Documentation Publishing: Choosing the Right Static Tooling

When choosing a publishing tool, I first check whether it can use the existing files and who will maintain the build, theme and extensions. Appearance matters, but does not answer those questions.

This page compares common generators and uses this site to explain customization costs. It is a selection note, not a requirement to build the same website.

Generator and host responsibilities

A static site generator reads content, navigation configuration and themes at build time, producing HTML, CSS, JavaScript and other files. A host provides an address and serves those files to browsers.

1. 01Maintain the sourceText, images, and content structureMarkdown / AsciiDoc, etc.
2. 02Generate the siteProcess content, navigation, and themeDocusaurus / Antora, etc.
3. 03Publish for readersHost the output at a web addressNetlify / GitHub Pages, etc.

Content formats, generators, and hosts serve different purposes. The toolchain must match the source format.

Static pages can still be interactive: this site's exercises run JavaScript in the browser. Static generation does not imply incremental builds; support depends on the tool and configuration.

Start with content and maintenance capacity

These are judgments based on common needs, not performance rankings. Verify features against the versions, themes and plugins you intend to use.

Tool	When to consider it	Maintenance work
Docusaurus	Markdown/MDX, shared blog and docs, React components	Maintain a Node.js project and check custom themes/components during upgrades
VitePress	Primarily Markdown docs and a team familiar with Vue	Organize extra sections such as a blog and maintain embedded Vue components
MkDocs	Markdown content, Python familiarity, existing themes/plugins	Check compatibility and maintain required customizations
Antora	Existing AsciiDoc spread across repositories and product versions	Organize components, versions and modules; maintain the UI and publishing setup

For a large AsciiDoc collection, evaluate compatible tools before converting it. DITA requires considering editing, content management and publishing tools such as DITA-OT, beyond website themes.

Docusaurus versioning copies current documents and sidebars into versioned directories. It does not automatically create Git branches. Corrections may need to be applied to several retained versions.

Why this site uses Docusaurus

FlowingDocs combines a blog, documentation, Chinese/English content and interactive examples. Docusaurus fits those needs reasonably well. See the original blog setup notes.

• Blog and docs have separate organization: posts follow time and topics; docs follow problems. This site's custom blog plugin needs maintenance during framework upgrades.
• The framework provides locale routes: translations, examples and tag URLs still require checks. A successful build does not establish that every language-switch target exists.
• React components fit into prose: their state, keyboard support, responsive layout and error recovery still require implementation and testing.

These are this site's reasons, not requirements for every documentation project.

Extensions affect portability

Notices depend on the renderer

Docusaurus notation:

:::note[Version note]
This example applies to 2.x.
:::

Rendered here:

Version note

This example applies to 2.x.

A CommonMark-only platform needs a conversion for this extension. It will not automatically produce the same notice. Ordinary blockquotes are usually more portable but look different.

Interactive components need their runtime

import MarkupWorkshop from '@site/src/components/MarkupWorkshop';

<MarkupWorkshop />

This requires the component, its dependencies and a React/MDX environment. Copying the text alone does not transfer the workshop.

My approach is to keep essential explanations in ordinary prose and use interactions where comparison or visible changes clearly help.

Compare editing, building and publishing

This is an illustration. Working, built and reader versions are stored separately to show when changes take effect. It does not build or upload a real site.

Simulation · edit, then build

Try editing, building and publishing

Edit the title or reorder the sidebar below, then run the static build to see the generated page on the right. Theme and view options are under "More".

This page simulates state changes; it does not build or deploy a site.

#

## Pre-flight checks

Verify data directory permissions and port 3306 availability before initialization.

## Operation steps

1. Run mysqld --initialize to generate system tables.
2. Start mysqld daemon via systemctl start mysqld.

Static Generator

IDLE

• 1. Parse Markdown AST
• 2. Resolve Sidebars & Routes
• 3. Bundle Theme & MDX
• 4. SSG HTML Pre-render

example.com/docs/start/

FlowingDocs

• Instance setup
• Storage engines
• Troubleshooting

MySQL Operations Guide

Pre-flight checks

Verify data directory permissions and port 3306 availability before initialization.

Operation steps

1. Run mysqld --initialize to generate system tables.
2. Start mysqld daemon via systemctl start mysqld.

More: theme and views

Theme

Brand Accent Color:

VioletTealSlate

Compact line height

View

DraftBuiltLive

1. 1Source
2. 2Build
3. 3Output
4. 4Live

Try editing the title, reordering sidebars, or toggling themes, then trigger a build.

Simulation only: no Docusaurus build runs and no files are uploaded.

To try a real build, download the minimal Markdown site template and follow its README. It uses Docusaurus 3.9.2 and includes bilingual instructions and practice assets, without all of this site's interactive components.

Before publishing, check key entry points, images, downloads and language switching, then verify the hosted address. A first release can go to a small set of readers and improve based on the problems they encounter.

Next: return to markup practice, or use the author review checklist.