mkdocs-techdocs-frontmatter 0.1.0__py3-none-any.whl

mkdocs_techdocs_frontmatter/__init__.py

@@ -0,0 +1,171 @@
+import html
+import json
+from typing import Any
+
+import yaml
+from markdown.extensions import Extension
+from markdown.preprocessors import Preprocessor
+
+
+def _stringify(value: Any) -> str:
+    if value is None:
+        return ""
+    if isinstance(value, bool):
+        return "Yes" if value else "No"
+    if isinstance(value, (list, tuple)):
+        return ", ".join(_stringify(entry) for entry in value if _stringify(entry))
+    if isinstance(value, dict):
+        return json.dumps(value, default=str, ensure_ascii=False)
+    return str(value)
+
+
+def _default_label(key: str) -> str:
+    return key.replace("_", " ").replace("-", " ").title()
+
+
+def _as_bool(value: Any, default: bool) -> bool:
+    if isinstance(value, bool):
+        return value
+
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in ("true", "yes", "1", "on"):
+            return True
+        if normalized in ("false", "no", "0", "off"):
+            return False
+
+    return default
+
+
+def _render_key(options: dict[str, Any]) -> str:
+    return options.get("render_key") or "techdocs_frontmatter_render"
+
+
+def _should_render(metadata: dict[str, Any], options: dict[str, Any]) -> bool:
+    default_render = _as_bool(options.get("render"), True)
+    render_key = _render_key(options)
+
+    if render_key in metadata:
+        return _as_bool(metadata[render_key], default_render)
+
+    return default_render
+
+
+def _select_items(metadata: dict[str, Any], options: dict[str, Any]) -> list[tuple[str, str, str]]:
+    include = options.get("include") or metadata.keys()
+    exclude = set(options.get("exclude") or [])
+    labels = options.get("labels") or {}
+    if options.get("exclude_render_key", True):
+        exclude.add(_render_key(options))
+    items = []
+
+    for key in include:
+        if key in exclude or key not in metadata:
+            continue
+
+        value = _stringify(metadata[key])
+        if not value:
+            continue
+
+        items.append((key, labels.get(key) or _default_label(key), value))
+
+    return items
+
+
+def _render_metadata(metadata: dict[str, Any], options: dict[str, Any]) -> list[str]:
+    items = _select_items(metadata, options)
+    if not items:
+        return []
+
+    title = options.get("title") or "Article metadata"
+    render = _should_render(metadata, options)
+    payload = json.dumps(
+        {key: value for key, _label, value in items},
+        ensure_ascii=False,
+    )
+    if not render:
+        lines = [
+            '<div hidden data-techdocs-frontmatter data-techdocs-frontmatter-render="false">',
+            f'  <code hidden data-techdocs-frontmatter-json>{html.escape(payload)}</code>',
+            f'  <span>{html.escape(title)}</span>',
+        ]
+
+        for _key, label, value in items:
+            lines.append(f'  <span>{html.escape(label)}: {html.escape(value)}</span>')
+
+        lines.extend(['</div>', ''])
+        return lines
+
+    lines = [
+        f'<aside class="techdocs-frontmatter" data-techdocs-frontmatter aria-label="{html.escape(title)}">',
+        f'  <code hidden data-techdocs-frontmatter-json>{html.escape(payload)}</code>',
+        f'  <p class="techdocs-frontmatter__heading">{html.escape(title)}</p>',
+        '  <dl class="techdocs-frontmatter__list">',
+    ]
+
+    for key, label, value in items:
+        lines.extend(
+            [
+                f'    <div class="techdocs-frontmatter__row" data-techdocs-frontmatter-key="{html.escape(key)}">',
+                f'      <dt>{html.escape(label)}</dt>',
+                f'      <dd>{html.escape(value)}</dd>',
+                '    </div>',
+            ],
+        )
+
+    lines.extend(['  </dl>', '</aside>', ''])
+    return lines
+
+
+class FrontmatterMetadataPreprocessor(Preprocessor):
+    def __init__(self, options: dict[str, Any]) -> None:
+        super().__init__()
+        self.options = options
+
+    def run(self, lines: list[str]) -> list[str]:
+        if not lines or lines[0].strip() != '---':
+            return lines
+
+        end_index = next(
+            (
+                index
+                for index, line in enumerate(lines[1:], start=1)
+                if line.strip() in ('---', '...')
+            ),
+            None,
+        )
+        if end_index is None:
+            return lines
+
+        metadata = yaml.safe_load('\n'.join(lines[1:end_index])) or {}
+        if not isinstance(metadata, dict):
+            return lines
+
+        metadata_lines = _render_metadata(metadata, self.options)
+        if not metadata_lines:
+            return lines
+
+        return lines[: end_index + 1] + metadata_lines + lines[end_index + 1 :]
+
+
+class FrontmatterMetadataExtension(Extension):
+    config = {
+        'title': ['Article metadata', 'Title shown above rendered frontmatter metadata.'],
+        'render': [True, 'Whether to visibly render the metadata block in generated documentation.'],
+        'render_key': ['techdocs_frontmatter_render', 'Frontmatter key that can override whether metadata is rendered for one page.'],
+        'exclude_render_key': [True, 'Whether to omit the render control key from emitted/indexed frontmatter metadata.'],
+        'include': [None, 'Only render these frontmatter keys, in this order.'],
+        'exclude': [None, 'Hide these frontmatter keys.'],
+        'labels': [{}, 'User-facing labels for frontmatter keys.'],
+    }
+
+    def extendMarkdown(self, md):
+        md.preprocessors.register(
+            FrontmatterMetadataPreprocessor(self.getConfigs()),
+            'frontmatter_metadata',
+            100,
+        )
+
+
+def makeExtension(**kwargs):
+    return FrontmatterMetadataExtension(**kwargs)

