v0.19.0

npm install -g monodocs

0.19.0 adds a fourth view of the difference from an earlier version, one column with the deleted blocks written back where they stood, and a key choosing the view a document opens in. It also brings the Japanese UI labels back under lang: ja, but for Generated by.

Nothing else changes for a build without a difference: its HTML is byte for byte what 0.18.0 wrote, but for the version the branding footer names, one comment in the default theme's app.js, and, under lang: ja, the labels and lang="en" on the branding line. There was no beta for that reason.

See the difference sample, the command reference, and html.diffViewDefault.

One column

• The new version with its deletions in place. A changed page shows the new version, each deleted block written back where it stood and marked as deleted, each added block marked as added. An added page shows its note above the new page, a deleted page its note above the earlier page.
• The bar gains the fourth button, Inline. In one column, the count and previous/next walk the same changes as side by side, and Show changes is ticked and fixed.
• The in-page table of contents lists the column's headings, the added and deleted ones marked, each with the changes in its section. The sidebar is the difference's, and there are no previous and next pages under a page.
• Search covers the new version, and its highlight stays out of the deleted blocks. In mermaid.mode: client, a deleted diagram is drawn in the column the view shows.
• In the other three views nothing of it shows, and in the new version's own view every block lies where it lies in the same build without a difference.

The view a document opens in

html.diffViewDefault chooses it: side-by-side (the default), inline, current, or earlier. current and earlier open on that version's first page rather than the list of changes. The reader can switch views; the choice is not kept, so the file opens in this view again. The key is accepted in every configuration and changes nothing in a build without a difference, and an earlier version's value is not used.

Japanese UI labels again

• lang selects the label table again, as it did until 0.17.1: en and ja ship, matched on the primary language subtag (ja-JP and JA find ja). Any other tag falls back to English and warns once per build with lang/no-label-table.
• Under lang: ja the search box, the table of contents, prev/next, the code and image controls, the footer's version, the PDF's cover and printed contents, and the difference's bar, list, and notes are Japanese.
• Generated by stays English. A label holds no placeholder, and the link after it fixes the word order, which is why 0.17.2 made every label English (#224). The line is marked lang="en" so a screen reader reads it as English, through a new optional template token, {{generatorAttrs}}.
• html.labels still replaces any label. A configuration that copied the Japanese labels into it keeps working and can drop them; while it sets generatedBy: "生成:", it keeps that footer.
• If you want English labels on a Japanese document, set them in html.labels; there is no separate key for the UI language.

Limitations

• The difference is still HTML only: a PDF output with --diff-from or --diff-from-dir stops with diff/unsupported. The difference on paper is v0.20.
• A custom template.html gets the lang="en" mark only where it keeps {{generatorAttrs}}.

CI

• The CI guide pins monodocs@0.19.0.

v0.18.0

npm install -g monodocs

0.18.0 writes the difference from an earlier version of a document into the single HTML file, for readers who do not look at Git. build gains two options:

• --diff-from <ref> reads the earlier version from a git tag, branch, or commit of the repository the current directory is in, without touching the working tree, the index, or any ref;
• --diff-from-dir <dir> reads it from a directory that stands for the current directory, not for the input: run from the project root with ./docs as the input, --diff-from-dir ../project-1.2 reads ../project-1.2/docs.

Nothing changes for a build without either option: its HTML is byte for byte what 0.17.2 wrote, but for the default theme's app.js, which gains a hook the difference uses for search, and the version the branding footer names. There was no beta for that reason.

See the difference sample and the command reference.

What the reader gets

• The list of changes, the page the document opens on: added, moved, changed, and deleted pages, each linking to its page, and the number of unchanged pages. Its title names the two versions by their document.version, or the earlier one by the argument as written.
• A changed page side by side: the earlier page on the left, the new one on the right, with the blocks they share lined up — table rows included — deleted blocks marked on the left and added ones on the right. A page that did not change is shown once. A deleted page stands where it stood in the earlier sidebar; an added page carries a note.
• A bar fixed at the top with three views — side by side, the earlier version, the new version — and previous/next buttons that walk every change with a count. A version's own view shows that version plain until Show changes is ticked. Search covers the version the view reads.
• The sidebar marks added pages green with +, deleted pages red with −, changed pages orange with •, and moved pages blue with →.

How a difference is found

• Both versions are built by this monodocs, the earlier one from its own sources. It takes what the document holds from its own configuration — input, root, sources.*, sidebar.mode, sidebar.items, sidebar.titleFrom, sidebar.titleTransform, sidebar.flattenSingleChild, math.enabled, and mermaid.enabled — and how the output looks follows the new one. Its build's warnings are not reported, since a released version cannot be fixed; its errors stop the build.
• Pages are matched by route, then by aliases; a page moved without one is a deletion and an addition.
• A block is compared by what it reads as. A link's target, emphasis, a table's frame, a role, and the numbers the build generates (sections, figures, footnotes, under :sectnums: or numbering.sections, and switching from :sectnums: to numbering.sections) are not differences.
• The earlier build reads its own includes and images, and {docdir} in its pages is then written as the new location; the AsciiDoc date and time attributes are taken once and given to both builds. So an unchanged page using them is no difference. With SOURCE_DATE_EPOCH set, two builds of the same difference give the same bytes, on machines whose TZ agrees.
• --diff-from needs git on PATH, and in CI the history: check out with fetch-depth: 0. A file kept in Git LFS needs git-lfs; a page, include, or image that comes out as an LFS pointer is diff/lfs-pointer. Submodules come out empty, as in a checkout without --recurse-submodules.
• The size report gains a difference line.

Limitations

• The difference is HTML only: with a PDF output (-f pdf, -f both, or output.format) the build stops with diff/unsupported. The difference on paper is v0.19.
• The two options are on build only, have no key in the configuration file, and cannot be used together (diff/conflicting-options); watch, serve, and validate do not know them.
• A path the earlier version lacks, or one that leaves it, is diff/outside-version. For a version whose document directory was renamed since, pass a copy laid out like the new version with --diff-from-dir.
• The difference's wording is English, as every UI label is since 0.17.2; html.labels replaces it.
• An inline SVG in the earlier column has its IDs and references renamed by a simpler pass than the one 0.17.2 gave the page: url(#…), href, #id selectors, and ID-naming attributes follow, but an attribute selector on id in its <style> ([id=r]) does not, and keeps naming the new column's element. SMIL references and nested CSS selectors are not renamed in either column.

CI

• The CI guide pins monodocs@0.18.0.

Dependencies

• zod 4.6.7, past GHSA-mrhx-c7xc-m3w5 (#232). zod is bundled into the CLI and the standalone binaries, so 0.17.2's package and binaries carry 4.6.5 until this release replaces them. monodocs validates the user's own configuration file with it, so the exposure was small, and no 0.17.x patch was made for it.
• puppeteer-core 25.16.0, whose chromium-bidi depends on zod 4.
• The Mermaid runtime still bundles DOMPurify 3.4.12 (#229); none of its advisories is reached under Mermaid's defaults, and it moves when a Mermaid release bundles 3.4.17 or later.

v0.17.2

npm install -g monodocs

0.17.2 is a patch with four fixes. It:

• keeps the UI labels of the generated document in English whatever lang says, leaving html.labels as the way to show them in another language (#224);
• keeps the image of a GFM alert whose body opens with one (#221);
• renames the references inside an inline SVG along with its IDs (#223);
• makes watch and serve on Linux fail with EMFILE when no inotify instance is left, instead of watching nothing (#215).

It is a patch, but the labels change alters the output of every lang: ja build that does not set html.labels.

What changes for an existing document

	0.17.1	0.17.2
UI labels under lang: ja without html.labels (the search box, the buttons, the footer's 生成:, the PDF cover's page label, the printed contents heading)	Japanese	English. lang fills <html lang> only. The configuration reference writes out the former Japanese labels as an html.labels block to copy
lang set to a language with no label table	English, with a lang/no-label-table warning	English, with no warning: the diagnostic is removed
A GFM alert whose body is an image, or opens with one	the image is lost	the image is kept inside the alert
An SVG written into an AsciiDoc page inline (opts=inline or a passthrough)	its IDs get the page prefix, but url(#…), <use href>, xlink:href, #id selectors in <style>, and aria-labelledby keep the old names, so gradients, <use> copies, style rules, and accessible names are lost	the references follow the renamed IDs. SMIL references (begin/end) stay as written
watch or serve on Linux with no inotify instance left	looks alive and never rebuilds	fails with EMFILE. The command reference says how to raise fs.inotify.max_user_instances

• Under lang="ja", a screen reader reads the English labels in a Japanese voice until html.labels replaces them.

CI

• The CI guide pins monodocs@0.17.2.

v0.17.1

npm install -g monodocs

0.17.1 fixes what looking at 0.17.0's output turned up, in the lightbox, in dark mode, and in embedding images. It:

• scales an SVG image up to fill the lightbox, and lets the reader switch any image between fit to screen and actual size (#210, #211);
• keeps images and Mermaid diagrams drawn for a light background readable in dark mode (#210, #213);
• embeds a Markdown image whose file name has a space or characters outside ASCII, such as 図.png (#212).

It is a patch, but it adds two html.labels keys for the lightbox's new button, a surface 1.0 freezes.

What changes for an existing document

	0.17.0	0.17.1
An SVG image in the lightbox	shown at the size its width and height give it	scaled up to fill the dialog, keeping its proportions, as a Mermaid diagram is. A raster image is still only shrunk
An image in the lightbox	drawn over the dark backdrop, the page showing through a transparent one	on a white panel fitted to the picture, in light and dark mode
Fit to screen or actual size	no choice	a button beside the close button switches an image to its actual size, with the dialog scrolling, and back. It appears only when the two sizes differ. A raster image's actual size is its pixels, and it is never enlarged. A local SVG's is the size the SVG gives itself. An SVG the build cannot read (remote, a data URI, outside the input) or size (in em) gets no button, and neither does a Mermaid diagram
A figure's image in the page, in dark mode	on the dark page	on a white backing. An icon or a badge in a sentence, or an image in a table cell, gets none. Light mode is unchanged
A local SVG with a viewBox but no width or height of its own	stretched across the page	given its viewBox width, its height following, unless the <img> sets a size
A Mermaid diagram in Mermaid's light theme, in dark mode: client mode, the default, or pre-rendered for a light page	near-black edges on the dark page, in the page and in the lightbox	on a white backing in the page and the white panel in the lightbox. A diagram pre-rendered with html.colorScheme: dark keeps the page background
A Markdown image named 図.png or <a b.png>	not embedded: image/not-found, and a percent-encoded relative src that a distributed HTML file or PDF cannot reach	embedded, as the same image in AsciiDoc already was

• In dark mode, a figure drawn for a dark background (light lines on transparency) is hidden by the white backing, and one with rounded corners shows white at them.
• In client mode, a diagram stays inside its code-block frame, so in dark mode it shows as a white diagram in a dark frame.

Labels and themes

• The new html.labels keys are actualSize ("Actual size" / "実寸で表示") and fitToScreen ("Fit to screen" / "画面に合わせる"). A document in a language other than English or Japanese that sets its own labels gets the English text for these two until it adds them.
• A custom template.html without the new <button id="image-lightbox-size"> has no size button. A theme that replaces app.js gets two new attributes it can use: data-monodocs-svg-size on a local SVG <img>, and data-monodocs-scheme="dark" on a diagram pre-rendered in a dark theme.

What may now stop a build

• A Markdown image with a space or non-ASCII characters in its name is now found and embedded. If it is larger than assets.maxInlineSize and assets.onLargeImage is error, the build now stops on it, where 0.17.0 only warned that it was not found.
• The other way round, validate --strict no longer fails on the image/not-found warning such an image raised.

CI

• The CI guide pins monodocs@0.17.1.

v0.17.0

npm install -g monodocs

v0.17 sets a PDF's formulas in one math font that monodocs carries, so a PDF looks the same wherever it is built. It also moves KaTeX and Mermaid past a security advisory. It:

• sets every formula in a PDF in New Computer Modern Math (Book), whatever math font the machine has, including none;
• moves KaTeX to 0.18.11 and Mermaid to 12.2.0, out of GHSA-238p-pmpm-9mq7.

Every PDF with a formula changes. There was no beta this time. Before publishing, PR CI installed the packed package on Linux and Windows and checked that its PDF embeds the carried font. The published package is verified after latest moves, and a fix will go into 0.17.1.

What changes for an existing document

	0.16.0	0.17.0
Formulas in a PDF	set in the build machine's math font: Cambria Math on Windows, Latin Modern Math if installed on Linux. On a machine without one, letters become tofu and brackets do not stretch	set in New Computer Modern Math, which monodocs carries, on any machine. A document with no formula does not load it
A formula in a Mermaid label, in a PDF	the build machine's math font	the carried font. Under mermaid.mode: pre-render, the PDF gets a copy of the diagram laid out again in it; the HTML keeps the SVG laid out in the machine's fonts
Formulas in HTML	the reader's fonts	unchanged (printing the HTML from a browser uses the browser's fonts too)
The font check, on a machine with no math font, with the default theme	reported every formula's letters in the PDF (font/missing) and the missing MATH table (font/no-math-table)	no longer reports what the carried font draws. Characters no available font can draw, such as Japanese in \text{} on a machine without CJK fonts, are still reported. Formulas under a theme's own math font and labels pre-rendered for the HTML remain subject to the existing checks
\reflectbox, \mathreflectbox in a page's formula	a parse error (math/parse-failed)	rendered, but unreflected: MathML cannot carry the reflection. Reported as math/construct-unsupported
\big{(}, \mapsfrom, \char"10FFFF	parse errors	rendered
A \\ that ends a numbered align, gather, or alignat	no extra row	an empty row
An empty last row with a \tag, in a starred environment too	dropped silently	kept, and reported as math/numbering-unsupported
alignat / alignedat with a column count that is not a positive integer ({0}, {1.5})	rendered	a parse error (math/parse-failed)

• The rows on KaTeX's syntax are about formulas in the pages. A formula in a Mermaid label is drawn by the runtime's own KaTeX, which monodocs does not check. The same commands now render there, and \reflectbox there is neither reflected nor reported.
• A theme that sets its own font-family on math still wins in the PDF. Monodocs's font only replaces the browser's default. A diagram pre-rendered for the PDF is still laid out in the carried font, even then.
• Built the same way before and after the KaTeX and Mermaid move, the HTML and MathML of the sample documents and the math fixture are byte-identical, apart from the embedded Mermaid runtime. Their diagrams draw pixel-identically.

CI

• The PDF needs no math font on the runner. The CI guide no longer installs fonts-lmodern, and pins monodocs@0.17.0.
• One exception: under mermaid.mode: pre-render, a build that writes HTML lays out every diagram label in the runner's fonts. A formula in a label there still needs a math font on the runner.

Dependencies

• New Computer Modern Math, Book weight, from CTAN newcomputermodern 8.1.1, under the GUST Font License, named in THIRD-PARTY-NOTICES.txt.
  • It ships beside the bundle in the npm package (dist/fonts). The npm package grows from about 4.4 MB to 5.4 MB packed.
  • The standalone binary does not carry it, since it cannot write a PDF. Its size is unchanged.
• KaTeX 0.18.11: the version Mermaid 12.2.0's runtime bundles.
  • npm marks 0.18.11 deprecated, because its changes to strict went out in a patch release. Its package is identical to 0.19.0's apart from the version string.
• Mermaid 12.2.0:
  • The runtime's notices change only in the KaTeX and Mermaid versions.
  • mermaid.runtime: cdn loads mermaid@12.2.0, and a test now ties the CDN version to the installed Mermaid.

What may now stop a build

• An alignat or alignedat whose column count is not a positive integer fails validate --strict, as math/parse-failed.
• An empty last row with a \tag, which 0.16.0 dropped, now produces math/numbering-unsupported, in a starred environment too. So validate --strict may newly fail on it.
• \reflectbox and \mathreflectbox in a page's formula are now a warning (math/construct-unsupported) rather than a parse error. Under --strict they still fail.
• A PDF with a formula needs the font beside the bundle (dist/fonts). If it cannot be read, or Chromium cannot load it, the build stops, whatever fontCheck says. Reinstalling the package, or checking the Chromium in use, is the remedy.
• The other way round, a build with fontCheck: error that failed on a machine without a math font now passes, if what it reported was the formulas the carried font now draws.

Documentation

• syntax.md and the configuration reference said that a \tag{} in a starred environment is drawn. It is not, and was not in 0.16.0 either.
• A \tag{} inside equation, align, gather, or alignat, starred or not, is dropped and reported.
• A \tag{} at the top level of a formula, such as after a starred environment, is drawn at the right margin.

v0.16.0

npm install -g monodocs

v0.16 clears what earlier releases set aside, so that 1.0 is left with only the removal of sidebar.exclude and a final check. It:

• draws AsciiDoc checklists as checkboxes, the way Markdown's task list does;
• renders AsciiDoc asciimath through KaTeX, on by default;
• makes search fold half-width katakana and match okurigana and English inflections loosely;
• lets a figure be aligned left, centre, or right with figures.align and AsciiDoc's align=;
• gives the search box a clear button of the theme's own;
• lists what 1.0 freezes on one page of the reference.

Checklists, asciimath, search results, and where figures sit all change for existing documents, so 0.16.0-beta.1 went out under next first. It was verified on Linux and Windows, the samples were built with it and looked at, the clear button was seen in Firefox, and the math fixture's accents were checked on Windows with Cambria Math.

What changes for an existing document

	0.15.0	0.16.0
An AsciiDoc checklist item	❏ or ✓, characters no default font has (tofu in the PDF)	a checkbox, <input type="checkbox" disabled>, the same as a Markdown task list item. [%interactive] is drawn disabled too
AsciiDoc asciimath (asciimath:[...], and stem when it means asciimath)	printed as text, with a warning (math/asciimath-not-rendered)	rendered as formulas, on the same terms as latexmath
A Markdown image alone in a paragraph, and a Mermaid diagram	at the left	in the centre
An AsciiDoc image block in a table cell	in the centre	at the left
AsciiDoc align=left / align=right on an image block	no effect	takes effect
Search for ガイド / ｶﾞｲﾄﾞ, 引渡し / 引き渡し, install / installing	no match across the spellings	matches both ways, highlighted as written in the page. Exact matches still rank first
The search box	the browser's own ×, in Chromium and Safari only	the theme's own clear button in every browser

• math.enabled: false turns asciimath off along with latexmath.
• figures.align: left puts Markdown figures back at the left.

Configuration and diagnostics

• New key figures.align: left, center (the default), or right. An AsciiDoc align= on the block wins over it. Markdown has no markup of its own for alignment.
• New label html.labels.clearSearch: "Clear search" / "検索語を消去".
• math/asciimath-not-rendered is retired. A CI job that looked for it will no longer see it. An asciimath formula that cannot be rendered is reported as math/parse-failed, as latexmath is.

Dependency

asciimath is converted by asciimath2tex 1.5.0 (Apache-2.0, no dependencies), named in THIRD-PARTY-NOTICES.txt. It adds about 38 KB to the CLI bundle and 64 KB to the standalone binary.

What 1.0 freezes

The reference has a new page, What 1.0 Freezes. It lists every configuration key with its default, every command and option, every diagnostic code with the schemaVersion a CI job pins, and the markup monodocs recognises beyond CommonMark, GFM, and AsciiDoc. A test keeps it in step with the code. sidebar.exclude is listed as deprecated, to be removed in 1.0.

What may now stop a build

• An asciimath formula that cannot be converted is reported as math/parse-failed, which fails validate --strict, as a latexmath one does.
• The other way round, a document whose asciimath used to fail validate --strict through math/asciimath-not-rendered now passes, if every formula converts.

Math on Windows

Checked with Edge and Cambria Math, the fixture's accents and braces sit as expected, with three things recorded rather than fixed:

• \widehat, \widetilde, \widecheck, and \utilde stay about a letter wide over a long term, as with Latin Modern Math on Linux.
• In a PDF built on Windows, \bar over a letter sits low enough to touch it, so at an ordinary zoom x̄ can read as x.
• A radical's sign does not join its bar.

None of these is new in 0.16. They come from how the browser and the font set correct MathML, which varies with the pair. monodocs now fixes what its own markup gets wrong and records the rest for the pairs it measures (roadmap.md 6.4).

Documentation

• The CI guide on the site now pins monodocs@0.16.0.
• The site now publishes PDF samples next to the HTML ones, built from the same examples with a cover and a table of contents: English, Japanese. The README links to them in place of page images.
• The samples' Search pages describe the new folding and loose matching, and the clear button.
• syntax.md describes checklists, asciimath, and figure alignment.

v0.16.0-beta.1

Prerelease of 0.16.0, published to npm under the next tag.

npm install -g monodocs@next

v0.16 clears what earlier releases set aside, so that 1.0 is left with only the removal of sidebar.exclude and a final check. It:

• draws AsciiDoc checklists as checkboxes, the way Markdown's task list does;
• renders AsciiDoc asciimath through KaTeX, on by default;
• makes search fold half-width katakana and match okurigana and English inflections loosely;
• lets a figure be aligned left, centre, or right with figures.align and AsciiDoc's align=;
• gives the search box a clear button of the theme's own;
• lists what 1.0 freezes on one page of the reference.

Checklists, asciimath, search results, and where figures sit all change for existing documents, which is why it goes out as a beta first.

What changes for an existing document

	0.15.0	0.16.0
An AsciiDoc checklist item	❏ or ✓, characters no default font has (tofu in the PDF)	a checkbox, <input type="checkbox" disabled>, the same as a Markdown task list item. [%interactive] is drawn disabled too
AsciiDoc asciimath (asciimath:[...], and stem when it means asciimath)	printed as text, with a warning (math/asciimath-not-rendered)	rendered as formulas, on the same terms as latexmath
A Markdown image alone in a paragraph, and a Mermaid diagram	at the left	in the centre
An AsciiDoc image block in a table cell	in the centre	at the left
AsciiDoc align=left / align=right on an image block	no effect	takes effect
Search for ガイド / ｶﾞｲﾄﾞ, 引渡し / 引き渡し, install / installing	no match across the spellings	matches both ways, highlighted as written in the page. Exact matches still rank first
The search box	the browser's own ×, in Chromium and Safari only	the theme's own clear button in every browser

• math.enabled: false turns asciimath off along with latexmath.
• figures.align: left puts Markdown figures back at the left.

Configuration and diagnostics

• New key figures.align: left, center (the default), or right. An AsciiDoc align= on the block wins over it. Markdown has no markup of its own for alignment.
• New label html.labels.clearSearch: "Clear search" / "検索語を消去".
• math/asciimath-not-rendered is retired. A CI job that looked for it will no longer see it. An asciimath formula that cannot be rendered is reported as math/parse-failed, as latexmath is.

Dependency

asciimath is converted by asciimath2tex 1.5.0 (Apache-2.0, no dependencies), named in THIRD-PARTY-NOTICES.txt. It adds about 38 KB to the CLI bundle and 64 KB to the standalone binary.

What 1.0 freezes

The reference has a new page, What 1.0 Freezes (it reaches the site with 0.16.0). It lists every configuration key with its default, every command and option, every diagnostic code with the schemaVersion a CI job pins, and the markup monodocs recognises beyond CommonMark, GFM, and AsciiDoc. A test keeps it in step with the code. sidebar.exclude is listed as deprecated, to be removed in 1.0.

What the beta is for

Before 0.16.0 goes to latest:

• the published package is verified on Linux and Windows;
• the samples are built with the beta and looked at: checklists, formulas, figures, search, and the clear button, the button in Firefox too;
• the wide accents in the math fixture are checked on Windows with Cambria Math.

v0.15.0

npm install -g monodocs

v0.15 is the last minor release before 1.0. It does three things:

• moves diagrams to mermaid 12;
• puts the third-party notices of the Mermaid runtime into the HTML that embeds it;
• adds math, rendered at build time to MathML.

Every document with a diagram builds differently, and math is on by default, so 0.15.0-beta.1 went out under next first. It was verified on Linux and Windows, every diagram this repository publishes was looked at under mermaid 12, and the math fixture was checked on Windows with Cambria Math.

What changes for an existing document

	0.14.0	0.15.0
A Mermaid diagram	drawn by mermaid 11	drawn by mermaid 12: layout and styling may differ
A diagram in client mode	no ES2024 requirement	needs Chrome or Edge 117, Firefox 119, Safari 17.4, or later (ES2024); an older browser draws no diagram
mermaid.runtime: cdn	loads mermaid@11	loads the pinned mermaid@12.1.0
HTML with the inline Mermaid runtime (the default)	the runtime alone	the runtime with its third-party notices, in a comment inside its script
Markdown $...$, $$...$$, $`...`$, and a fenced math block	printed as text, or as code	rendered as formulas, by GitHub's rules
AsciiDoc latexmath, and stem when it means latexmath	MathJax delimiters left as text	rendered as formulas
AsciiDoc asciimath	printed as text	still printed as text, now with a warning (math/asciimath-not-rendered), which fails validate --strict

math.enabled: false turns the math changes off and gives 0.14.0's output for formulas.

GitHub's rules keep the common forms of money and shell variables as text:

• It costs $5 and $10 today. and $HOME/$USER stay text.
• Between $5 and 10$ is a formula. Write \$ for a dollar sign there.

How diagrams change

Every diagram this repository publishes still reads under mermaid 12. The look is different:

• Boxes are white with dark borders where mermaid 11 drew them light purple.
• Edges turn at right angles where they curved.
• Long labels in a wide diagram may wrap.

Look at your own diagrams after upgrading. A diagram that no longer reads can stay on 0.14.0 while it is adjusted.

License change

monodocs itself is still MIT, and your document content is unaffected. What is new:

• EPL-2.0 code is now bundled. mermaid 12 bundles ELK (elkjs, EPL-2.0, with parts of EMF under the EPL-1.0) into its runtime. That runtime is embedded in the npm bundle and the standalone binary. It also goes into the HTML built with the inline runtime (the default) whenever a document has diagrams. The CDN runtime, pre-render, and a document without diagrams keep it out of the output.
• The HTML that embeds the runtime now carries the notices of what the runtime contains, in a comment inside the runtime's script. That includes ELK, and a few CC BY-SA snippets and pieces of code whose source states no license, which earlier releases embedded too, without notices.

See the license page.

Math

Let $x$ be real, and $\mathbb{R}$ the reals.

```math
\int_0^1 x\,dx = \frac{1}{2}
```

• Rendering. KaTeX renders each formula to MathML only, with no script and no stylesheet in the output, and the browser draws it. \mathbb, \mathbf and the other styles become Unicode's mathematical letters, since the browser ignores mathvariant.
• A math font is needed. It must be on the machine that prints the PDF and in the reader's browser.
  • Cambria Math ships with Windows.
  • On Debian and Ubuntu, fonts-lmodern supplies Latin Modern Math.
  • For a PDF, fontCheck reports a formula's letters that no font draws (as the browser draws them: x as 𝑥), and a formula font with no OpenType MATH table (font/no-math-table).
• Copying and search. In the HTML, a selection with a formula copies the formula's source: as written in Markdown, and in AsciiDoc as latexmath, stem being resolved by then. Copying from a PDF is the viewer's. Search reads a formula's TeX.
• Diagnostics. What cannot be rendered is reported. A formula KaTeX cannot parse, or one using a command behind trust, is shown as written. An automatic equation number, a style Unicode has no letters for, an enclosure CSS cannot draw, and a construct the browser cannot draw are left out of a formula that is otherwise rendered.
• Fixture. examples/math holds the formulas v0.14 measured, in Markdown and AsciiDoc, to check a machine's fonts with.

syntax.md describes the notation and its rules.

What may now stop a build

• With fontCheck: error, a PDF with formulas fails where no math font is installed.
• The inline runtime is larger under mermaid 12 and its notices, so a tight assets.budget may now warn or fail.

Documentation

• The CI guide on the site now pins monodocs@0.15.0.
• The CI guide's font install step now adds fonts-lmodern beside the CJK and emoji fonts. A workflow copied from an earlier guide may need it: without a math font, the default font check reports font/no-math-table, and may also report a formula's letters as tofu.

v0.15.0-beta.1

Prerelease of 0.15.0, published to npm under the next tag.

npm install -g monodocs@next

v0.15 is the last release before 1.0. It does three things:

• moves diagrams to mermaid 12;
• puts the third-party notices of the Mermaid runtime into the HTML that embeds it;
• adds math, rendered at build time to MathML.

Every document with a diagram builds differently, and math is on by default, which is why it goes out as a beta first.

What changes for an existing document

	0.14.0	0.15.0
A Mermaid diagram	drawn by mermaid 11	drawn by mermaid 12: layout and styling may differ
HTML with the inline Mermaid runtime (the default)	the runtime alone	the runtime with its third-party notices, in a comment inside its script
Markdown $...$, $$...$$, $`...`$, and a fenced math block	printed as text, or as code	rendered as formulas, by GitHub's rules
AsciiDoc latexmath, and stem when it means latexmath	MathJax delimiters left as text	rendered as formulas
AsciiDoc asciimath	printed as text	still printed as text, now with a warning (math/asciimath-not-rendered), which fails validate --strict

math.enabled: false turns the math changes off and gives 0.14.0's output for formulas.

GitHub's rules keep the common forms of money and shell variables as text:

• It costs $5 and $10 today. and $HOME/$USER stay text.
• Between $5 and 10$ is a formula. Write \$ for a dollar sign there.

Licence

monodocs is MIT. The Mermaid runtime it embeds contains elkjs under the EPL-2.0 (with parts of EMF under the EPL-1.0), a few CC BY-SA snippets, and a few pieces of code whose source states no licence.

HTML built with the inline runtime now embeds them with their notices, and your document content is unaffected. See the license page.

Math

Let $x$ be real, and $\mathbb{R}$ the reals.

```math
\int_0^1 x\,dx = \frac{1}{2}
```

• Rendering. KaTeX renders each formula to MathML only, with no script and no stylesheet in the output, and the browser draws it. \mathbb, \mathbf and the other styles become Unicode's mathematical letters, since the browser ignores mathvariant.
• A math font is needed. It must be on the machine that prints the PDF and in the reader's browser.
  • Cambria Math ships with Windows.
  • On Debian and Ubuntu, fonts-lmodern supplies Latin Modern Math.
  • For a PDF, fontCheck reports a formula's letters that no font draws (as the browser draws them: x as 𝑥), and a formula font with no OpenType MATH table (font/no-math-table).
• Copying. A selection with a formula copies the formula's source as written, and search reads its TeX.
• Diagnostics. What cannot be rendered is reported: a formula KaTeX cannot parse, a command behind trust, an automatic equation number, and a style, enclosure or construct the browser cannot draw.
• Fixture. examples/math holds the formulas v0.14 measured, in Markdown and AsciiDoc, to check a machine's fonts with.

syntax.md describes the notation and its rules.

What may now stop a build

• With fontCheck: error, a PDF with formulas fails where no math font is installed.
• The inline runtime is larger under mermaid 12 and its notices, so a tight assets.budget may now warn or fail.

What the beta is for

Before 0.15.0 goes to latest:

• the published package is verified on Linux and Windows;
• every diagram this repository publishes is looked at under mermaid 12;
• the math fixture is checked on Windows with Cambria Math.

v0.14.0

npm install -g monodocs

v0.14 is about setting the printed page: the things a specification printed and handed on is expected to have — sections numbered across the whole document, so "see 3.2" means something, and a table of contents that says which sheet each section starts on.

None of 0.14 breaks an existing configuration, so, like 0.13, it is released directly, without a beta.

No breaking changes

Both new keys are off by default, so an existing configuration builds the same document. What every build does differently is small:

• The page data carries one more label, contents, the heading of the printed table of contents. It can be set through html.labels like the others.
• The client script carries the code that shows section numbers. Without numbering it does nothing; search ranks and links exactly as before.
• An error in sidebar.items is reported earlier, before the pages are post-processed (and before a browser is started for Mermaid pre-render).

Section numbers across the whole document

numbering:
  sections: 3 # false (default), or the deepest heading level numbered (2–6)

• One numbering over every file, Markdown and AsciiDoc alike, in the order of the sidebar the reader sees. A page's number is its place in the sidebar, a directory contributes a level, and h1 carries the page's own number: the third page of the second top-level entry is 2.3, and its sections 2.3.1, 2.3.2.
• The number appears in the heading (as <span class="section-number">, so a stylesheet can hide it and copying a heading copies the number), in the sidebar, in the in-page table of contents, and in the PDF bookmarks. Searching 3.2 finds section 3.2 and lists it first.
• It never appears in an address: routes, page IDs, and heading IDs are exactly what they are without numbering, so no link anyone has copied breaks when a page moves.
• AsciiDoc's :sectnums: numbers each file on its own, so it is refused while this is on (numbering/sectnums), naming the key. With numbering off it works as before.

A table of contents on paper

pdf:
  toc:
    enabled: true # false (default)
    depth: 2 # deepest heading level listed (2–6)

• The PDF opens, after the cover, with a table listing the sidebar's directories and pages and each page's headings down to depth, with section numbers when numbering is on. Each line links to its section.
• The page numbers are read back from the PDF itself and checked: monodocs prints once with the number column empty, reads which sheet each section landed on, prints again with the numbers in, and reads that PDF once more. A document whose numbers do not settle fails the build (pdf/toc-not-converged) rather than shipping a table that is usually right.
• It costs a second print. For a hundred-odd sheets of Japanese with Mermaid diagrams, about 2.1 s became 3.1 s on a Linux workstation, and 3.9 s became 6.1 s on a GitHub-hosted Windows runner. That is why it is off by default.
• PDF only: the HTML has the sidebar.

Math: measured, and planned for 1.x

Math is still unsupported, but the reason has changed. KaTeX's MathML-only output needs no script or stylesheet in the file, and a sample of real formulas sets well in Chromium with a math font installed. What it needs before it ships is recorded in the roadmap (6.4): a font check that covers formulas (without a math font every variable is tofu, and today's check does not see it), \mathbb / \mathbf resolved at build time (Chromium drops them), copy and search designed, and the notation chosen in the open.

Documentation

• The CI guide on the site now pins monodocs@0.14.0.
• The documentation site is now deployed from the latest stable release rather than from main, so it describes the version npm install gives you.