pidgy basics¤
pidgy uses markdown as programming and document language.
it is designed for writing intermingling narrative and code.
be experimental. have fun.
# pidgy suppresses output when beginning with a blank line.
%reload_ext pidgy
shell.weave.reactive = False
shell.tangle.include_code_fences = ()
tangle markdown to python¤
a single Tab separates code and non-code in markdown.
a block of markdown illustrating the subtle difference between code blocks and non-code blocks.
# indented code block
# markdown heading
python and markdown have constrasting views of the #. in python, lines beginning with # are comments that are ignored. while in markdown, the # represent an <h1> which is a very meaningful element.1
the nearness between narrative and code allows for fluid transitions between literary and computational thinking. typically, in notebooks, narrative and code are separated by distinct cell boundaries.
#### setting markdown to variables
an early <abbr title="markdown and python pidgin syntax">markdonic hybird syntax you may use is sets markdown blocks as strings. everything in between code blocks is a big old block string.
<figure markdown>
<figcaption markdown>
a practical case for settings markdown to variables is very useful for collecting variables or lists of variables.
the outcome is demonstrated by `pidgy_links` below
</figcaption>
pidgy_links=\
* https://deathbeds.github.io/pidgy/
* https://github.com/pidgy/
</figure>
{% set block %}
my_variable_name = \
a markdown paragraph
{% endset %}
<figure markdown>
<figcaption markdown>
markdown input defined <code>my_variable_name</code> to a markdown paragraph.
during translation, line continuations are included to connect code blocks to markdown blocks.
</figcaption>
```markdown
{{block}}
```
</figure>
<figure>
<figcaption>the python translation of the markdown</figcaption>
```python
{{shell.tangle.render(block)}}
```
</figure>
setting markdown to variables¤
an early markdonic hybird syntax you may use is sets markdown blocks as strings. everything in between code blocks is a big old block string.
a practical case for settings markdown to variables is very useful for collecting variables or lists of variables.
the outcome is demonstrated by pidgy_links below
pidgy_links=\
markdown input defined my_variable_name to a markdown paragraph.
during translation, line continuations are included to connect code blocks to markdown blocks.
my_variable_name = \
a markdown paragraph
my_variable_name = \
\
"""a markdown paragraph""";
#### writing markdown docstrings
pidgy has heuristics for dealing nested blocks in python make it easy to write docstrings in markdown.
{% set block %}
my_variable_name = \
a markdown paragraph
class MyClass:
you bet this with classes.
def sub_function(self):
even inside of class methods!
return "🔥"
{% endset %}
##### docstrings in markdown
<figure>
<figcaption>
markdown input defined <code>my_variable_name</code> to a markdown paragraph.
during translation, line continuations are included to connect code blocks to markdown blocks.
</figcaption>
```markdown
{{block}}
```
</figure>
##### docstrings in python
<figure>
<figcaption>the python translation of the markdown</figcaption>
```python
{{shell.tangle.render(block)}}
```
</figure>
writing markdown docstrings¤
pidgy has heuristics for dealing nested blocks in python make it easy to write docstrings in markdown.
docstrings in markdown¤
my_variable_name to a markdown paragraph.
during translation, line continuations are included to connect code blocks to markdown blocks.
my_variable_name = \
a markdown paragraph
class MyClass:
you bet this with classes.
def sub_function(self):
even inside of class methods!
return "🔥"
docstrings in python¤
my_variable_name = \
\
"""a markdown paragraph"""
class MyClass:
"""you bet this with classes."""
def sub_function(self):
"""even inside of class methods!"""
return "🔥"
weave markdown to a display¤
jinja2 is a powerful templating engine in between markdown and python.
it lets authors include variables from their current namespace directly into a rich display; pidgy also reacts to changes and updates the display.
suppressing the display¤
start the cell with a blank line to suppress the woven display.
this is a quick way to suppress supporting code or imports that don't add directly to the narrative.
when a markdown begins with a blank line, `pidgy` will tangle & execute any code, but will not generate a display.
#### reactivity
`pidgy` is reactive out of the box; any [variables included in the display](#including-variables-in-the-display) are updated when values change during cell execution.
[learn more about reactivity and working with widgets](reactivity.ipynb)
reactivity¤
pidgy is reactive out of the box; any variables included in the display are updated when values change during cell execution.
learn more about reactivity and working with widgets
## learn more
learn more¤
-
web content accessibility guidelines recommend one and only one
<h1>on your page, the same should go for your markdown ↩