diff --git a/.metadock/content_schematics/jinja_helpers/global.yml b/.metadock/content_schematics/jinja_helpers/global.yml index dcf5aeb..06bf6a6 100644 --- a/.metadock/content_schematics/jinja_helpers/global.yml +++ b/.metadock/content_schematics/jinja_helpers/global.yml @@ -1,8 +1,23 @@ global: - info: | - The global namespace contains helpful macros and filters for manipulating data in the Jinja - context. It also provides access to more specific namespaces through their respective identifiers, - such as `md` and `html`. + docstring: | + Jinja namespace for the global Metadock environment, including all global exports, filters, and namespaces. + + **Macros**: + + debug + + **Namespaces**: + + html + md + + **Filters**: + + chain + inline + with_prefix + with_suffix + zip macros: debug: diff --git a/.metadock/content_schematics/jinja_helpers/html.yml b/.metadock/content_schematics/jinja_helpers/html.yml index 46ac1e4..2c9131c 100644 --- a/.metadock/content_schematics/jinja_helpers/html.yml +++ b/.metadock/content_schematics/jinja_helpers/html.yml @@ -1,4 +1,22 @@ html: + docstring: | + Jinja namespace which owns HTML-related functions and filters. + + **Macros**: + + bold + code + codeblock + details + italic + summary + underline + + **Filters**: + + escape + inline + macros: bold: docstring: | @@ -97,3 +115,52 @@ html: snippet_key: HTML summary snippet_body: - html.summary($1) + + underline: + docstring: | + Wraps a string in HTML underline tags (). + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string("{{ html.underline('This is underlined text.') }}").render() + 'This is underlined text.' + source_file: metadock/env.py + method_name: metadock.env.MetadockHtmlNamespace.underline + signature: "(self, content: str) -> str" + intellisense: + snippet_key: HTML underline + snippet_body: + - html.underline($1) + + filters: + escape: + docstring: | + Filter which escapes a string by replacing all HTML special characters with their HTML entity equivalents. + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string("{{ '

This is a paragraph.

' | html.escape }}").render() + '<p>This is a paragraph.</p>' + source_file: metadock/env.py + method_name: metadock.env.MetadockHtmlNamespace.escape_filter + signature: "(self, content: str) -> str" + intellisense: + snippet_key: HTML escape + snippet_body: + - html.escape + + inline: + docstring: | + Filter which inlines a string by replacing all newlines with HTML line-breaks
singleton tags. + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string("{{ 'This is a multi-line string.\nThis is the second line.\nAnd the third.' | html.inline }}").render() + 'This is a multi-line string.
This is the second line.
And the third.' + source_file: metadock/env.py + method_name: metadock.env.MetadockHtmlNamespace.inline_filter + signature: "(self, content: str) -> str" + intellisense: + snippet_key: HTML inline + snippet_body: + - html.inline diff --git a/.metadock/content_schematics/jinja_helpers/md.yml b/.metadock/content_schematics/jinja_helpers/md.yml index 16a0c7c..b3f3f12 100644 --- a/.metadock/content_schematics/jinja_helpers/md.yml +++ b/.metadock/content_schematics/jinja_helpers/md.yml @@ -1,4 +1,162 @@ md: - macros: {} + docstring: | + Jinja Namespace for Markdown-related functions and filters. - filters: {} + **Macros**: + + blockquote + code + codeblock + list + tablehead + tablerow + + **Filters**: + + convert + list + + macros: + blockquote: + docstring: | + Produces a Markdown blockquote from the given content by prepending each line with a gt symbol ("> "). + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string("{{ md.blockquote('This is a blockquote.') }}").render() + '> This is a blockquote.' + source_file: metadock/env.py + method_name: metadock.env.MetadockMdNamespace.blockquote + signature: "(self, content: str) -> str" + intellisense: + snippet_key: Markdown blockquote + snippet_body: + - md.blockquote($1) + + code: + docstring: | + Produces a Markdown inline code block from the given content by wrapping the string in graves ("\`"). + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string("{{ md.code('This is an inline code block.') }}").render() + '`This is an inline code block.`' + source_file: metadock/env.py + method_name: metadock.env.MetadockMdNamespace.code + signature: "(self, content: str) -> str" + intellisense: + snippet_key: Markdown inline code + snippet_body: + - md.code($1) + + codeblock: + docstring: | + Produces a Markdown codeblock from the given content by wrapping the string in triple-graves ("\`\`\`"), + and optionally specifies a language. + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string("{{ md.codeblock('This is a codeblock.', language = 'sh') }}").render() + '```sh\nThis is a codeblock.\n```' + source_file: metadock/env.py + method_name: metadock.env.MetadockMdNamespace.codeblock + signature: "(self, content: str, language: str = '') -> str" + intellisense: + snippet_key: Markdown codeblock + snippet_body: + - md.codeblock($1) + + list: + docstring: | + Produces a Markdown list from the given content by prepending each line with a dash ("- "). If any of its + arguments are, themselves, formatted as Markdown lists, then they are simply indented as sublists. + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string( + ... "{{ md.list('This is a list.', md.list('This is a sublist,', 'in two pieces.')) }}" + ... ).render() + '- This is a list.\n - This is a sublist,\n - in two pieces.' + source_file: metadock/env.py + method_name: metadock.env.MetadockMdNamespace.list + signature: "(self, *items: str) -> str" + intellisense: + snippet_key: Markdown list + snippet_body: + - md.list($1) + + tablehead: + docstring: | + Produces a Markdown table header from the given cells by joining each cell with pipes ("|") and wrapping the + result in pipes, plus adding a header divider row. Cell contents have their pipes escaped with a backslash + ("\\"). To bold the header cell contents, supply `bold = true`. + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string( + ... "{{ md.tablehead('Column 1', 'Column 2', 'Column 3', bold = true) }}" + ... ).render() + '| Column 1 | Column 2 | Column 3 |\n| --- | --- | --- |' + source_file: metadock/env.py + method_name: metadock.env.MetadockMdNamespace.tablehead + signature: "(self, *header_cells: str, bold: bool = False) -> str" + intellisense: + snippet_key: Markdown table head + snippet_body: + - md.tablehead($1) + + tablerow: + docstring: | + Produces a Markdown table row from the given cells by joining each cell with pipes ("|") and wrapping the + result in pipes. Cell contents have their pipes escaped with a backslash ("\\"). + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string( + ... "{{ md.tablehead('Column 1', 'Column 2', 'Column 3') }}\n" + ... "{{ md.tablerow('Value 1', 'Value 2', 'Value 3') }}" + ... ).render() + '| Column 1 | Column 2 | Column 3 |\n| --- | --- | --- |\n| Value 1 | Value 2 | Value 3 |' + source_file: metadock/env.py + method_name: metadock.env.MetadockMdNamespace.tablerow + signature: "(self, *row_cells: str) -> str" + intellisense: + snippet_key: Markdown table row + snippet_body: + - md.tablerow($1) + + filters: + convert: + docstring: | + Filter which converts Markdown content to HTML, by invoking `marko.convert`. + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string("{{ '# This is a heading\n\n> And a block quote.' | md.convert }}").render() + '

This is a heading

\n
\n

And a block quote.

\n
\n' + source_file: metadock/env.py + method_name: metadock.env.MetadockMdNamespace.convert_filter + signature: "(self, md_content: str) -> str" + intellisense: + snippet_key: Markdown convert + snippet_body: + - md.convert($1) + + list: + docstring: | + Filter which unpacks an iterable of values into a Markdown list, or formats a single value as a Markdown list + element. + example: | + >>> from metadock.env import MetadockEnv + >>> env = MetadockEnv().jinja_environment() + >>> env.from_string( + ... "{{ ['This is a list.', 'This is a second element'] | md.list }}\n" + ... ).render() + '- This is a list.\n- This is a second element\n' + source_file: metadock/env.py + method_name: metadock.env.MetadockMdNamespace.list_filter + signature: "(self, values: str | Iterable[str]) -> str" + intellisense: + snippet_key: Markdown list + snippet_body: + - md.list diff --git a/.metadock/generated_documents/README.html b/.metadock/generated_documents/README.html index be69dc9..bc6ba97 100644 --- a/.metadock/generated_documents/README.html +++ b/.metadock/generated_documents/README.html @@ -249,9 +249,21 @@

Jinja Templating Helpers

and filters which can be used to make formatting content easier. The macros and filters are segregated into 3 namespaces, documented below:

Global namespace

-

The global namespace contains helpful macros and filters for manipulating data in the Jinja -context. It also provides access to more specific namespaces through their respective identifiers, -such as md and html.

+

Jinja namespace for the global Metadock environment, including all global exports, filters, and namespaces.

+

Macros:

+
debug
+
+

Namespaces:

+
html
+md
+
+

Filters:

+
chain
+inline
+with_prefix
+with_suffix
+zip
+
Jinja macro reference @@ -311,7 +323,19 @@

Global namespace

md namespace

-

None

+

Jinja Namespace for Markdown-related functions and filters.

+

Macros:

+
blockquote
+code
+codeblock
+list
+tablehead
+tablerow
+
+

Filters:

+
convert
+list
+
Jinja macro reference @@ -323,7 +347,39 @@

md namespace

Signature Doc -
+ + + +md.blockquote +metadock.env.MetadockMdNamespace.blockquote: (self, content: str) -> str +Produces a Markdown blockquote from the given content by prepending each line with a gt symbol ("> "). 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string("{{ md.blockquote('This is a blockquote.') }}").render()
'> This is a blockquote.'

+ + +md.code +metadock.env.MetadockMdNamespace.code: (self, content: str) -> str +Produces a Markdown inline code block from the given content by wrapping the string in graves ("`"). 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string("{{ md.code('This is an inline code block.') }}").render()
'`This is an inline code block.`'

+ + +md.codeblock +metadock.env.MetadockMdNamespace.codeblock: (self, content: str, language: str = '') -> str +Produces a Markdown codeblock from the given content by wrapping the string in triple-graves ("```"), and optionally specifies a language. 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string("{{ md.codeblock('This is a codeblock.', language = 'sh') }}").render()
'sh\nThis is a codeblock.\n'

+ + +md.list +metadock.env.MetadockMdNamespace.list: (self, *items: str) -> str +Produces a Markdown list from the given content by prepending each line with a dash ("- "). If any of its arguments are, themselves, formatted as Markdown lists, then they are simply indented as sublists. 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string(
...     "{{ md.list('This is a list.', md.list('This is a sublist,', 'in two pieces.')) }}"
... ).render()
'- This is a list.\n  - This is a sublist,\n  - in two pieces.'

+ + +md.tablehead +metadock.env.MetadockMdNamespace.tablehead: (self, *header_cells: str, bold: bool = False) -> str +Produces a Markdown table header from the given cells by joining each cell with pipes ("|") and wrapping the result in pipes, plus adding a header divider row. Cell contents have their pipes escaped with a backslash ("\"). To bold the header cell contents, supply bold = true. 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string(
...     "{{ md.tablehead('Column 1', 'Column 2', 'Column 3', bold = true) }}"
... ).render()
'| <b>Column 1</b> | <b>Column 2</b> | <b>Column 3</b> |\n| --- | --- | --- |'

+ + +md.tablerow +metadock.env.MetadockMdNamespace.tablerow: (self, *row_cells: str) -> str +Produces a Markdown table row from the given cells by joining each cell with pipes ("|") and wrapping the result in pipes. Cell contents have their pipes escaped with a backslash ("\"). 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string(
...     "{{ md.tablehead('Column 1', 'Column 2', 'Column 3') }}\n"
...     "{{ md.tablerow('Value 1', 'Value 2', 'Value 3') }}"
... ).render()
'| Column 1 | Column 2 | Column 3 |\n| --- | --- | --- |\n| Value 1 | Value 2 | Value 3 |'

+ +
Jinja filter reference @@ -335,9 +391,34 @@

md namespace

Signature Doc -
+ + + +md.convert +metadock.env.MetadockMdNamespace.convert_filter: (self, md_content: str) -> str +Filter which converts Markdown content to HTML, by invoking marko.convert. 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string("{{ '# This is a heading\n\n> And a block quote.' | md.convert }}").render()
'<h1>This is a heading</h1>\n<blockquote>\n<p>And a block quote.</p>\n</blockquote>\n'

+ + +md.list +metadock.env.MetadockMdNamespace.list_filter: (self, values: str | Iterable[str]) -> str +Filter which unpacks an iterable of values into a Markdown list, or formats a single value as a Markdown list element. 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string(
...     "{{ ['This is a list.', 'This is a second element'] | md.list }}\n"
... ).render()
'- This is a list.\n- This is a second element\n'

+ +

html namespace

-

None

+

Jinja namespace which owns HTML-related functions and filters.

+

Macros:

+
bold
+code
+codeblock
+details
+italic
+summary
+underline
+
+

Filters:

+
escape
+inline
+
Jinja macro reference @@ -381,6 +462,11 @@

html namespace

metadock.env.MetadockHtmlNamespace.summary: (self, content: str) -> str Wraps a string in line-broken HTML summary tags (<summary>\n\n</summary>). 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string("{{ html.summary('This is summary text.') }}").render()
'<summary>\nThis is summary text.\n</summary>'

+ +html.underline +metadock.env.MetadockHtmlNamespace.underline: (self, content: str) -> str +Wraps a string in HTML underline tags (<u></u>). 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string("{{ html.underline('This is underlined text.') }}").render()
'<u>This is underlined text.</u>'

+
@@ -393,7 +479,19 @@

html namespace

Signature Doc -
+ + + +html.escape +metadock.env.MetadockHtmlNamespace.escape_filter: (self, content: str) -> str +Filter which escapes a string by replacing all HTML special characters with their HTML entity equivalents. 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string("{{ '<p>This is a paragraph.</p>' | html.escape }}").render()
'&lt;p&gt;This is a paragraph.&lt;/p&gt;'

+ + +html.inline +metadock.env.MetadockHtmlNamespace.inline_filter: (self, content: str) -> str +Filter which inlines a string by replacing all newlines with HTML line-breaks <br> singleton tags. 

>>> from metadock.env import MetadockEnv
>>> env = MetadockEnv().jinja_environment()
>>> env.from_string("{{ 'This is a multi-line string.\nThis is the second line.\nAnd the third.' | html.inline }}").render()
'This is a multi-line string.<br>This is the second line.<br>And the third.'

+ +

Acknowledgements

Author: