Changelog

pnpm add -D --save-exact for-humanity@latest

0.31.1 — 2026-11-03

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the marked image size fix.

• Keep a marked image at its own size, centered in its box, instead of stretching a narrow screenshot to the text width. A wide one still shrinks to fit.

0.31.0 — 2026-11-03

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the Details status position, marked images, table row targets and one-line identifier links. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Add a marked image, <figure class="fx-shot">, that puts numbered boxes over a screenshot in percent of its size, with a switch on the top right border that hides them. See Figures.
• Make a raw <a id> at the start of a table cell a target for its row. Arriving there highlights the row for a few seconds, and the cell stays on one line.
• Keep a link whose text is a hyphenated identifier, such as SSD-001, on one line instead of breaking after the hyphen, and keep a link that starts with an icon image on one line.
• Place a status badge in a Details title at the right end of the row, before the chevron, wherever the phrase is written. A list of question cards now lines up its statuses along the right edge.

0.30.0 — 2026-11-02

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the figure box, the lighter list bullets and the Details changes. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Put a raster figure, a PNG, JPEG, GIF, WebP or AVIF image alone in its paragraph, in a box with the same border and corner radius as tables and SVG figures and a 6px inner margin, so a screenshot no longer floats on the page background. An image inside a sentence, wrapped in a link or in a raw HTML paragraph with attributes keeps its written layout.
• Draw unordered list bullets in the muted text color at 70% of the text size. The default disc in the body font looked heavier and larger than the text beside it. Numbered lists keep their numbers.
• Move the Details chevron to the right end of the title row. It points down while collapsed and turns to point up over 320ms when opened, and the body text now starts at the box padding instead of after the chevron column.
• Slide a Details body open and closed over 320ms, together with its padding, in browsers that can animate to an automatic height. Other browsers open and close it at once, and reduced motion turns the slide off.
• Keep the hover shade on the title row of an open Details, so the open card stands out in a list of Details.
• Show the first word of a Details title as a reference chip when it is a configured prefix and a number, such as :::details[Q3 · Which unit?]. A list of question cards now shows the same chips as the links that point to them.

0.29.1 — 2026-11-02

Upgrade: Existing projects remain compatible. Rebuild and redeploy. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Count an id written in raw HTML, such as <a id="01"></a> inside a heading, as a target of a #hash link in the same document and in other documents. A document that keeps stable numbered anchors beside its heading text no longer prints Link to a missing heading for every link to them. A hash that matches neither a heading anchor nor a written id still warns.

0.29.0 — 2026-11-01

Upgrade: Existing projects remain compatible. Rebuild and redeploy. A document whose label differs from its name now shows the label under the title; a document that should not show one sets label to the same text as name.

• Show the document label under the title as a one-line lead in the muted color of the date line, when it differs from name. The same sentence already served as the sidebar tooltip and the link preview description, so a page can open with it instead of repeating it in the first paragraph.
• Drop the rule above section headings. Sections are separated by the wide section gap alone, so a Details block or a figure before a heading no longer ends in two stacked lines.
• Draw a Details block as a bordered box like a figure instead of two hairlines. The title row is in the body text color instead of the link color, is no longer bold, has inner padding so its hover shade fills the row inside the box, and opens with a chevron that turns from right to down over 320ms like the table sort arrow, instead of the + and − glyphs. The opened body sits inside the box under a light divider, aligned with the title text, without the vertical line. Consecutive Details blocks share one box with dividers between them, and a block keeps more room above and below than before.

0.28.1 — 2026-10-30

Upgrade: Existing projects remain compatible. Rebuild and redeploy. Author syntax for figures is unchanged.

• Rename the control parts the figure widget generates. Icon buttons, the scrubber, the step count and the run box output carry wg_fx__* classes instead of fx__icon, fx__scrub, fx__count and fx__out. The run box editor, selected before as .fx[data-fx="run"] textarea, now carries wg_fx__editor, and a bar the widget builds carries wg_fx__bar next to fx__bar. Site CSS that targeted the old undocumented fx__icon, fx__scrub, fx__count or fx__out classes, or aria-disabled buttons inside fx__bar, loses that styling. The authoring vocabulary (fx, fx-*, fx__stage, fx__captions, fx__range, fx__bar, fx--ready, is-on, is-hl, data-*, --fx-*) moved into its own stylesheet, which is the documented contract.

0.28.0 — 2026-10-29

Upgrade: Existing projects remain compatible. Rebuild and redeploy to get the figure widget. A site that already carries its own copy of a figure runtime script in its documents must remove it, or step figures and run boxes get two sets of controls. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Add interactive figures. A <figure class="fx" data-fx="steps"> written in raw HTML gets a bar with play, previous, next, a scrubber and the step count, and its elements show, highlight or move per step with data-on, data-hl and data-pos; data-labels turns the bar into tabs. data-fx="range" wires a slider to the --fx-v variable and an <output>, data-fx="run" runs the code block above it in a sandboxed iframe and shows the console, and data-fx="custom" leaves the scene to the author’s own module script. The widget ships in the inline browser bundle like table sorting, so every page carries about 11 KB more script (under 4 KB compressed). Without JavaScript the page shows the elements marked to the end and every caption. Control names are English, or Korean when the page language is ko or a regional form such as ko-KR. See Figures.

0.27.0 — 2026-10-29

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the larger text, the body font change and table sorting. Text struck through with a single ~ on each side needs ~~ now. CLI commands, configuration and Node.js requirements are unchanged.

• Enlarge text for reading: body text is 16px instead of 12px, navigation, outline, tables, code blocks and metadata are 14px, group labels 13px, part titles 17px, subheadings 18px, section headings 20px, page titles 26px, the site name 20px and a centered README title 32px. Diagram labels are 14px instead of 13px, and body letter spacing loosens from -0.03em to -0.02em.
• Set Latin, digits and punctuation in body text, labels and diagrams in IBM Plex Sans KR, the Latin its Hangul was designed with, instead of the monospaced Monoplex KR. Inline code, document navigation, the outline, code blocks, code file titles, reference chips and the status code keep Monoplex KR for Latin next to IBM Plex Sans KR Hangul, so code and the sidebars frame the text like a terminal; inline code is 15/16 of the surrounding size so it reads at the same height, and the outline narrows its word spaces so Hangul headings keep about their body spacing. A page that has not received the fonts yet shows the system sans-serif instead of the system monospace.
• Keep the hover shade of a Details title between its top and bottom lines. The title row used to reach 6px past both ends of the lines.
• Sort a table by clicking a column header. A table with a header row and at least two body rows shows an arrow at the right edge of a header when pointed at: the first click sorts that column ascending, the second descending and the third restores the written order, and the arrow turns as the direction changes. Numbers and dates in cell text sort by value, empty cells and - stay at the end, the sorted column is exposed as aria-sort, and the written order stays without JavaScript. A table with merged cells or a link in a header keeps its written order.
• Keep a single ~ as written, so a range such as 10~11개월 or 400~600 is no longer struck through. Strikethrough needs ~~ on each side.

0.26.3 — 2026-10-28

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the new card type. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Show the link preview image at full width on Slack and X. With image set, pages declare the summary_large_image Twitter card instead of summary, which those services drew as a small thumbnail beside the text. Sites without image keep summary.

0.26.2 — 2026-10-28

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the new heading sizes, lines, code font and diagram style. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Make headings easier to tell apart from body text: page titles are 20px, section headings 17px and subheadings 14px instead of 16px, 15px and 12px. A subheading now leaves about three lines (60px) of space above it, and a subheading right under a section heading stays close to it. The site name in the sidebar keeps its 16px size.
• Replace the dotted lines with solid gray ones under the document head, between parts, for --- and around Details. Hovering a Details title shades the whole row, and an open Details draws a thin line down its content, indented to the title text, so it is clear where the folded content ends.
• Set Hangul in code blocks and code file titles in IBM Plex Sans KR like body text; Latin stays in Monoplex KR. Hangul in code no longer lines up to exactly two Latin columns.
• Draw diagrams in the same black-and-white style as the rest of the page instead of soft blue: boxes on the light warm gray used for row hover with one-color gray borders (Mermaid 12’s left-to-right border gradient is off), square corners, no shadows, thin gray connectors ending in small open arrowheads, subgraphs on the page background and notes in the highlighter yellow. Sequence diagrams use the same font and 13px size as flowcharts instead of Mermaid’s 16px Trebuchet. Dark mode uses the matching dark values. A diagram that sets its own theme in frontmatter keeps it.
• Trim the side padding of inline code so a Hangul particle right after it no longer looks detached.

0.26.1 — 2026-10-27

Upgrade: Same package as 0.26.0, which was tagged but never published to npm because the release check failed. Install this version.

• Publish the 0.26.0 changes: flowchart labels longer than 120px are no longer cut off, and diagrams use the site’s palette and font.

0.26.0 — 2026-10-27

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the diagram theme and the label fix. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Stop cutting off flowchart labels longer than Mermaid’s 120px wrapping width. Mermaid 12 switches a label to wrapped lines only when its measured width equals that limit exactly, and a label that misses the comparison stayed on one line and was cut at the box edge. Labels are no longer wrapped automatically; the box grows to fit the text, and <br> breaks a line.
• Draw diagrams in the site’s own palette and font instead of Mermaid’s default theme: soft blue boxes with rounded corners, gray lines and the body font, with a matching dark palette when the system color scheme is dark. A diagram that sets its own theme in frontmatter keeps it.

0.25.0 — 2026-10-27

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the heading chips. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Show a heading whose whole text is a configured refs prefix and a number, such as ### Q3, as the same chip as a link to it, at the heading’s size, so a numbered question and the chips that point to it look alike. Raw HTML links whose text is a prefix and a number become chips too.

