fleshing out jinja helper metadocks

.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:

.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 (<u></u>).
+      example: |
+        >>> 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>'
+      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("{{ '<p>This is a paragraph.</p>' | html.escape }}").render()
+        '&lt;p&gt;This is a paragraph.&lt;/p&gt;'
+      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 <br> 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.<br>This is the second line.<br>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

.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()
+        '| <b>Column 1</b> | <b>Column 2</b> | <b>Column 3</b> |\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()
+        '<h1>This is a heading</h1>\n<blockquote>\n<p>And a block quote.</p>\n</blockquote>\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