Course Preview
Documentation Publishing Tools
Documentation publishing tools turn plain-text source files into a documentation website, PDF, or API reference that readers can browse. They range from static site generators like Sphinx, MkDocs, and Docusaurus to hosted platforms like Read the Docs and GitBook and generators built specifically for API references. The tool a team picks shapes how it writes, versions, searches, and ships documentation.
itTechnical communication and collaboration | OpenSkills.info
Intro
Documentation Publishing Tools
A documentation publishing tool converts plain-text source into a reader-facing artifact: an HTML site, a PDF, an ePub, or an interactive API reference. It is the layer between what a writer edits and what a reader sees.
These tools fall into three overlapping groups. Static site generators, such as Sphinx, MkDocs, Docusaurus, Hugo, VitePress, Jekyll, and Zola, read source files and configuration and produce prebuilt HTML you can host anywhere. Hosted platforms, such as Read the Docs and GitBook, add build automation, versioning, and hosting around a generator or their own editor. Specialized generators, such as Antora, the DITA Open Toolkit, Doxygen, Swagger UI, and Redoc, target one publishing problem — multi-repository aggregation, structured single-sourcing, source-code comments, or OpenAPI descriptions — rather than general-purpose sites.
The build pipeline
Every generator in this category follows the same shape:
Source files + configuration
|
v
Parser (Markdown, reStructuredText, AsciiDoc, MDX, DITA XML)
|
v
Generator / build process
|
v
Theme + templates -> Rendered pages
|
v
Static output (HTML, PDF, ePub) -> Hosting
Continue the course
This section is part of the paid course.
See pricing to subscribe, or log in if you already have access.
Where this skill leads
Relevant careers
See how this topic contributes to broader role-level skill maps.
Sources
- https://www.mkdocs.org/
Supports
- MkDocs as a Markdown-based static site generator with one YAML configuration file
- Built-in mkdocs and readthedocs themes, plus third-party theme support
- A live-reload development server and static HTML build output
- mkdocs new, mkdocs serve, mkdocs build, and mkdocs gh-deploy commands
- https://www.sphinx-doc.org/en/master/usage/quickstart.html
Supports
- sphinx-quickstart scaffolding a new Sphinx project
- sphinx-build usage and the -b flag for selecting a builder
- The -W flag promoting build warnings to errors
- https://www.sphinx-doc.org/en/master/usage/builders/index.html
Supports
- Sphinx's HTML, LaTeX/PDF, man, texinfo, and text builders
- Multiple output formats generated from one reStructuredText source tree
- https://docusaurus.io/docs
Supports
- Docusaurus as a React-based static site generator using MDX
- Built-in versioning, internationalization, built-in search, and a plugin architecture
- npx create-docusaurus@latest, npm run start, and npm run build commands
- https://opensource.fb.com/projects/docusaurus/
Supports
- Docusaurus created at Facebook Open Source to solve internal documentation duplication
- Adoption by Prettier, Babel, React Native, and KaTeX
- https://docs.readthedocs.com/platform/stable/index.html
Supports
- Read the Docs as a documentation building and hosting platform
- Integrated support for Sphinx, MkDocs, and Docusaurus projects
- Versioned documentation URLs and pull-request preview builds with a visual diff
- https://docs.readthedocs.com/platform/stable/config-file/v2.html
Supports
- The .readthedocs.yaml version 2 configuration schema
- build.os and build.tools.python fields, and the sphinx.configuration field
- https://www.ericholscher.com/blog/2010/aug/16/announcing-read-docs/
Supports
- Read the Docs founded in 2010 by Eric Holscher, Charlie Leifer, and Bobby Grace
- Read the Docs originating as a hackathon project
- https://docs.antora.org/antora/latest/
Supports
- Antora as a static site generator for AsciiDoc content aggregated from one or more Git repositories
- The playbook, component, and module concepts
- The antora command reading a playbook file to build a site
- https://antora.org/
Supports
- Antora's general positioning as a documentation site generator for tech writers
- https://evaparish.com/blog/2018/10/19/antora-and-docusaurus-duke-it-out
Supports
- Antora available as a working, comparable documentation generator by October 2018
- https://gohugo.io/documentation/
Supports
- Hugo built with the Go programming language, distributed as a compiled binary
- Archetypes, content types, menus, cross references, summaries, and asset pipelines
- Community themes for documentation, referenced via themes.gohugo.io
- hugo new site, hugo server, and hugo --minify commands
- https://vitepress.dev/
Supports
- VitePress as a Vite- and Vue-powered static site generator
- Markdown source with embeddable Vue components
- Fast development server and client-side routing after initial load
- https://jekyllrb.com/docs/
Supports
- Jekyll as a static site generator using layouts and a chosen markup language
- Liquid templates and front matter as core site-structure components
- jekyll new and jekyll serve commands
- https://en.wikipedia.org/wiki/Jekyll_(software)
Supports
- Jekyll released by Tom Preston-Werner, a GitHub co-founder, in 2008
- Jekyll written in Ruby
- https://www.noze.it/en/insights/jekyll-1-0/
Supports
- Jekyll's native integration with GitHub Pages
- Jekyll 1.0 released in May 2013, stabilizing the tool as GitHub Pages' reference build engine
- https://www.getzola.org/
Supports
- Zola as a static site generator written in Rust, distributed as a single binary with no external dependencies
- Zola requiring CommonMark-specification Markdown
- zola init, zola serve, and zola build commands
- https://docsify.js.org/
Supports
- Docsify rendering Markdown client-side in the browser with no build step
- Docsify operating as a single-page application driven by one index.html
- https://www.gitbook.com/
Supports
- GitBook as a hosted documentation platform
- GitBook's docs-as-code Git Sync support alongside browser-based editing
- GitBook's use for product docs, API docs, help centers, and knowledge bases
- https://www.mintlify.com/docs
Supports
- Mintlify as a hosted documentation platform generating from MDX, source code, and OpenAPI specifications
- Mintlify's interactive API playgrounds and AI-oriented search
- https://readme.com/documentation
Supports
- ReadMe as a hosted API documentation platform
- ReadMe's interactive API reference that lets readers call the API with their own API key
- ReadMe generating a dynamic API reference from an uploaded OpenAPI spec
- https://www.dita-ot.org/
Supports
- The DITA Open Toolkit as an open-source publishing engine for DITA XML content
- DITA-OT's plug-in mechanism and HTML and PDF (via XSL-FO) output
- https://www.dita-ot.org/dev/topics/prerequisite-software.html
Supports
- DITA Open Toolkit requiring a Java Runtime Environment or JDK
- https://www.oasis-open.org/2005/05/31/members-approve-dita-as-oasis-standard/
Supports
- OASIS members approving DITA version 1.0 as an OASIS Standard in 2005
- https://redocly.com/docs/redoc
Supports
- Redoc CE producing web-ready documentation from an OpenAPI description, including Swagger 2.0
- Redoc's three-panel layout and deployment as CLI output, HTML, or a React component
- Support for OpenAPI 3.1, 3.0, and 2.0
- https://redocly.com/docs/cli/commands/build-docs
Supports
- The npx @redocly/cli build-docs command and its -o/--output option
- redoc-static.html as the default output filename
- https://swagger.io/docs/
Supports
- Swagger UI parsing an OpenAPI specification into an interactive documentation site
- The interactive "try it out" request panel
- Swagger Editor, Swagger UI, Swagger Codegen, and SwaggerHub as related SmartBear tools
- https://github.com/swagger-api/swagger-ui/blob/master/docs/usage/configuration.md
Supports
- The swaggerapi/swagger-ui Docker image and its SWAGGER_JSON, PORT, and BASE_URL environment variables
- https://www.doxygen.nl/manual/index.html
Supports
- Doxygen generating documentation from source-code comments
- HTML as Doxygen's most popular output format, alongside RTF and other formats
- Markdown support, grouping, tables, and graph/diagram generation
- doxygen -g and doxygen Doxyfile commands
- https://en.wikipedia.org/wiki/Doxygen
Supports
- Doxygen's first release, version 0.1, on 26 October 1997 by Dimitri van Heesch
- https://en.wikipedia.org/wiki/Sphinx_(documentation_generator)
Supports
- Sphinx's initial release on 21 March 2008
- Sphinx created to replace Python's LaTeX-based documentation for the Python 2.6 release
- https://en.wikipedia.org/wiki/MkDocs
Supports
- MkDocs initially released on 24 January 2014, created by Tom Christie
- https://www.linuxfoundation.org/press/press-release/new-collaborative-project-to-extend-swagger-specification-for-building-connected-applications-and-services
Supports
- The Linux Foundation announcing the OpenAPI Initiative on 5 November 2015
- SmartBear donating the Swagger specification as the basis of the new open specification
- Founding member organizations including 3Scale, Apigee, Capital One, Google, IBM, Intuit, Microsoft, PayPal, Restlet, and SmartBear
- https://github.com/OAI/OpenAPI-Specification/releases
Supports
- OpenAPI Specification 3.0.0 released on 26 July 2017
- https://github.com/squidfunk/mkdocs-material
Supports
- Material for MkDocs created by Martin Donath, copyrighted from 2016
- Material for MkDocs as the most widely used third-party MkDocs theme
- https://docsearch.algolia.com/docs/what-is-docsearch/
Supports
- Algolia DocSearch's crawler-based indexing and query frontend
- DocSearch free for eligible open source and public technical documentation sites, subject to attribution
- https://github.com/unicodeveloper/awesome-documentation-tools/blob/master/README.md
Supports
- A curated community list of documentation tools including documentation.js, Stoplight, ExDoc, and Pydoctor
- https://documentation.js.org/
Supports
- documentation.js generating HTML, Markdown, or JSON from JSDoc or Flow annotations
- documentation.js inferring exported functions and parameter types
- https://stoplight.io/
Supports
- Stoplight as a collaborative OpenAPI design and documentation platform
- Stoplight's visual editor for creating and sharing OpenAPI descriptions
- https://hexdocs.pm/ex_doc/readme.html
Supports
- ExDoc generating HTML, Markdown, and EPUB documentation for Elixir and Erlang projects
- ExDoc's automatic cross-linking between modules, functions, and dependencies on hexdocs.pm
- https://pydoctor.readthedocs.io/
Supports
- pydoctor as a Python API documentation generator built by the Twisted project
- pydoctor working by static analysis and producing static HTML output
- https://swagger.io/tools/swagger-ui/
Supports
- Swagger UI as an open-source tool for rendering OpenAPI descriptions as interactive documentation