Feature Proposal: Generate guidance in Markdown format #99

New Issue

michael · 2026-01-19T18:29:13Z

michael commented

2026-01-19 18:29:13 +00:00

Originally created by @homebysix on GitHub.

Originally assigned to: @brodjieski on GitHub.

Problem to solve

mSCP currently produces PDF, HTML, AsciiDoc, and Excel formatted guidance, but does not produce Markdown guidance.

Intended users

Many organizations utilize documentation systems that require (or prefer) Markdown formatted files. Such systems include MkDocs, GitBook, GitHub Pages, Hugo, Jekyll, and Sphinx.

Further details

Expanding to Markdown formatted guidance might lower friction required for some organizations to adopt the mSCP with their existing systems and tools.

Proposal

Modifications to the generate_guidance.py script would include the capability to templatize and output Markdown formatted files, as it currently does for other supported formats.

Documentation

Updates to the Generate Guidance wiki page would reflect the inclusion of Markdown in the supported output formats for guidance files.

Testing

Whatever tests are included in generate_guidance.py would need to support testing the Markdown output capabilities.

What does success look like, and how can we measure that?

Acceptance criteria for this feature request includes:

generate_guidance.py produces Markdown formatted guidance files alongside currently supported formats
Documentation for generating guidance is updated to reflect Markdown as a supported output format

Links / references

Markdown Syntax Documentation | Daring Fireball

Originally created by @homebysix on GitHub. Originally assigned to: @brodjieski on GitHub. ### Problem to solve mSCP currently produces PDF, HTML, AsciiDoc, and Excel formatted guidance, but does not produce Markdown guidance. ### Intended users Many organizations utilize documentation systems that require (or prefer) Markdown formatted files. Such systems include MkDocs, GitBook, GitHub Pages, Hugo, Jekyll, and Sphinx. ### Further details Expanding to Markdown formatted guidance might lower friction required for some organizations to adopt the mSCP with their existing systems and tools. ### Proposal Modifications to the [generate_guidance.py](https://github.com/usnistgov/macos_security/blob/main/scripts/generate_guidance.py) script would include the capability to templatize and output Markdown formatted files, as it currently does for other supported formats. ### Documentation Updates to the [Generate Guidance](https://github.com/usnistgov/macos_security/wiki/Generate-Guidance) wiki page would reflect the inclusion of Markdown in the supported output formats for guidance files. ### Testing Whatever tests are included in [generate_guidance.py](https://github.com/usnistgov/macos_security/blob/main/scripts/generate_guidance.py) would need to support testing the Markdown output capabilities. ### What does success look like, and how can we measure that? Acceptance criteria for this feature request includes: - generate_guidance.py produces Markdown formatted guidance files alongside currently supported formats - Documentation for generating guidance is updated to reflect Markdown as a supported output format ### Links / references - [Markdown Syntax Documentation | Daring Fireball](https://daringfireball.net/projects/markdown/syntax)

michael closed this issue

2026-01-19 18:29:14 +00:00

michael commented

2026-01-19 18:29:14 +00:00

@brodjieski commented on GitHub:

Markdown output will be available in 2.0. The dev_2.0 branch has this function in place now for testing.

@brodjieski commented on GitHub: Markdown output will be available in 2.0. The `dev_2.0` branch has this function in place now for testing.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: usnistgov/macos_security#99