NotepadMD is a Markdown editor first and a rich UI second. Our goal is to keep the raw file readable, portable, and as close to standard Markdown as possible, even when the editor offers higher-level controls.
Our Markdown Philosophy
We prefer Markdown-first notation over HTML-first notation.
- Raw files should stay readable in any text editor.
- Round-tripping through the editor should preserve intent instead of introducing noisy markup.
- Extensions should look like natural Markdown when possible.
- HTML should be a compatibility escape hatch, not the default way to author features.
Standards And Compatibility
NotepadMD is built on a CommonMark baseline for core Markdown parsing and serialization.
CommonMark
For headings, paragraphs, emphasis, links, blockquotes, lists, fenced code blocks, thematic breaks, and the other core building blocks of Markdown, our starting point is CommonMark behavior. When we choose between a convenient shortcut and a CommonMark-compatible result, we aim to preserve CommonMark-compatible output.
GitHub Flavored Markdown
We intend to support GitHub Flavored Markdown where it improves real-world authoring without making raw documents harder to read. That includes practical extensions such as pipe tables, task lists, strikethrough, and other widely understood authoring patterns.
Pandoc Markdown
We also aim to be as compatible with Pandoc Markdown as we can when that compatibility still fits our Markdown-first design goals. Pandoc is a very important tool in the Markdown ecosystem, so we try to avoid drifting away from syntax that is already familiar to Pandoc users unless there is a strong readability reason to do so.
NotepadMD-Specific Cases
Some features need extra notation that is not part of baseline CommonMark. When we add these cases, we try to keep the syntax compact, descriptive, and close to existing Markdown conventions.
Review Comments
Review comments are stored in a CriticMarkup-inspired format so they remain visible and understandable in the raw file.
Inline marked text uses this format:
{> [comment-id="c1"] selected text <}
The corresponding comment metadata uses this format:
{>> [REVIEW comment-id="c1" time="2026-03-13T12:00:00Z" author="Reviewer" quote="selected text"] Please tighten this wording. <<}
This is intentionally Markdown-adjacent rather than HTML-based. At runtime the editor may render comment marks with richer UI, but the persisted file format stays textual and reviewable.
Page Breaks
Our canonical page break notation is:
--- {.page-break}
This keeps page breaks close to standard thematic-break syntax instead of requiring an HTML block by default.
We also recognize the widely used legacy HTML page-break hack:
<div style="page-break-before:always"> </div>
That means NotepadMD can interoperate with documents that already use the HTML approach, but our preferred storage format is the attribute-based Markdown form above.
We are aware that some Pandoc workflows use LaTeX commands such as these:
\newpage
\pagebreak
We do not treat those as NotepadMD page-break syntax because they are TeX commands rather than Markdown notation.
Table Column Widths
NotepadMD supports a table column-width extension so resized tables can preserve layout information in the raw file.
Example:
| Feature | Notes |
| :--- | :--- |
| Tables | Widths persist | {: col-widths="30,70" }
The outer {: ... } wrapper follows the attribute-list style used by Markdown tooling that understands generic attributes. The specific col-widths property is a NotepadMD extension that stores percentage widths for each column.
This gives us a Markdown-shaped way to persist presentation hints without falling back to HTML tables or inline CSS as the default representation.
HTML In Markdown
Markdown allows embedded HTML, and NotepadMD will continue to read documents that contain it. But our general design goal is to avoid making HTML the default representation of an editing feature.
HTML is harder to skim in raw documents, harder to diff, and more disruptive to the plain-text reading experience. Where we can express a feature as readable Markdown or a small Markdown-style extension, we prefer that route.
Compatibility Promise
NotepadMD is not trying to invent a private Markdown dialect. Our approach is:
- stay grounded in CommonMark,
- support practical GFM behavior,
- remain as compatible with Pandoc-style authoring as we reasonably can, and
- keep any NotepadMD-specific syntax small, explicit, and human-readable.
That principle guides how we evaluate every new Markdown feature we add.
Tables Of Contents
NotepadMD recognises four equivalent TOC marker aliases on a single line. They all expand to the same live navigation block in the editor:
[TOC]
[[TOC]]
[[_TOC_]]
<!-- toc -->
A depth range may be appended (defaults to 1–6 when omitted):
[TOC:2-4]
[[_TOC_:2]]
The configuration modal preserves whichever alias you originally typed when it rewrites the marker.
Scoped TOCs
A TOC marker placed immediately under a heading scopes itself to that heading's subtree (issue #566 SG-1). When the marker is removed from the immediate-following position — for example, by inserting a paragraph between the heading and the marker — the TOC silently falls back to a document-wide listing rather than going blank. This is intentional: the marker is data, not configuration; we choose continuity over surprise.