PNPMD Markdown specification — PNPMD v1.0.4

Max Freet, An M. Rodriguez, Adrien Hale

Preferred Frame — November 2025

Markdown · PDF · Preprocessed MD

One-Sentence Summary

PNPMD is a specification for human-readable-*first*, plain-text, math-aware, markdown documents.

Abstract

PNPMD is a specification for human-readable-*first*, plain-text, math-aware documents. PNPMD honors Pandoc's flavored markdown, rendered with pdflatex. Uses Pandoc's crossref filter (giving numbered and referenceable equations, figures, tables, etc), and adds some syntax sugar to ease cross-referencing and citations.

Files

• The PNP Markdown Standard - PNPMDv1.html
• The PNP Markdown Standard - PNPMDv1.md
• provenance.yaml
• PDF

Article

1 One-Sentence Summary

PNPMD is a specification for human-readable-first, plain-text, math-aware, markdown documents.

2 Abstract

PNPMD is a specification for human-readable-first, plain-text, math-aware documents. PNPMD honors Pandoc’s flavored markdown, rendered with pdflatex. Uses Pandoc’s crossref filter (giving numbered and referenceable equations, figures, tables, etc), and adds some syntax sugar to ease cross-referencing and citations.

3 Keywords

plain-text, research format, markdown, mathjax, pandoc, PNPMD

4 Introduction

PNPMD is a specification for human-readable-first, plain-text, math-aware, markdown documents.

PNPMD:

• provides a complete Markdown structure for mathematically aware documents, with cross-references and citations,
• keeps the format plain-text and human-readable-first, and
• avoids noisy LaTeX wrappers and PDF-only workflows

5 (Suggested) Structure

• Header
• One-Sentence Summary
• Abstract
• Keywords
• Other body sections
• About Author(s)
• References

5.1 Header

Three lines:

% Title
% Author(s)
% Date

5.2 One-Sentence Summary

One sentence summarizing the paper.

5.3 Abstract

3–5 sentences: problem → method → result → significance.

No citations or equations.

5.4 Keywords

3–6 topical keywords.

5.5 Other Body Sections (Recommended)

Introduction, Theory/Framework, Derivation, Results, Discussion, Conclusion, Future Work, Appendices.

5.6 About Author(s)

Immediately before References.

A list of authors, with ORCID if available, email if corresponding, or relevant information.

For example,

• An M. Rodriguez, https://orcid.org/0009-0009-9098-9468, an@preferredframe.com
• Max Freet, max@preferredframe.com

5.7 References

Use DOI links where possible.

6 References and Cross-References

Cross-linking, numbering, and citations are produced automatically by Pandoc with the pandoc-crossref filter.

7 Cross-Reference System and Sugar Substitutions

When using the PNPMD rendering script, several syntactic sugars are automatically expanded to Pandoc-compatible links:

• {#id} → []{#id}: For plain prose anchors (no colon).

• @id → [label](#id): If a [label]{#id} exists

  • @id → [@id](#id): otherwise

• [label](@id) → [label](#id): Always.

• [label](@sec:id) → [label](#sec:id): Always.

• @sec:, @fig:, @eq:, @tbl: → (unchanged): Handled by pandoc-crossref.

• bare #id → [](#id): When not inside code blocks, headings, or existing links.

Colon-prefixed anchors (e.g., {#eq:wave}) are reserved for cross-reference numbering and remain untouched.

8 Formatting Rules

8.1 Math

• Inline math: $...$ (e.g., $E = mc^2$)
• Display math:

$$
F_{\mu\nu} = \partial_\mu A_\nu - \partial_\nu A_\mu
$$ {#eq:sampleeq}

renders as:

F_μν = ∂_μA_ν − ∂_νA_μ   (1)

And can be referenced as @eq:sampleeq, like so:

See eq. 1

• Do not use \[...\] or \(...\)
• Always specify units (SI preferred)

8.2 Characters

• UTF-8 required (pdflatex-compatible)
• Unicode symbols allowed only if supported by pdfLaTeX input; otherwise prefer $...$ or ASCII

8.3 Text Emphasis

Avoid bold/italics/underline unless essential.

Clarity is primary. Don’t pollute the document with unnecessary visual noise.

8.4 Section Separation

• Separate sections with two blank lines
• Never use --- (horizontal rules) to separate sections
• Do not number sections manually; Pandoc handles numbering automatically

9 Conclusion

PNPMD is a plain-text specification for mathematically aware documents.

It standardizes minimal syntax, automatic cross-referencing, and deterministic conversion through Pandoc with pandoc-crossref.

The format remains simple, portable, and human-readable.

PNPMD: where notation and meaning remain human before machine.

10 Corresponding Author

An M. Rodriguez: an@preferredframe.com