Skip to content

Instantly share code, notes, and snippets.

@commonquail

commonquail/mdpp.md

Last active August 28, 2015 04:38
Show Gist options
  • Star 0 You must be signed in to star a gist
  • Fork 0 You must be signed in to fork a gist
  • Save commonquail/db984356e1927379dc17 to your computer and use it in GitHub Desktop.
Save commonquail/db984356e1927379dc17 to your computer and use it in GitHub Desktop.
Download ZIP
Idea for a Markdown preprocessor
Raw
mdpp.md

Idea for a Markdown preprocessor

Feature master list:

  • Table of contents
    • {{toc}}?
    • ATX headers
    • two-pass processing for consistent stream
    • Ignore # in code blocks, quotes
  • File transclusion
    • {{file path}}?
    • Warn on missing or unreadable file
    • Before ToC, to get all headers
    • Recursion: warn, error, proceed?
    • Specify or derive file type?
    • Descend-only?
    • Allow in code? Yes; how else to document? Escaping required.

Considerations

Setext header support

Almost certainly not. Setext headers are basically a mistake best forgotten about.

File type

The source file is something more than Markdown. It can be trivially kept Markdown, with no further support for ("illegitimate") extensions.

Consistency

Is it more valuable to remain consistent with Markdown or to deliberately and obviously deviate?

The former produces a consistent result, the advantages of which need no qualification.

The latter does the opposite, which can be helpful to:

  1. emphasise that this is not plain Markdown; and
  2. prevent breaking existing compliant parsers.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment