# Documenter.jl: the documentation generator that the Julia ecosystem is built around > Documenter.jl turns Markdown pages and Julia docstrings into a hosted documentation site, with cross-references checked at build time so a broken link fails the build instead of shipping. It is the reference documentation tool for Julia packages, and the ecosystem around it is maintained by the same organisation. **JuliaDocs/Documenter.jl** — A documentation generator for Julia. - Repository: https://github.com/JuliaDocs/Documenter.jl - Website: https://documenter.juliadocs.org - Stars: 924 · Forks: 518 - Language: Julia - License: MIT - Published: 2026-10-20 · Updated: 2026-10-20 · Language: en - Canonical page: https://hysenlabs.com/projects/juliadocs-documenter-jl ## What Documenter solves: reference docs that break silently Documenter is a documentation generator for Julia, and the problem it solves is narrow and specific: producing API reference documentation for a Julia package, together with hand-written prose pages, as a website that a package manager can host. The interesting part is not the HTML output. It is the checking. A documentation system for a dynamically typed language has one recurring failure, and it is that a name mentioned in prose stops existing. You rename a function, the docstring follows it, but the tutorial that tells the reader to call it by the old name still calls it by the old name, and nothing complains until a reader tries it. Documenter addresses that by turning cross-references into build-time assertions. A reference that cannot be resolved fails the build. That converts a documentation failure mode from a runtime surprise for a reader into a red build for the author, which is the single reason many Julia packages use it. The audience is package authors and the maintainers of shared libraries. The project is not a general purpose static site generator that happens to be written in Julia, and the tooling around it, from the JuliaDocs organisation's own extensions to the third party integrations, all assume a Julia package context. It is also the default choice in practice. When the ecosystem lists alternative tools such as Franklin.jl, Publish.jl and Weave.jl, those are described as similar packages filling a slightly different niche, which tells you where Documenter sits. ## Installation through the Pkg REPL, and the two documentation branches Installing Documenter is a package manager operation, and the documentation gives both routes. From the Julia REPL, press `]` to enter Pkg REPL mode and run: ```bash pkg> add Documenter ``` The equivalent through the Pkg API is a single line: ```bash julia> import Pkg; Pkg.add("Documenter") ``` Either way the package joins the active project environment, and it is added as a development dependency of your own package rather than as a runtime dependency, so it never ends up in the load path of someone who installs your code. The project publishes two documentation sets. The stable one documents the most recently tagged version, and the development one documents the in-development version. The distinction matters more in Julia than in many ecosystems, because a Julia package version is what pins a set of dependency versions, so the stable docs correspond to a reproducible environment and the dev docs correspond to the current tip of the branch. The support matrix is stated plainly: the package is tested against and being developed for Julia 1.6 and above, on Linux, macOS and Windows. Community support runs through the Julia Discourse forum under the documenter tag, the #documentation channel of the Julia Slack, and the JuliaDocs chat room. Usage questions are the stated purpose of those channels, while contributions go through issues and pull requests following the contributing guidelines. ## The repository layout tells you what a build actually involves Documenter's own repository is a working example of what it expects from a project, so it is worth reading as a template. The root holds `src/`, `test/`, `docs/`, `assets/`, a `Project.toml` for the package itself and a `Makefile` that drives the whole workflow. There is also a `CHANGELOG.md`, a `coverage/` directory and configuration files for formatting and linting: `JuliaFormat.toml`, `biome.jsonc`, `.typos.toml` and `.prettierrc`. The `docs/` directory contains its own `Project.toml` and `make.jl`, and the Makefile targets show how a documentation build is wired. The environment is instantiated separately from the package environment: ```bash ${JULIA} --project=docs -e 'using Pkg; Pkg.instantiate()' ``` and the build itself runs the documentation script in that same isolated environment: ```bash ${JULIA} --project=docs docs/make.jl ``` That separation is the important architectural point. The documentation environment is its own Julia project, so the versions used to build the site are pinned in `docs/Manifest.toml` and do not drift with the package's own dependency tree. Two variants of the build target exist. The normal one is `docs`, and there is a second one described in the Makefile as the same command intended for testing things while developing, where you want to avoid builds erroring. ```bash ${JULIA} --project=docs docs/make.jl strict=false ``` That `strict=false` flag is the escape hatch for day-to-day work: it keeps the build going while you are still writing, and it is what separates a working session from a release build. ## Strict mode is the feature: why the build is allowed to fail The strictness switch is worth understanding on its own, because it explains how the project is used in practice. In strict mode, an unresolvable cross-reference is an error and the build stops. Outside strict mode, the same condition is a warning and the build completes. That gives a package author two working modes without two sets of configuration. While writing a page you run the lenient build and see everything, including the broken references. Before tagging, you run the strict build and the build fails if anything is unresolved, which is exactly the check you want in continuous integration. The repository's own CI configuration backs this up. The workflow badges in the project documentation cover the main build status, a separate regression test workflow, code coverage and a PkgEval report, so the documentation build, the regression tests and package evaluation are tracked as distinct things rather than one green tick. The Makefile also shows that documentation work is not limited to the site. There is a changelog target that runs a separate script, `docs/changelog.jl`, which means the release notes are generated through the same toolchain rather than by hand. Two housekeeping targets are worth noting because they show how the repository treats generated artefacts as disposable. The clean target removes the manifests and the generated release notes file, along with the build directories under `docs/`, and it removes the temporary directories that the docstring link, doctest and error test fixtures create under `test/`. The effect is that a stale manifest or a leftover build directory is never a source of confusion, since everything in that list is derived and can be regenerated. ## The ecosystem around Documenter is as important as the generator A documentation generator is rarely used alone, and the project documentation is unusually clear about the ecosystem around it. The JuliaDocs organisation maintains five extensions. DocumenterCitations.jl handles citations, DocumenterInterLinks.jl handles links between separate packages, DocumenterMarkdown.jl adds Markdown processing, DocumenterTools.jl provides supporting tooling, and LiveServer.jl serves the documentation locally while you work on it. Third party packages compose with it in other ways. DemoCards.jl builds interactive example cards, Literate.jl turns plain source files, including notebooks, into documentation pages, QuizQuestions.jl embeds questions in the docs, DocumenterMermaid.jl renders Mermaid diagrams, and DocumenterDiagrams.jl produces diagrams. The distinction the project draws is useful. The first group extends Documenter itself and is maintained alongside it. The second group integrates with it from outside, which means a version of Documenter can break them and the fix lands in a different repository. That is the usual cost of a plugin ecosystem, and it is the reason the list is published in the README rather than assumed. Then there are the alternatives that fill a slightly different niche: Franklin.jl, Publish.jl and Weave.jl. The difference in approach is that these are not primarily an API reference generator with prose attached. Franklin treats a site as a collection of Markdown and Julia files with its own conventions, and Weave is built around literate programming, executing code as it documents it. If you want executed, verified output in your docs, that is a different requirement from checking that your cross-references resolve. The practical question for a team is which of those two problems you actually have. ## Where Documenter is the wrong tool Several boundaries are clear from the project structure and stated support matrix. The first is that it is Julia only. The parser understands Julia docstrings, the docstrings are read from a Julia session during the build, and the whole workflow assumes the Pkg package manager. A team wanting one documentation setup across Python, Rust and Julia code will not get that here. The second is the theme workflow. Documenter builds documentation for packages, not marketing sites, and the theme assets live in the repository's own `assets/` directory with a dedicated Makefile target that delegates to a separate makefile in that directory. Building a heavily customised brand theme is possible, but the documented path is oriented towards API reference sites, and the effort goes into a site shape that assumes a package layout. The third is the release rhythm. The recent tags are v1.19.0 on 2026-09-02, v1.18.0 on 2026-08-31 and v1.17.0 on 2026-02-20, and the last push was on 2026-10-16. A major version boundary therefore arrives periodically, and a package that depends on Documenter in its documentation build has to absorb that. The documentation itself is published as two tracks, stable and development, which is a reasonable way to signal that a breaking change is on its way. The fourth is that the tool does not write your documentation. It formats and checks it. If the gap in your project is that nobody writes the prose, Documenter will not close that gap, and no generator in this family will. ## MIT licensed, released often, and maintained in the open The licence is MIT, which for a tool that every Julia package may end up using in its own build is the practical choice. There is no copyleft obligation on a project that chooses to build its docs with it, and the licence file is in the repository root as `LICENSE.md`. The project is not archived and the last push was on 2026-10-16, with three tagged releases inside the preceding eight months. The activity is visible in the tooling as well: the Makefile targets run Runic for Julia formatting, including extensions and docstrings, and Biome for JavaScript formatting, with separate install targets for each so the formatting tools are pinned in their own project environments. The `install-biome` target pins a specific version rather than tracking latest. That last detail is worth reading as a signal about how the project treats reproducibility. Documentation builds that break because a formatter changed are a recurring source of lost afternoon, so the tools are pinned, the environments are separated, and generated artefacts are listed for deletion by a clean target. The remaining commitment is procedural. The contributing page has guidelines that should be followed when opening pull requests, and the documentation asks that problems be reported as issues first. Both are ordinary open source hygiene, but they are listed here because they are part of the contract with anyone who depends on the tool. The licence does not extend to whatever a package author writes in their own docstrings, and none of this is legal advice: it simply means the generator is permissively licensed while the prose it renders remains yours. ## Conclusion Documenter.jl suits a Julia package author who wants hosted docs built from docstrings and Markdown with broken cross-references caught at build time. It does not suit a project outside Julia, since it parses Julia docstrings and depends on the Julia package manager, and it does not suit a team that needs a general site generator with a theme editor rather than an API reference. Before adopting it, read the contributing guidelines, check the supported Julia version against your own, and add the doctest and cross-reference checks to continuous integration, since the build is where its value actually shows up. ## FAQ ### How do I install Documenter.jl? From the Julia REPL, press `]` to enter Pkg REPL mode and run `pkg> add Documenter`, or use the Pkg API with `julia> import Pkg; Pkg.add("Documenter")`. You would normally add it to the development dependencies of your own package. ### Which Julia versions does Documenter.jl support? The package is tested against, and being developed for, Julia 1.6 and above, on Linux, macOS and Windows. ### How do I build the documentation locally for Documenter.jl? The repository's Makefile has a `docs` target that instantiates the separate documentation environment with `${JULIA} --project=docs -e 'using Pkg; Pkg.instantiate()'` and then runs `${JULIA} --project=docs docs/make.jl`. A lenient variant passes `strict=false` so that a developing build does not error out. ### What packages extend Documenter.jl? The JuliaDocs organisation maintains DocumenterCitations.jl, DocumenterInterLinks.jl, DocumenterMarkdown.jl, DocumenterTools.jl and LiveServer.jl. Third party integrations listed include DemoCards.jl, Literate.jl, QuizQuestions.jl, DocumenterMermaid.jl and DocumenterDiagrams.jl. ### How do I ask a question about Documenter.jl? Usage questions can be posted on the Julia Discourse forum under the documenter tag, in the #documentation channel of the Julia Slack, or in the JuliaDocs chat room. Bugs and feature requests should be filed as issues on the repository. ## Sources - [JuliaDocs/Documenter.jl on GitHub](https://github.com/JuliaDocs/Documenter.jl) - [License: MIT](https://github.com/JuliaDocs/Documenter.jl/blob/master/LICENSE) - [Project website](https://documenter.juliadocs.org) - [README](https://github.com/JuliaDocs/Documenter.jl/blob/master/README.md) - [Releases](https://github.com/JuliaDocs/Documenter.jl/releases) --- Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/juliadocs-documenter-jl