0.24.0 — 2026-10-27

Upgrade: Existing projects remain compatible. The status configuration accepts two more kind values, refs is a new optional key, and hash links to missing headings now print a build warning. Rebuild and redeploy to apply the new badge and chip styles. CLI commands, document syntax and Node.js requirements are unchanged.

• Add blocked (red) and neutral (gray) status badge kinds next to verified and unverified, so a document can mark blocked work and settled outcomes in their own colors.
• Add the refs configuration. A link whose text is a configured uppercase prefix and a number, such as [Q3](questions.md#q3), is shown as a small chip in gray, blue, violet or amber, so numbered decisions and questions stand out where the body refers to them. The link address is unchanged and documents without refs render as before.
• Warn at build time when a #hash link points to a heading that does not exist, in the same document or in another document, with the file and line number. Links to headings on the home page are not checked. The build continues as it does for a link to a missing document.

0.23.2 — 2026-10-27

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the new code colors, date labels and heading spacing. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Color code blocks with GitHub’s light and dark syntax themes, following the system color scheme. Comments and purple tokens use the darker values github.com uses today, so they stay readable on the code box background. The code box keeps its own background and border.
• Label document dates on Korean pages as 작성일 and 수정일 instead of 처음 작성 and 다시 정리. Pages in other languages keep Created and Revised.
• Give body headings more room: a section heading sits 28px below its divider and 14px above its text, and subheadings and h4 headings leave 10px above their text.

0.23.1 — 2026-10-27

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the figure border. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Draw an SVG figure in a box with the same border and padding as Mermaid diagrams, and center it in the box. Raster images keep their current layout.

0.23.0 — 2026-10-27

Upgrade: Existing projects remain compatible, except that a document whose frontmatter already uses created or revised for anything other than a YYYY-MM or YYYY-MM-DD date now fails the build; earlier versions ignored both keys. Rebuild and redeploy to apply the new figure and Details layout. CLI commands, configuration and Node.js requirements are unchanged.

• Add optional created and revised frontmatter dates, written as YYYY-MM or YYYY-MM-DD. They appear under the document title in small gray text, as Created 2022-12, Revised 2026-10, or 처음 작성 2022-12, 다시 정리 2026-10 on Korean pages. A different format, a day that does not exist or a revised date earlier than created fails the build with the file and the key.
• Use the last frontmatter date, revised or else created, as the page’s <lastmod> in sitemap.xml when it is written with the day. Month-only dates and home pages get no <lastmod>.
• Lay out an image that is alone in its paragraph as a figure, with the same space above and below as tables and code blocks. On screens narrower than 640px, an SVG figure keeps the width and height written in the file and scrolls sideways like a wide table instead of shrinking its text, and keyboard users can focus and scroll it. Raster images and wider screens keep their current size.
• Mark Details titles with + while collapsed and − while open instead of the browser’s triangle, give a collapsed title the same space above and below, and let Details written one after another share one divider.

0.22.1 — 2026-10-27

Upgrade: Existing projects remain compatible. Only package metadata and documentation links change. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Point the package repository, issue tracker and documentation links to github.com/nomeehej/for-humanity after the GitHub account rename.

0.22.0 — 2026-10-26

Upgrade: Existing projects remain compatible. Sites without locales render as before, except that sitemap.xml now declares the xhtml namespace on <urlset>. To add a translation, set locales in the configuration and put its README.md and public folder under content/<code>/.

• Add locales for translated documents. Each language code is a folder under the content root, the URL prefix and the lang of its pages, and files at the same relative path are translations of each other. The sidebar lists the current language only, and a page that exists in two or more languages shows a language line above its body that links to each translation. With url, pages that exist in two or more languages get hreflang alternate links in the head and in the sitemap, with the default language as x-default. A plain parent in a translated document resolves within its language, and a parent in another language fails the build.
• Serve the official documentation in English at the root and in Korean under /ko/, with links between translated pages.

0.21.1 — 2026-10-26

Upgrade: Existing projects remain compatible. Rebuild and redeploy to apply the desktop navigation spacing. CLI commands, configuration, document syntax and Node.js requirements are unchanged.

• Leave the same 64px space below the end of the desktop sidebar and outline as below the document, so long lists no longer stop flush against the bottom of the window.

0.21.0 — 2026-10-23

Upgrade: Existing projects remain compatible. dev and preview still listen on localhost unless --host or host is set. The build output, document syntax and Node.js requirements are unchanged.

• Add opt-in LAN access to dev and preview with --host, --host <address> or the host configuration. CLI options take precedence over configuration; the default remains localhost. The default dev command also accepts for-humanity --host.

0.20.0 — 2026-10-23

Upgrade: Rebuild and redeploy for the narrower layout and new 404 screen. statusImage is optional. If an older .cloudflare/prepare.mjs copies 404.html unconditionally, remove that copy or copy only when the output is absent; keep _headers preparation. Rename any document that would generate /404.html/, such as public/404.html.md, because 404.html is now reserved. Node.js requirements and the other existing CLI and configuration options are unchanged.

• Reduce the default desktop page width from 1920px to 1600px.
• Add a centered, theme-aware 404 page with a sad variant of the pixel face and a home link. Generate 404.html for every hosting target, use the same screen in dev and preview, and keep generated screens when Cloudflare helpers prepare deployment files. Set statusImage to a local image to replace the artwork; existing favicon and cursor artwork remain unchanged. The 404.html document path is now reserved for the generated error page.

0.19.0 — 2026-10-23

Upgrade: Existing projects remain compatible. The dev, build and preview commands, configuration, document syntax and Node.js requirements are unchanged. New sites can select Cloudflare Workers during init; existing Cloudflare Pages and GitHub Pages setups remain supported. Rebuild and redeploy to include the first-paint fix.

• Add init --deploy cloudflare-workers with a Worker name prompt and --worker-name for automation. Generate wrangler.jsonc, a 404 page, cache headers, a build helper and docs:deploy for npm or pnpm. Preserve existing Wrangler dependencies and stop before writing when a Wrangler configuration already exists.
• Hold the first paint of a built page until the inline browser script has run. On a slow device the sidebar and outline could appear at the top for one frame before their saved positions were restored. Chromium honors the new <link rel="expect" blocking="render"> in the page head; other browsers ignore it and behave as before.

0.18.0 — 2026-10-22

Upgrade: Existing projects remain compatible. The dev, build and preview commands, configuration, document syntax and Node.js requirements are unchanged. New projects can start with for-humanity init instead of copying the template.

• Add for-humanity init [project-dir] with interactive site, folder, language and hosting setup. Choose suggested values or type a custom answer directly in the same question. Clack provides wider, responsive boxes for questions, answers, the three setup stages, file review and next commands; --yes and explicit options support automation.
• Generate GitHub Pages workflows for npm or pnpm and derive the site URL and repository path. Cloudflare Pages setup includes a 404 page and a build helper for the selected content folder. Existing application scripts and dependencies are preserved; conflicts stop before writing, and failed writes restore this run’s changes.

0.17.0 — 2026-10-22

Upgrade: Existing root deployments remain compatible. For a GitHub project site, set basePath: "/repository/" and keep url as the origin, such as https://username.github.io. Rebuild and deploy the contents of content/dist.

• Add basePath for project sites such as https://username.github.io/project/. Navigation, document links, images, fonts, Mermaid and crawler URLs use the same path in dev, build and preview; / remains the default and the output directory stays content/dist.
• Include a GitHub Pages Actions workflow in template/github-pages.yml and document separate project-site deployments.

0.16.0 — 2026-10-21

Upgrade: CLI commands, configuration, document syntax and Node.js requirements remain compatible. Document pages now use each label as their description, so write labels that read well in search results and link previews. Pages are still marked as Korean by default; set lang, such as lang: "en", for sites in other languages.

• Describe each document page with its own label in the description meta tag. Every page used to repeat the site description, or had no description when it was not set.
• Add a lang setting for the page language, such as en or en-US. Pages were always marked as Korean, and ko stays the default. A value that is not a language tag stops with lang must be a language tag such as ko or en-US.
• Add a canonical link and Open Graph and Twitter card tags to every page when url is set, with the same addresses as sitemap.xml. Shared links now preview with the document name and label.
• Add an image setting for the link preview image, a PNG, JPEG, GIF or WebP file given relative to the content folder, such as asset/preview.png. With url set, every page gets an og:image tag that points to a fingerprinted copy. A missing file stops with Invalid asset: <path> (file not found).
• Give local PNG, JPEG, GIF, WebP and AVIF images their original width and height, so text below an image no longer moves down while it loads. A size written on a raw <img> is kept, and SVG images are left without size attributes.
• Underline links in document text so they stand out without relying on color. Links used to be underlined only on hover.
• Let keyboard users focus and scroll wide tables, and mark the site name and menu button as the page header for screen readers.
• Land anchor links near the top of the screen again, 80 pixels down on desktop and below the fixed header on mobile, and switch the outline at that line. On tall screens the outline used to mark a later heading as soon as a page opened.

0.15.0 — 2026-10-21

Breaking change: The build now fails, with the file and line, on input that earlier versions accepted: a ::part without a plain-text title, with attributes or without a ## section before the next part; a selected snippet region without an end marker; a non-image file such as a PDF in a Markdown image, <img>, srcset or poster; a raw HTML <video>, <audio> or <source> that points to a missing local file or to a format other than MP4, WebM or MP3; a raw HTML <track>, <embed> or <object> that points to a missing local file or to a format other than WebVTT, PDF or an image; and a raw HTML <h1> or <h2> inside a Note or Details block. Write each part as ::part[Title] followed by a ## section, add the missing end marker, link non-image files instead of embedding them, add missing media files, convert other media to MP4, WebM or MP3 or serve it from an absolute or external URL, and move raw <h1> and <h2> headings out of Note and Details blocks. See the 0.15.0 migration steps.

Upgrade: CLI commands, configuration and Node.js requirements remain unchanged. Run build after updating and fix each reported file and line; the new link warnings do not stop the build. Raw HTML <h2> and <h3> headings now get anchors, so a later Markdown heading with the same text gets a -1 suffix. Sidebar scroll positions saved by older versions start from the top once.

• Collect local files in raw HTML srcset, <video> src and poster, <audio> and <source> with fingerprinted URLs, and accept MP4, WebM and MP3. A missing file or an unsupported format now fails the build with the file and line instead of shipping a broken relative URL.
• Collect local WebVTT files in raw HTML <track> and PDF or image files in <embed> and <object> the same way, and warn with Link to a local file that is not published about an <iframe> that points to a local file, which the build cannot publish.
• Answer byte range requests for local files in dev with 206 Partial Content, so Safari plays local video and audio there.
• Fail the build with unsupported image format when a Markdown image or <img> points to a file that is not an image, such as a PDF. Such a file used to be copied and shown as a broken image.
• Fail the build with the file and line when ::part has no name, as in ::part or ::part[], a title with links, emphasis or code, or attributes, as Note and Details already do. An unnamed part now reports Invalid part syntax: part needs a non-empty title instead of rendering an empty part divider and an empty outline group.
• Fail the build when a ::part has no ## section before the next part or the end of the document, and report a :::part block as part must be written as a ::part[...] line instead of Unknown part. The earlier of two parts used to disappear from the outline.
• Fail the build with Invalid part syntax: note cannot contain # or ## headings and the file and line when a raw HTML <h1> or <h2> is inside a Note or Details block, as Markdown # and ## headings already do.
• End a snippet region at a nameless // #endregion, <!-- #endregion --> or /* #endregion */, which closes the innermost open region, and fail with region not closed when the selected region has no matching end marker. The rest of the file used to leak into the snippet.
• Accept # region markers in Python, YAML and shell snippets and #pragma region markers in C and C++ snippets, and read <!-- #region name--> as the region name.
• Give raw HTML <h2> and <h3> headings anchors and outline entries, and wrap raw HTML tables in the same scroll box as Markdown tables. Automatic anchors skip ids already written in raw HTML.
• Warn with Link to a missing document and the file and line when a raw HTML link such as <a href="missing.md"> points to a missing document, as Markdown links already do.
• Warn with Link to a local file that is not published and the file and line when a link points to a local file that the build does not copy, such as [source](code.ts).
• Keep a colon in Note, Details and part titles such as 예:이것. Note and Details used to reject the title, and the outline cut a part title at the colon.
• Serve the first page in dev even when a document changes while the site is still being prepared. The first request used to fail with HTTP 500 until the next change.
• Build a home README that starts with a code block and puts a snippet inside a Note or Details block. The build used to fail with a code fence error.
• Keep Markdown links with a URL scheme such as web+app:notes.md as written. They used to be rewritten as document links and reported as missing.
• Report a YAML syntax error in frontmatter as Invalid frontmatter: <file>: <reason> with the line number in the document, and print YAML warnings with the file and line, instead of messages without the document path.
• Ignore the words good, bad and line-numbers inside a code block file title such as [good.ts]. They used to turn on the colored background or line numbers.
• Show a color swatch only for 3, 4, 6 or 8 digit hex colors such as #e80030. Values such as #12345 now render as plain inline code.
• Keep sidebar scrolling light on large sites by saving a short signature of the document list with each scroll position instead of the whole document tree.

0.14.2 — 2026-10-20

Upgrade: CLI commands, configuration, document syntax and Node.js requirements remain unchanged.

• Keep the cursorFace pixel face at the last mouse position after a reload in Chromium on Windows. Chromium briefly turned off its display condition just before leaving the page, which dropped the position and failed the Windows browser check NAV-010.
• Show CLI help, build errors and warnings, and the diagram failure notice in English, for example Invalid asset: ./missing.png (file not found).
• Report a link or image path with a malformed % escape as Invalid percent-encoding with its file and line, instead of failing with URI malformed.
• Skip Markdown files inside dist, .git and node_modules folders at any depth of the document folders instead of failing the build, and treat these folder names case-insensitively when checking references.
• Keep a Details block closed after you close it, even when diagrams render again, for example after a theme change. A block opened by the address hash used to reopen.
• Join the page and site names in browser tab titles with a vertical bar, for example Writing | for humanity, instead of a middle dot.

0.14.1 — 2026-10-19

Upgrade: CLI commands, configuration, document syntax and Node.js requirements remain unchanged.

Known issue: The intermittent Windows cursor check (NAV-010) fails again in CI, and its cause is being investigated. See Maintenance.

• Reorganize the documentation site into Start, Guide and Updates. Installation has its own page, Commands covers command options and troubleshooting, and the changelog is published with update instructions. The Reference and Releases pages are removed; their content is in Commands, Settings, Writing and Changelog.
• Let the mouse wheel scroll the document over the document list and the outline when they fit on screen. Chrome previously kept the wheel inside them.
• Restore the scroll position instantly when reloading or going back to an address with a heading, without first jumping to the heading or sliding down from the top.
• End documents with a regular section margin instead of nearly a screen of blank space. Over the last screen, the outline steps through the remaining headings in order, and a heading opened from a link stays marked until you scroll.
• Land anchor links with the heading at 40% of the screen height instead of near the top, and switch the outline at the same line.
• Land anchor links in the last screen exactly where the outline switches to them, so clicking an outline entry never briefly marks another heading.

0.14.0 — 2026-10-19

Breaking change: Configuration now belongs in the project root. CLI paths identify a project, not a Markdown folder. Move published documents into content/public, local-only documents into content/private, and the site home into content/README.md; use content.root, content.public and content.private to customize these paths. Existing flat document folders are not automatically published. See the migration guide. Node.js 22.12.0 or later is still required.

• Focus public documentation on installation, configuration, authoring and deployment. Keep internal plans, release operations, development history and fictional project studies in local-only content.
• Show both document collections in dev; build and preview only the public site in content/dist.
• Preserve public document URLs and reserve /private/ for local internal pages. Exclude internal pages, navigation data, sitemap entries and their assets from public builds.
• Reject public references to internal Markdown, images and snippets, including raw HTML and symlink targets.
• Move this repository’s documentation to content and its configuration to the project root.
• Include a reusable template/ starter with public/private folders and document migration from flat Markdown projects.
• Reject content-root symlinks into build output, Git metadata and installed dependencies.

0.13.1 — 2026-10-16

Upgrade: CLI commands, configuration and Node.js requirements remain unchanged. Navigation scroll positions saved by older versions may reset once after upgrading.

Known issue: The previously recorded intermittent Windows cursor check (NAV-010) remains deferred. See Maintenance.

• Let Zustand persist own navigation scroll storage and hydration; remove direct storage reads, legacy layout-key compatibility and duplicate restoration helpers.
• Validate saved navigation positions once with a shared Zod schema, discard malformed snapshots, and compare navigation data without traversing DOM links on every scroll event.
• Keep code-block and caption backgrounds in the prose stylesheet, remove inline container colors and token overrides outside their owner, and share metadata decisions across both elements.

0.13.0 — 2026-10-16

Upgrade: Node.js 22.12.0 or later is now required; upgrade Node before installing. Existing dev, build, preview commands and .mjs configurations remain supported. To use typed configuration, replace the .mjs file with for-humanity.config.ts; keep only one configuration file per document folder. Development and preview servers bind to localhost.

Known issue: The Windows browser check for cursor visibility after a reload (NAV-010) intermittently fails. The other browser checks and installed-package dev/preview checks pass; further cursor lifecycle investigation is deferred. See Maintenance.

• Render page titles, metadata and resource tags with a request-local Unhead server instance; deduplicate links, preserve literal metadata text, and keep CSS and font loading in the initial HTML.

• Use Citty for CLI commands and help/version output, reject unsupported options and extra paths before running, and format build results and document warnings with Consola.

• Load source development CSS through HTML stylesheet links before the first paint; preserve CSS HMR and refresh the stylesheet list when files are added or removed.

• Mark the prebuilt Mermaid module URL as an intentional runtime import to avoid Vite development warnings while preserving lazy loading.

• Serve static previews through Vite with explicit site output paths, document 404s and preserved font cache headers; bind to localhost, reject missing builds and occupied ports, and remove the direct Hono Node server dependency.

• Share document preparation and Hono routes between static builds and a single Vite development server; replace custom file watching and SSE with Vite updates, preserve the last valid document snapshot, and support source TSX reloads and CSS HMR.

• Avoid an extra browser reload after the first successful development request; verify recovery from an invalid initial document and shutdown after a pending file change.

• Pre-optimize browser JSX runtimes to prevent missing development chunks, and retain the last mouse position when reloading after window focus is lost.

• Remove seven unused color and radius tokens and align the design reference with the active styles.

• Replace direct esbuild package and browser fixture builds with Vite 8 and shared typed build configuration; preserve synchronous browser initialization and Mermaid license notices.

• Raise the package minimum Node.js version to 22.12.0 and include Vite for the development and preview commands.

• Support for-humanity.config.ts and publish a documented SiteConfig input type and generated declarations; retain .mjs support and reject duplicate configuration files.

• Type-check build and maintenance tools, exclude repository tests from packages, and verify configuration types in an installed consumer project.

• Split CLI and navigation checks into isolated scenarios with Korean GIVEN/WHEN/THEN conventions and Playwright failure reports.

• Fix relative links from nested documents on Windows and clean up Mermaid load errors when their widget unmounts.

• Run repository tests with standalone Vitest and split Mermaid browser checks into isolated Playwright scenarios with failure traces.

• Replace the custom ASCII grid renderer with locally hosted Mermaid 12, loaded only on pages with diagrams, with official themes, system dark mode and isolated SVG styles.

• Support Mermaid’s built-in diagram types, including Tree View, and add a diagram writing guide with flowchart, sequence, state, ER and tree examples.

• Keep readable diagram source when JavaScript is disabled or loading/rendering fails. Diagram syntax errors now appear in the browser instead of stopping the build.

0.12.0 — 2026-10-13

• Add a [file name] fence meta that draws a title bar with the file name and language above the code block, sharing the bad/good tone.

0.11.0 — 2026-10-13

• Add <<< ./file.ext#region meta code snippet imports: a file inside the document root becomes a code block, with optional #region extraction, dedent, fence meta passthrough and dev reloads when the file changes.
• Add bad and good fence meta that tint the whole code block, with line notation drawn one step darker on top.

0.10.0 — 2026-10-13

• Add VitePress-style code notation through Shiki transformers: // [!code highlight|error|warning|++|--], // [!code word:name], meta {2,4-6} and a line-numbers meta that numbers lines with CSS counters.
• Remove the bad/good code labels added in 0.9.0; mark the lines instead.
• Draw tables and flowchart boxes with the same border color as code blocks.

0.9.1 — 2026-10-13

• Draw tables with an outer border and cell borders, box flowcharts with a border, and separate sections with a solid rule and 64px of space.
• Tint the whole code block of a bad or good label instead of relying on the caption, so a label can carry its reason as a code comment.

0.9.0 — 2026-10-13

• Add code labels: a fence meta of bad or good with an optional title renders the code block with a colored left stripe and a caption, keeping Shiki highlighting.
• Give table header rows a soft background and a solid rule, widen the space above sections to 44px and subsections to 28px, and set section headings to 15px so long reference pages read in blocks.

0.8.1 — 2026-10-13

• Render tab-indented code blocks at four columns per tab instead of the browser default of eight.

0.8.0 — 2026-10-13

• Add a cursorFace site setting for the pixel face that follows the mouse on desktop. It is off by default; this documentation site turns it on.
• Add an optional port site setting for the dev and preview servers, defaulting to 4321, so two document projects can run side by side; preview now reads and validates the site configuration too.

0.7.1 — 2026-10-11

• Set Hangul in body text, labels, inline code and the site name in bundled IBM Plex Sans KR, the source of Monoplex KR’s Hangul, at its natural width; Latin stays in Monoplex KR, and code blocks and flowcharts keep two-cell Hangul for the grid.
• Tighten letter spacing to -0.03em for body text, labels and inline code, -0.04em for h2 and parts and -0.045em for h1; code blocks and flowcharts stay at 0 for the grid.
• Narrow the document navigation and outline sidebars from 240px to 200px and let the body fill the rest of a page up to 1920px instead of a 900px column, keeping the 32px gaps; show the outline from 1360px so the body stays about 800px or wider.

0.7.0 — 2026-10-06

• Replace Pretendard and JetBrains Mono with bundled Monoplex KR for body text, labels, code and flowcharts; align the flowchart grid to its 1:2 Latin–Hangul widths.
• Remove tree lines from the document navigation and page outline, keeping nesting through indentation.
• Remove the expand/collapse buttons and their saved branch choices; nested documents and headings are always shown.
• Tighten navigation and outline rows to 16.8px with a 1.4 line height and share a 16px gap between groups; style On this page like the group labels.

0.6.0 — 2026-10-04

• Generate robots.txt and sitemap.xml in dev and static builds when an optional public root url is configured; include home and encoded document URLs, and leave projects without a URL unchanged.
• Validate public HTTP(S) origins and reject crawler-file document path collisions before processing; document Cloudflare crawler policy and Markdown negotiation separately.

0.5.0 — 2026-10-04

• Place document loading, Markdown processing and server setup under the CLI owner; keep document tree construction under navigation and share a standalone shell-controls widget through a lifecycle-managed Hono browser root.

• Consolidate browser behavior into a single Hono JSX shell entry, with component-owned anchor effects, dev reload subscriptions and an independent cursor widget that cleans up events and timers.

• Separate CLI and browser entry folders and move package build/test commands into repository scripts using the esbuild API.

• Generate page HTML with Hono JSX and remove the React server renderer and dependencies.

• Render interactive navigation with Hono client JSX components and Hooks, including native event handlers, persisted branch state, drawer focus and scroll restoration before the first paint. Keep the Markdown body as server-generated HTML.

• Use equal 240px document and outline sidebars at 1536px and wider, showing the outline only on wide screens and keeping document navigation in the mobile drawer.

• Add separate expand/collapse buttons to document groups, parent documents, outline parts and headings with children, with every branch expanded by default.

• Persist branch choices through Zustand vanilla stores in localStorage and independent wide, desktop and drawer scroll positions in sessionStorage, restoring layout and saved choices before the first paint.

• Compile a synchronous Hono JSX navigation entry to mount branch controls before the first paint, avoiding their reappearance after page navigation and function-string serialization.

• Match idle branch controls to the tree line color and keep persistence contracts in src/store/navigation.

0.4.4 — 2026-10-04

• Keep the document list and page outline in separate native scroll areas, so a shorter outline cannot clamp the document list position.
• Restore desktop document navigation before its first paint and avoid reinserting the same navigation DOM during startup.
• Indicate remaining navigation content with conditional top and bottom fades, keeping native scrollbars in forced colors and without JavaScript.
• Connect the active outline branch through its parent while highlighting only the exact current heading.

0.4.3 — 2026-10-04

• Use standard native navigation scrollbars in forced-color mode so browser color adjustment cannot hide custom thumbs against the background.

0.4.2 — 2026-10-04

• Preserve sidebar and mobile drawer scroll positions across document navigation and reloads within a tab, independently of the main content.
• Show thin native navigation scrollbar thumbs on hover or keyboard focus, with a transparent track, Firefox thin fallback and system colors in forced-color environments.
• Explain when related sections belong in one page’s headings and when a separate child document is appropriate.

0.4.1 — 2026-10-04

• Coalesce consecutive document and asset saves and serialize dev refreshes so bulk AI edits cannot start overlapping full-site renders and exhaust memory.
• Continue queued and later edits after failed processing, and apply only the latest valid generation.

0.4.0 — 2026-10-04

• Copy explicitly referenced local images and supported attachments to fingerprinted asset URLs, resolving paths relative to their Markdown files in both build and dev.
• Support reference-style images and raw HTML image sources, preserve query/hash suffixes, and reject missing files, unsupported local image formats and paths or symlinks outside the document root.
• Reload referenced image and attachment changes in dev while retaining the previous valid document and resource map after failed processing.
• Mark only the current table-of-contents anchor as active, with aria-current="location", while retaining the tree path through its ancestors.
• Add image documentation, purpose-based authoring guidance and fictional design and research examples.
• Keep legacy type: document and type: blueprint inputs compatible, recommend omitting type, and focus the roadmap on reusable visualization and theme modules rather than a dedicated Blueprint renderer.

0.3.0 — 2026-10-04

• Support nested document pages with optional parent IDs, preserving existing groups and document URLs.
• Resolve ./ and ../ parent references relative to document files so project folders can also be used as document roots.
• Reject missing parents, self references, parent cycles and parent links across different group paths.
• Extend active, hover and keyboard focus tree paths through clickable parent documents.
• Distinguish sidebar groups from document links and page headings, and rename the table of contents to “On this page” with a gray label matching the groups.
• Clarify trunk-based development, site deployment and package release policy.

0.2.1 — 2026-10-04

• Fingerprint stylesheet and browser-script URLs so new pages cannot reuse assets cached from an older deployment.
• Cache fingerprinted CSS, scripts and fonts with immutable headers on Cloudflare Pages.

0.2.0 — 2026-10-04

• Support nested navigation with group name arrays while keeping single-name groups compatible.
• Order nested sibling groups with paths in navigation, independently of document folders.
• Extend active, hover and keyboard focus tree paths through ancestor groups.

0.1.2 — 2026-10-03

Documentation and release automation update. The CLI commands and Node.js requirement are unchanged.

• Link the README to the public documentation site, npm package and GitHub Releases.
• Set the package homepage to https://for-humanity.fyi.
• Deploy the documentation from main to Cloudflare Pages and preserve installation commands in served HTML.
• Verify pull requests and publish npm plus GitHub Release from matching stable version tags using Trusted Publishing.
• Add official Releases and Changelog pages to the documentation site, with the changelog generated from this file.
• Accept both npm 11 array reports and npm 12 package-keyed reports when validating release artifacts.

The v0.1.1 attempt stopped during package validation and was not published to npm.

0.1.0 — 2026-10-03

First public release of the Markdown documentation CLI. Requires Node.js 22 or later.

• dev, build and preview commands for a document folder or the project root.
• Static HTML, CSS, a browser script, self-hosted fonts and a favicon.
• A README home page, grouped navigation, a table of contents, Markdown links and highlighted code.
• Notes, disclosures, Mermaid flowcharts, status badges and color swatches.
• System light and dark themes, mobile navigation and keyboard access.
• Root AGENTS.md and CLAUDE.md excluded from the document list.

init, search and deployment under a URL subpath are planned. Static output currently assumes the site root /.