Documenter.jl is a documentation generator for the Julia programming language. It builds documentation by processing docstrings and Markdown files.

Key features include:

• Markdown-based: Write all documentation using Markdown syntax.
• Doctests: Automatically executes and verifies Julia code blocks within your documentation.
• Cross-references: Supports linking between documentation pages and section headers.
• LaTeX Support: Provides support for $\LaTeX$ syntax.
• Validation: Checks for missing docstrings and broken cross-references.
• Automation: Generates tables of contents, docstring indexes, and supports automated deployment via GitHub Actions to GitHub Pages or other CI providers.

The HTMLWriter component uses non-Julia assets for styling and layout. These assets are organized into SCSS source files and compiled CSS themes:

• SCSS Sources (scss/): Contains the raw Sass/SCSS files used to build the themes.
  • scss/bulma/: The base Bulma CSS framework (v0.9.4).
  • scss/darkly/: The Darkly Bulmaswatch theme (v0.8.1).
  • scss/documenter/: Custom Documenter-specific overrides and components.
  • documenter.scss and darkly.scss: The primary source files for Documenter's default themes.
• Compiled Themes (themes/): Contains the final, ready-to-use .css files generated from the SCSS sources.

The following areas are not part of the public API and are subject to change without notice:

• Internal Hooks: Any logic that hooks into Documenter's internals (e.g., adding custom build steps or renderers) is not guaranteed to remain stable. Clean plugin APIs are a long-term goal, but current internal extension points may change.
• Generated Output Structure: The HTML, TeX, or file structure of generated documents is not guaranteed unless explicitly documented. This includes CSS classes in HTML themes; custom CSS overrides that rely on specific theme classes may break.
• Visual Design: The look and feel of the HTML UI and generated PDFs may change significantly between minor versions.
• Experimental Features: Anything marked as experimental is subject to change in the next minor version.

The search system uses a two-phase architecture to provide full-text search for documentation sites:

1. Build-time (Julia): During site generation, a Julia-based indexer processes documentation content and generates a searchable index file (search_index.js).
2. Runtime (JavaScript): A client-side interface uses the MiniSearch library to perform real-time searches. To ensure the UI remains responsive, the search execution is offloaded to a Web Worker (background thread).

This architecture ensures that heavy search computations do not block the main UI thread, providing a smooth user experience even on large documentation sites.

By default, every doctest block is evaluated in its own isolated module. Definitions (variables, functions, etc.) created in one block are not available in the next.

To share scope between multiple blocks, assign them the same label. All blocks with the same label in a single file will be evaluated in the same module. Labeled blocks do not need to be consecutive; they can be separated by unlabeled blocks or blocks with different labels.

```jldoctest mylabel
julia> foo = 42
42

julia> println(foo)
42

To pull inline docstrings from your Julia code into your Markdown files, use the @docs block.

By default, @docs blocks are evaluated in the Main module. If the objects you are documenting belong to a different module, you must either:

1. Use a @meta block to change the module context for that page.
2. Specify the full qualified name (e.g., MyModule.func).

Multiple objects can be included in a single block by placing them on separate lines.

func(x)

Or with a module context:

CurrentModule = Example

func(x)

By default, Documenter.jl deploys documentation into versioned subfolders based on Git tags and branches:

• Tagged Releases: Documentation built from a tag matching <tag_prefix>vX.Y.Z (where tag_prefix defaults to "") is stored in a folder named vX.Y.Z.
• Development Builds: Documentation built from the devbranch (defaults to master) is stored in a folder determined by the devurl keyword (defaults to dev).
• Stable Link: Documenter automatically creates a stable link that points to the latest release (e.g., https://USER_NAME.github.io/PACKAGE_NAME.jl/stable). It is recommended to use this link instead of specific versioned URLs.

Unless using a custom domain, URLs follow this pattern: https://USER_NAME.github.io/PACKAGE_NAME.jl/vX.Y.Z or https://USER_NAME.github.io/PACKAGE_NAME.jl/dev.

The client-side search uses the MiniSearch library with specific configurations to optimize for documentation:

• Fields: It indexes title and text fields.
• Store Fields: It returns location, title, text, category, and page for rendering results.
• Tokenization: Uses a custom tokenizer that splits strings by spaces, hyphens, or dots (/[\s\-\.]+/).
• Search Options:
  • prefix: true: Enables prefix matching.
  • boost: { title: 100 }: Heavily weights matches found in titles.
  • fuzzy: 2: Enables fuzzy matching with a distance of 2.
• Stop Words: Uses a modified version of the Lunr 2.1.3 stop words list, specifically tuned to preserve Julia-specific symbols (like @ and !) that are semantically important.

Documenter supports multiple output formats through different writer modules. The primary writers available are:

• HTMLWriter: The standard writer for generating HTML-based documentation.
• HTMLWriter.RD: A specialized writer within the HTML suite, likely handling specific Markdown/RD formats.
• LaTeXWriter: A writer used to generate LaTeX-based documentation, suitable for PDF generation.

These writers are typically invoked during the Documenter.generate_documentation process based on the configuration provided.

By default, each code block is evaluated in a clean, separate context. To share state between blocks, use Named Blocks.

Named @example blocks

Assign a name to an @example block to allow subsequent blocks with the same name to access the same variables.

x = 40

x + 1

@setup blocks

Use ```@setup block-name ``` for code that sets up state but should not be visible in the generated documentation. It acts as a hidden @example block.

x = 42

Continued blocks

You can use continued = true in an @example block to prevent it from evaluating immediately. This is useful for defining multi-line logic that is completed by a later block with the same name.

y = 99

Documenter can automatically generate links to publicly hosted Git repositories (like GitHub, GitLab, or Forgejo) for source code and 'edit this page' links. There are two types of remote configurations:

1. Project repository remote: Specified via the repo keyword in makedocs. This is used for the main repository landing page and issue references.
2. File link remotes: Specified via the remotes keyword in makedocs. These map local filesystem paths to remote repository paths, used for generating edit links for Markdown files and source links for Julia docstrings.

In most simple package setups, you don't need to specify either, as Documenter attempts to automatically detect the repository via the Git origin URL.