mkdocs_techdocs_frontmatter/plugin.py

@@ -0,0 +1,28 @@
+from typing import Any
+
+from mkdocs.config import config_options
+from mkdocs.plugins import BasePlugin
+
+from mkdocs_techdocs_frontmatter import _render_metadata
+
+
+class TechDocsFrontmatterPlugin(BasePlugin):
+    config_scheme = (
+        ('title', config_options.Type(str, default='Article metadata')),
+        ('render', config_options.Type(bool, default=True)),
+        ('render_key', config_options.Type(str, default='techdocs_frontmatter_render')),
+        ('exclude_render_key', config_options.Type(bool, default=True)),
+        ('include', config_options.Type(list, default=[])),
+        ('exclude', config_options.Type(list, default=[])),
+        ('labels', config_options.Type(dict, default={})),
+    )
+
+    def on_page_markdown(self, markdown: str, page: Any, config: Any, files: Any) -> str:
+        metadata = getattr(page, 'meta', None) or {}
+        metadata_lines = _render_metadata(metadata, self.config)
+
+        if not metadata_lines:
+            return markdown
+
+        rendered = '\n'.join(metadata_lines)
+        return f"{rendered}\n{markdown}"

mkdocs_techdocs_frontmatter-0.1.0.dist-info/METADATA

@@ -0,0 +1,62 @@
+Metadata-Version: 2.4
+Name: mkdocs-techdocs-frontmatter
+Version: 0.1.0
+Summary: Python-Markdown extension that renders TechDocs page frontmatter as searchable metadata.
+Author: Gijs Reijn
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/Gijsreyn/backstage-plugin-techdocs-addon-frontmatter
+Project-URL: Repository, https://github.com/Gijsreyn/backstage-plugin-techdocs-addon-frontmatter
+Project-URL: Issues, https://github.com/Gijsreyn/backstage-plugin-techdocs-addon-frontmatter/issues
+Keywords: mkdocs,mkdocs-plugin,techdocs,backstage,frontmatter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Documentation
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Markdown>=3.4
+Requires-Dist: mkdocs>=1.6
+Requires-Dist: PyYAML>=6.0
+Dynamic: license-file
+
+# mkdocs-techdocs-frontmatter
+
+A [MkDocs](https://www.mkdocs.org/) plugin that emits YAML frontmatter from
+Markdown pages as visible, indexable metadata during TechDocs generation.
+
+Companion to the
+[`backstage-plugin-techdocs-addon-frontmatter`](https://github.com/Gijsreyn/backstage-plugin-techdocs-addon-frontmatter)
+Backstage TechDocs addon. See the repository README for full usage,
+configuration, and integration with Backstage search.
+
+## Install
+
+```sh
+pip install mkdocs-techdocs-frontmatter
+```
+
+## Enable
+
+```yaml
+# mkdocs.yml
+plugins:
+  - techdocs-core
+  - techdocs-frontmatter:
+      title: Article metadata
+      render: true
+      include: [type, author, last_review_date]
+      labels:
+        type: Type
+        author: Author
+        last_review_date: Last reviewed
+```
+
+## License
+
+MIT

mkdocs_techdocs_frontmatter-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+mkdocs_techdocs_frontmatter/__init__.py,sha256=PPSv-uUDRk726oW3PzboAyayv_1C71t9dscghkMGtg8,5768
+mkdocs_techdocs_frontmatter/plugin.py,sha256=oLdEp9YQR5bSlowOQ3cfl3qn3SHIfLv5vhS5zeaQ7B8,1093
+mkdocs_techdocs_frontmatter-0.1.0.dist-info/licenses/LICENSE,sha256=THGwJ7J29LE4sRhrjozYO_6a_Tsi8c0UlyA2R7ZD4Io,1088
+mkdocs_techdocs_frontmatter-0.1.0.dist-info/METADATA,sha256=bGQ9YdxvGiREMhRmGCyDq1YXGO8AApAvt1IjCqeoFYU,2051
+mkdocs_techdocs_frontmatter-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+mkdocs_techdocs_frontmatter-0.1.0.dist-info/entry_points.txt,sha256=N-F9CTzD3WL-Gmp_MQJI9j_9VENZRHvSjR1xQiBTQmI,101
+mkdocs_techdocs_frontmatter-0.1.0.dist-info/top_level.txt,sha256=NzSwGVDW2uJ_kpm9phehbW4gwGtR3zHK2XYKC7SPDFU,28
+mkdocs_techdocs_frontmatter-0.1.0.dist-info/RECORD,,

mkdocs_techdocs_frontmatter-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mkdocs_techdocs_frontmatter-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[mkdocs.plugins]
+techdocs-frontmatter = mkdocs_techdocs_frontmatter.plugin:TechDocsFrontmatterPlugin

mkdocs_techdocs_frontmatter-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gijs Reijn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mkdocs_techdocs_frontmatter-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mkdocs_techdocs_frontmatter