YDoc builds a documentation site from markdown and a plugin list

A generator with plugins and themes as its extension points

YDoc is described as an elegant documentation site building tool that generates a complete static site from markdown, so you can concentrate on writing. The interesting part is not the generation, which most markdown tools do, but the two extension points it defines. The first is plugins, and the published list shows the kind of work they cover. There is ydoc-plugin-copy for quickly copying the code snippet of a generated page, ydoc-plugin-import-asset for pulling js and css files into a page, ydoc-plugin-jsdoc which generates documentation from code comments on the basis of jsdoc, and ydoc-plugin-pangu, which inserts whitespace between Chinese characters and half-width English, digits and symbols on the page, a typographic convention usually called pangu spacing. The second extension point is themes, with ydoc-theme-demo and ydoc-theme-dark as the published ones, and the repository carries a theme/ directory of its own. So a site is assembled by choosing a theme, adding plugins, and pointing it at markdown. That is a smaller and more legible model than a framework with a configuration object.

Installing the CLI and generating a first site

The install is a global npm package.

npm install -g ydoc

There is also a release candidate channel published separately, and the README gives the command with the global flag as optional.

npm install ydoc@rc [-g]

Once installed, two commands take you from nothing to a site. The first scaffolds a project and the second builds it.

ydoc init
ydoc build

The manifest defines the binary as ydoc pointing at bin/ydoc, with the module entry point at src/index.js. Because the tool is a global command rather than a library you import, the same install works on a developer machine and in a CI job, and the build step becomes a single line in a pipeline. That is the shape most teams want from a documentation generator. The examples directory in the repository shows the four starting points the project ships, a homepage, an init example, a plugin example and a theme example, so the intended workflow is copy an example, edit it, run the build.

The runtime stack is a 2018 stack

The dependency list is where the age of the project shows, and it matters for anyone considering it today. The runtime dependencies include markdown-it at ^8.4.0, cheerio at ^0.20.0 for HTML manipulation, koa at ^2.4.1 with koa-static, chokidar for file watching, prismjs for syntax highlighting, ora for the spinner, fs-extra, yargs for the command line, underscore, and watch. The engines field says node >=7.6.0. The dev dependencies pin mocha at ^4.1.0, node-sass at ^4.7.2, which is the native binding that is the most likely thing to fail to build on a modern Node, and rewire for testing internals. The project uses mocha with the spec reporter and the bail flag for its test script, and the build script runs ydoc build followed by a shell build step, while a separate buildCss script runs the theme build in watch mode. For a tool that only reads markdown and writes HTML, the dependency footprint is on the heavy side, and the version pins are the practical obstacle rather than the design.

Plugins are separate packages, not built-in options

Two things are worth understanding about how plugins are distributed. First, the plugin list in the README is not the whole set, it points to a plugin index page for more. Second, several of the plugins are also declared as dependencies of the project itself, which is how the default site gets its behaviour: ydoc-plugin-copy, ydoc-plugin-demo, ydoc-plugin-edit-page, ydoc-plugin-execution-time, ydoc-plugin-img-view, ydoc-plugin-import-asset and ydoc-plugin-search are all listed in the dependencies alongside the two themes. The search plugin is the one most projects will care about, since a documentation site without search is a documentation site nobody navigates, and it ships enabled by default here. The edit-page plugin is the other one worth noting, because it points at a theme that supports editing, which is the natural way to turn a static documentation site into something contributors can update. The mechanism is npm packages that the generator loads, so a plugin written for your own organisation is a package you publish and add, not a fork.

Themes, contributors and the project's own site

Themes are treated the same way as plugins, as separately published packages, with ydoc-theme-demo and ydoc-theme-dark being the two in the list. The repository holds a theme/ directory and a src/ directory, so the shipped theme and the generator live side by side, and a _site/ directory is checked in for the project's own documentation, which is deployed to the GitHub Pages site at hellosean1025.github.io/ydoc. The development setup is a plain npm project with eslint and a .npmignore for publishing, and the test directory and an eslint configuration sit alongside the source. The people behind it are listed individually, dwb1994 and zwjamnsss for development and design, lwg529 for development, and sean1025 for development, and the project asks for pull requests and for contributions of new plugins, with issues and pull request links given directly. The licence is Apache 2.0, recorded in the package manifest and with a LICENSE file in the root of the repository, and the documentation is published in both Chinese and English, with a separate README-en.md file for the English version.

Where YDoc is the wrong tool

Three cases. The first is a team that wants a documentation site with a current, maintained toolchain. The generator's own dependencies are pinned to versions from around 2018, the Node engine floor is stated as 7.6.0, and node-sass in the dev dependencies is the component most likely to fail to compile on a current Node release, so a team that runs bleeding edge Node will spend time on a toolchain problem rather than on documentation. The second is a project that needs features the plugin list does not cover, since the ecosystem here is a handful of npm packages maintained by the same small group, and there is no published roadmap in the documentation to tell you what is coming. The third is a project that needs documentation generated from typed source, because the jsdoc integration is the only code-derived path offered and it is built on jsdoc rather than on a typedoc style pipeline. The maintenance picture supports taking that seriously. The only tagged release is v4.0.0 from 2018-03-29, while the package manifest reads version 4.1.3, and the last push to the repository was on 2026-04-10. The project is not archived, but the gap between the published release and the working tree is a fact worth knowing before you depend on it, and the version you install from npm is the one to pin.

Editorial conclusion

Adopt YDoc if you want a documentation site that is entirely markdown and are comfortable wiring up the plugin and theme packages yourself, since the project ships as a small command line tool with a documented plugin list. Skip it if you need a generator with a current dependency tree, because the runtime dependencies are pinned to versions from 2018 and the engine field still says node >=7.6.0, and skip it if you need a maintained community around the project. Before you start, read the theme and plugin documentation, run ydoc init and ydoc build to see the default output, and pin the version you use, since the published release tags stop at v4.0.0 from 2018 while the package manifest reads 4.1.3.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. YMFE/ydoc on GitHub