feat: add --markdown-tree paginated output for static site generators#700
Open
smithjw wants to merge 2 commits into
Open
feat: add --markdown-tree paginated output for static site generators#700smithjw wants to merge 2 commits into
--markdown-tree paginated output for static site generators#700smithjw wants to merge 2 commits into
Conversation
Adds mscp guidance --markdown-tree <baseline> (also included in --all),
which renders a baseline as a directory tree ready to drop into any
CommonMark-based static site generator — Docusaurus, Starlight, MkDocs,
VitePress, and similar.
Output shape:
build/<baseline>/markdown_tree/
index.md # overview — foreword, scope, authors
02-<section-slug>/
index.md # section description
01-<rule-slug>.md # one page per rule
...
Files are NN- prefixed for stable ordering (no sidebar config needed).
index.md follows the category-index convention recognised by Docusaurus
and Starlight. Frontmatter is minimal — title only — so it works across
generators without modification.
Content reuses markdown/rule.md.jinja via a markdown_tree context flag,
selecting heading-based Check/Remediation sections and a GFM pipe table
for references. The single-file --markdown output path is unchanged.
Manual-rule notes use > **Note:** blockquotes that render everywhere.
Also fixes a crash in adoc/rule.adoc.jinja when rule.references.hhs is
absent (rules predating the HICP framework).
Tests: 41 pytest tests covering mdx_escape, create_slug,
render_references_md, _frontmatter, and an integration test against a
real baseline asserting NN- ordering, balanced fences, no raw braces
outside fenced blocks, and valid frontmatter. Validated: 104/104
(cis_lvl1) and 168/168 (disa_stig) pages compile under @mdx-js/mdx v3.
Note: --markdown-tree has no short flag to avoid collision with
-m/--markdown.
The concatenated __all__ entry "PLATFORM_MAPvalidate_yaml_file" made pyflakes miss both names as exports, so it reported their imports as unused (F401). Splitting it fixes both. Also import CONFIG_PATH so its existing __all__ entry resolves, drop unused BaseModel/config imports, and clean blank-line whitespace in scap.py.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
mscp guidance --markdown-tree <baseline>(also included in--all), which renders a baseline as a directory tree ready to drop into any CommonMark-based static site generator - Docusaurus, Starlight, MkDocs, VitePress, etc.Output:
Files are NN- prefixed for stable ordering (no sidebar config needed in the case of Docusaurus).
index.mdfollows the category-index convention recognised by Docusaurus and Starlight. Frontmatter is minimal — title only — so it should work across generators wit minimal modification needed.Content reuses markdown/rule.md.jinja via a markdown_tree context flag, selecting heading-based Check/Remediation sections and a GFM pipe table for references. The single-file
--markdownoutput path is left as-is.Also fixes a crash in adoc/rule.adoc.jinja when rule.references.hhs is absent (rules predating the HICP framework).
Tests:
41 pytest tests covering mdx_escape, create_slug, render_references_md, _frontmatter, and an integration test against a real baseline asserting NN- ordering, balanced fences, no raw braces outside fenced blocks, and valid frontmatter. Validated: 104/104 (cis_lvl1) and 168/168 (disa_stig) pages compile under @mdx-js/mdx v3.
Note:
--markdown-treehas no short flag to avoid collision with-m/--markdown