如何把五種文件來源整合成一個文件網站

If your repository mixes languages, you almost certainly ship four kinds of documentation that four different tools generate: the HTTP API reference from OpenAPI, the C and C++ pages from Doxygen, Go and Rust pages from godoc and rustdoc, and the guides sitting in a Markdown folder that every tool renders differently. Each generator brings its own theme, its own search, and its own idea of where output belongs.

The fix is boring and effective: treat documentation as a build artifact. Leave every source where it already lives, then run a single build that turns all of them into one static site.

Why static, and why one build

Static HTML has three properties that matter in 2026. It hosts anywhere: a bucket, a CDN, a small VPS, or a folder inside the repo. It needs no runtime, so it cannot rot when a server dependency breaks. And it can be read by anything, including the agents people now point at documentation.

A single build matters because readers do not care which generator produced which page. They want one search box, one navigation tree, one place where the version number is correct. If the API reference says 2.4.0 and the guide says 2.3.1, trust is gone.

What the build has to ingest

A realistic project needs at least three of these sources:

• OpenAPI or Swagger definitions for the HTTP API.
• Doxygen XML for C and C++ code.
• godoc for Go packages.
• rustdoc for Rust crates.
• Markdown for guides, tutorials, and changelogs.
• MCP server definitions, if the project exposes tools to agents.

Each source already has a canonical extractor. Doxygen parses C and C++ comments into XML. godoc reads Go doc comments. rustdoc ships with cargo. OpenAPI is a YAML file. The only real decision is what renders the final site.

The tool landscape, briefly

Doxygen plus a theme is still the standard for C and C++, and it now emits usable HTML on its own. Sphinx owns the Python world and handles Markdown through MyST. MkDocs with Material is the default for Markdown-first projects and is easy to wire into CI. Redoc and Swagger UI render OpenAPI well but stop there; they do not know about the rest of your documentation.

There is also a newer option worth a look: Sourcey, a free, self hosted documentation generator that takes OpenAPI, MCP, Doxygen, godoc, rustdoc, and Markdown in the same build and outputs static HTML. It is AGPL-3.0, installs with npx sourcey init, needs Node 22 or newer, and ships four themes with custom CSS. The detail I care about is that the same build also emits llms.txt, OpenAPI, and API catalogs, so agent facing readers get machine readable versions without a second pipeline. You can see the engine at https://sourcey.com/docs and the source at github.com/sourcey/sourcey.

A layout that works

Keep sources under docs/ and let the build own build/site:

docs/
  guides/*.md
  openapi.yaml
  doxygen/Doxyfile
src/                # godoc and rustdoc read from here

A CI job runs the extractors first, then the site build, then deploys build/site to your host. Cache the extractor outputs; Doxygen on a large C++ tree is the slow step, and it does not need to rerun when only a guide changed.

Two rules keep this honest. First, the version string comes from one file, not from prose. Second, a broken link fails the build, not the reader's afternoon.

Search and the agent question

Client side search over static files works fine up to a few thousand pages. Past that, prebuild the index at build time and ship it as a static asset.

The agent question is newer. If your product exposes an MCP server or an API that agents call, your docs are part of the interface. Agents do not click; they fetch. Serving llms.txt, a clean OpenAPI file, and plain HTML without JavaScript requirements costs almost nothing and removes a whole class of failures. A documentation build that emits these by default saves you from bolting them on later.

What I would do first

Pick the one build that already understands your largest source. Add the other sources one at a time. Deploy the static output somewhere boring. Then spend the remaining time on the guides, because the generator was never the hard part.

Documentation is a product surface. Treat the build like code: versioned, tested, deployed on every merge. The rest is details.