Bazel Central Registry

@rules_docs@rules_docs//docgen:defs.bzl

Public API for docgen rules.

Functions & Macros

docs

Generate documentation from markdown files.

This macro creates a documentation target that processes markdown files and generates
a navigation structure. It can either use an existing entry file or generate one from
provided content.

Parameters

`name`	Name of the documentation target. Defaults to "docs". Default: `"docs"`
`entry`	The entry point markdown file for the documentation. If the file doesn't exist, it will be generated with content from readme_content. Defaults to "README.md". Default: `"README.md"`
`srcs`	List of source markdown files to include in the documentation. Defaults to ["README.md"]. Default: `["README.md"]`
`data`	Additional data files to include (images, assets, etc.). Default: `[]`
`deps`	Documentation dependencies - other docs/docs_index/docs_link targets. Default: `[]`
`title`	Title of the documentation section. If not provided, defaults to the package name. Default: `None`
`nav`	Navigation structure dictionary. Keys can be: "path/to/file.md": "Display Name" for markdown files ":link_target": "Display Name" for docs_link targets ":docs_target": "Display Name" for other docs targets ":index_target": "" for docs_index targets (empty string uses index's title) Default: `{}`
`out`	Output directory for generated documentation. If not specified, uses the target name. Default: `None`
`readme_content`	Content for the generated entry file if it doesn't exist as a file. Default: `""`
`readme_header_links`	Dictionary of links to add to the README header. Format same as nav. Default: `{}`
`kwargs`	Additional arguments passed to the underlying docs_action rule.

docs_action_impl

Implementation function for docs_action rule.

Processes documentation files and generates output with proper linking and file dependencies.

Parameters

*ctx

The rule context.

docs_index

Create a nested navigation structure for organizing documentation.

This macro creates a documentation index that can be referenced in the nav structure
of other docs targets. It allows building hierarchical navigation without duplicating
entries.

Parameters

`name`	Name of the index target. Defaults to "docs". Default: `"docs"`
`title`	Title of the navigation section. This will be used as the display text when referenced with an empty string in a parent nav dictionary. Default: `None`
`entry`	Optional entry point file for the index. If provided, clicking the index will navigate to this file. Default: `None`
`nav`	Navigation structure dictionary for this section. Same format as docs() nav: "path/to/file.md": "Display Name" for markdown files ":link_target": "Display Name" for docs_link targets ":docs_target": "Display Name" for other docs targets ":index_target": "" for nested docs_index targets Default: `{}`
`kwargs`	Additional arguments passed to the underlying docs_action rule.

Rules

docs_action

Processes documentation files and generates output with proper linking and file dependencies.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`title`	`string`	The title of the navigation element Default: `""`
`entrypoint`	`label`	The entrypoint file for the documentation Default: `None`
`srcs`	`list of labels`	The files that are part of the documentation Default: `[]`
`out`	`string`	The output directory for the documentation Default: `""`
`data`	`list of labels`	The data files that are part of the documentation Default: `[]`
`deps`	`list of labels`	The dependencies of the documentation Default: `[]`
`nav`	`dictionary: Label → String`	Sub navigation elements Default: `{}`
`rewrite_path`	`string`	The path prefix to rewrite documentation files to Default: `""`
`readme_filename`	`string`	The filename of the README.md file Default: `"README.md"`
`readme_content`	`string`	The content of the README.md file Default: `""`
`readme_header_links`	`dictionary: Label → String`	The links to add to the README.md file Default: `{}`

docs_link

Define an external link to be used in documentation navigation.

This rule creates a link target that can be referenced in the nav structure of
docs or docs_index targets. It's useful for adding external URLs to your
documentation navigation, such as links to external resources, API references,
or related projects.

Example:
docs_link(
name = "github",
title = "GitHub Repository",
url = "https://github.com/username/repo",
)

docs(
    name = "docs",
    nav = {
        "README.md": "Home",
        ":github": "Source Code",  # Reference the link
    },
)

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`title`	`string`	The title of the navigation element Default: `""`
`url`	`string`	The URL of the navigation element Default: `""`
`entrypoint`	`string`	The entrypoint file for the documentation Default: `""`
`data`	`list of labels`	The data files that are part of the documentation Default: `[]`

docs_add_last_updated

Add "last updated" timestamps to documentation files from git history.

This rule processes documentation files and adds metadata about when each file
was last modified according to git history. The timestamps are extracted from
a JSON file generated by git_last_updated_timestamps and inserted into the
documentation files.

Example:
git_last_updated_timestamps(
name = "timestamps",
srcs = glob(["docs/**/*.md"]),
out = "last_updated.json",
)

docs_add_last_updated(
    name = "docs_with_timestamps",
    docs = ":docs",
    last_updated_json = ":timestamps",
    out_dir = "docs_updated",
)

The updated documentation files will be available in the specified output directory
and can be used as input to mkdocs_build or mkdocs_serve.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*last_updated_json`	`label`	JSON file with a key->value mapping of file paths to last updated timestamps
`*docs`	`label`	The docs to add last updated information to
`out_dir`	`string`	The output directory for the docs with last updated information Default: `""`
`last_updated_date_format`	`string`	The date format to use for last updated timestamps Default: `"+%B %d, %Y at %I:%M %p"`
`update_history_url`	`string`	The URL to the update history Default: `""`

mkdocs_build

Build a static MkDocs documentation site.

This rule processes documentation targets and generates a static website using MkDocs.
The output is a directory containing all the HTML, CSS, JavaScript, and asset files
needed to deploy the documentation site.

Example:
mkdocs_build(
name = "site",
config = ":mkdocs_config",
docs = [":docs"],
site_dir = "site",
)

The built site can then be found in bazel-bin/<package>/<name>/<site_dir>.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*mkdocs_executable`	`label`	The mkdocs executable. Defaults to @mkdocs//:mkdocs from the docgen extension.
`docs`	`list of labels`	The docs to include in the site Default: `[]`
`data`	`list of labels`	The data files to include in the site Default: `[]`
`*config`	`label`	The mkdocs.yml file
`docs_dir`	`string`	The directory containing the docs Default: `"docs"`
`site_dir`	`string`	The output directory for the site Default: `"site"`
`root_nav_folder`	`string`	The root nav folder Default: `""`
`use_default_shell_env`	`boolean`	Use the default shell environment Default: `False`

mkdocs_config

Generate an MkDocs configuration file from a template.

This rule takes a base MkDocs YAML configuration template and merges it with
the navigation structure from a docs target. The result is a complete mkdocs.yml
file that can be used with mkdocs_build or mkdocs_serve.

Example:
mkdocs_config(
name = "mkdocs_config",
docs = ":docs",
mkdocs_base = "mkdocs.tpl.yaml",
)

The base template should contain all MkDocs settings except the 'nav' section,
which will be automatically generated from the docs target.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`title`	`string`	The title of the site Default: `""`
`docs`	`label`	The docs to include in the site Default: `None`
`*mkdocs_base`	`label`	The base mkdocs.yml file
`root_nav_folder`	`string`	The root nav folder Default: `""`

mkdocs_serve

Serve MkDocs documentation locally for development.

This rule creates an executable that runs the MkDocs development server,
allowing you to preview your documentation with live reload support.
When used with ibazel, changes to source files will automatically rebuild
and reload the documentation in your browser.

Example:
mkdocs_serve(
name = "mkdocs.serve",
config = ":mkdocs_config",
docs = [":docs"],
)

Run with:
bazel run //:mkdocs.serve
# or for live reload:
ibazel run //:mkdocs.serve

The server will be available at http://localhost:8000 by default.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*mkdocs_executable`	`label`	The mkdocs executable. Defaults to @mkdocs//:mkdocs from the docgen extension.
`docs`	`list of labels`	The docs to include in the site Default: `[]`
`git_folder`	`label`	The git files to use to get last updated information Default: `None`
`data`	`list of labels`	The data files to include in the site Default: `[]`
`*config`	`label`	The mkdocs.yml file
`docs_dir`	`string`	The directory containing the docs Default: `"docs"`
`root_nav_folder`	`string`	The root nav folder Default: `""`

git_last_updated_timestamps

Extract last updated timestamps from git history for documentation files.

This rule queries git history to determine when each file was last modified
and outputs the results as a JSON file. The JSON maps file paths to Unix
timestamps representing the last commit time for each file.

Example:
git_last_updated_timestamps(
name = "timestamps",
srcs = glob(["docs/**/*.md"]),
out = "last_updated.json",
git_dir = ".git",
filter_extensions = ["md", "rst"],
)

The output JSON can then be used with docs_add_last_updated to annotate
documentation files with their modification times.

Note: This rule requires git to be available and the repository to have
git history. It uses the USE_DEFAULT_SHELL_ENV to access the git command.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`git_dir`	`string`	Path to the .git directory Default: `".git"`
`srcs`	`list of labels`	Source files to track (git directory contents) Default: `[]`
`out`	`string`	Output JSON file name Default: `"git-timestamps.json"`
`filter_extensions`	`list of strings`	List of file extensions to filter Default: `["md", "rst", "txt"]`

Providers

DocsProviderInfo

Provider to specify docs information, such as files and navigation title

Fields

`title`	The title of the navigation element
`entrypoint`	The entrypoint file for the documentation
`files`	The files that are part of the documentation
`nav`	The sub navigation elements

DocsLinkInfo

Provider to specify a link to docs (external URL or internal path)

Fields

`title`	The title of the navigation element
`url`	The URL of the navigation element
`entrypoint`	The entrypoint file for the documentation
`files`	The files that are part of the documentation

@rules_docs@rules_docs//docgen:extensions.bzl

Extensions for bzlmod.

Module Extensions

docgen

Tag Classes

mkdocs

Attribute	Type	Description
`name`	`name`	The name of this mkdocs toolchain. Only used in the root module. Default: `"mkdocs"`
`pypi_hub`	`label`	Name of the pip repository hub that contains mkdocs Default: `"@default_pypi"`
`plugins`	`list of strings`	List of mkdocs plugins to install Default: `[]`

@rules_docs@rules_docs//docgen:repositories.bzl

Declare runtime dependencies

Repository Rules

mkdocs_repository

Fetch external tools needed for docgen toolchain

Attribute	Type	Description
`*name`	`name`	A unique name for this repository.
`repo_mapping`	`dictionary: String → String`	In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). This attribute is not supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).
`*pypi_hub`	`label`	Name of the pip repository hub that contains mkdocs
`plugins`	`list of strings`	List of mkdocs plugins to install Default: `[]`

@rules_docs@rules_docs//docgen/private:docs_action.bzl

Internal documentation processing actions.

Functions & Macros

docs_action_impl

Implementation function for docs_action rule.

Processes documentation files and generates output with proper linking and file dependencies.

Parameters

*ctx

The rule context.

Rules

docs_action

Processes documentation files and generates output with proper linking and file dependencies.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`title`	`string`	The title of the navigation element Default: `""`
`entrypoint`	`label`	The entrypoint file for the documentation Default: `None`
`srcs`	`list of labels`	The files that are part of the documentation Default: `[]`
`out`	`string`	The output directory for the documentation Default: `""`
`data`	`list of labels`	The data files that are part of the documentation Default: `[]`
`deps`	`list of labels`	The dependencies of the documentation Default: `[]`
`nav`	`dictionary: Label → String`	Sub navigation elements Default: `{}`
`rewrite_path`	`string`	The path prefix to rewrite documentation files to Default: `""`
`readme_filename`	`string`	The filename of the README.md file Default: `"README.md"`
`readme_content`	`string`	The content of the README.md file Default: `""`
`readme_header_links`	`dictionary: Label → String`	The links to add to the README.md file Default: `{}`

@rules_docs@rules_docs//docgen/private:docs_add_last_updated.bzl

Rules for adding last updated timestamps to documentation.

Rules

docs_add_last_updated

Add "last updated" timestamps to documentation files from git history.

Example:
git_last_updated_timestamps(
name = "timestamps",
srcs = glob(["docs/**/*.md"]),
out = "last_updated.json",
)

docs_add_last_updated(
    name = "docs_with_timestamps",
    docs = ":docs",
    last_updated_json = ":timestamps",
    out_dir = "docs_updated",
)

The updated documentation files will be available in the specified output directory
and can be used as input to mkdocs_build or mkdocs_serve.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*last_updated_json`	`label`	JSON file with a key->value mapping of file paths to last updated timestamps
`*docs`	`label`	The docs to add last updated information to
`out_dir`	`string`	The output directory for the docs with last updated information Default: `""`
`last_updated_date_format`	`string`	The date format to use for last updated timestamps Default: `"+%B %d, %Y at %I:%M %p"`
`update_history_url`	`string`	The URL to the update history Default: `""`

@rules_docs@rules_docs//docgen/private:docs_index.bzl

Core documentation index processing rules.

Functions & Macros

docs_index

Create a nested navigation structure for organizing documentation.

This macro creates a documentation index that can be referenced in the nav structure
of other docs targets. It allows building hierarchical navigation without duplicating
entries.

Parameters

`name`	Name of the index target. Defaults to "docs". Default: `"docs"`
`title`	Title of the navigation section. This will be used as the display text when referenced with an empty string in a parent nav dictionary. Default: `None`
`entry`	Optional entry point file for the index. If provided, clicking the index will navigate to this file. Default: `None`
`nav`	Navigation structure dictionary for this section. Same format as docs() nav: "path/to/file.md": "Display Name" for markdown files ":link_target": "Display Name" for docs_link targets ":docs_target": "Display Name" for other docs targets ":index_target": "" for nested docs_index targets Default: `{}`
`kwargs`	Additional arguments passed to the underlying docs_action rule.

@rules_docs@rules_docs//docgen/private:docs_link.bzl

Rules for creating documentation links.

Rules

docs_link

Define an external link to be used in documentation navigation.

Example:
docs_link(
name = "github",
title = "GitHub Repository",
url = "https://github.com/username/repo",
)

docs(
    name = "docs",
    nav = {
        "README.md": "Home",
        ":github": "Source Code",  # Reference the link
    },
)

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`title`	`string`	The title of the navigation element Default: `""`
`url`	`string`	The URL of the navigation element Default: `""`
`entrypoint`	`string`	The entrypoint file for the documentation Default: `""`
`data`	`list of labels`	The data files that are part of the documentation Default: `[]`

@rules_docs@rules_docs//docgen/private:docs.bzl

Core documentation processing rules.

Functions & Macros

docs

Generate documentation from markdown files.

This macro creates a documentation target that processes markdown files and generates
a navigation structure. It can either use an existing entry file or generate one from
provided content.

Parameters

`name`	Name of the documentation target. Defaults to "docs". Default: `"docs"`
`entry`	The entry point markdown file for the documentation. If the file doesn't exist, it will be generated with content from readme_content. Defaults to "README.md". Default: `"README.md"`
`srcs`	List of source markdown files to include in the documentation. Defaults to ["README.md"]. Default: `["README.md"]`
`data`	Additional data files to include (images, assets, etc.). Default: `[]`
`deps`	Documentation dependencies - other docs/docs_index/docs_link targets. Default: `[]`
`title`	Title of the documentation section. If not provided, defaults to the package name. Default: `None`
`nav`	Navigation structure dictionary. Keys can be: "path/to/file.md": "Display Name" for markdown files ":link_target": "Display Name" for docs_link targets ":docs_target": "Display Name" for other docs targets ":index_target": "" for docs_index targets (empty string uses index's title) Default: `{}`
`out`	Output directory for generated documentation. If not specified, uses the target name. Default: `None`
`readme_content`	Content for the generated entry file if it doesn't exist as a file. Default: `""`
`readme_header_links`	Dictionary of links to add to the README header. Format same as nav. Default: `{}`
`kwargs`	Additional arguments passed to the underlying docs_action rule.

@rules_docs@rules_docs//docgen/private:git_last_updated_timestamps.bzl

Rules for extracting last updated timestamps from git history.

Rules

git_last_updated_timestamps

Extract last updated timestamps from git history for documentation files.

Example:
git_last_updated_timestamps(
name = "timestamps",
srcs = glob(["docs/**/*.md"]),
out = "last_updated.json",
git_dir = ".git",
filter_extensions = ["md", "rst"],
)

The output JSON can then be used with docs_add_last_updated to annotate
documentation files with their modification times.

Note: This rule requires git to be available and the repository to have
git history. It uses the USE_DEFAULT_SHELL_ENV to access the git command.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`git_dir`	`string`	Path to the .git directory Default: `".git"`
`srcs`	`list of labels`	Source files to track (git directory contents) Default: `[]`
`out`	`string`	Output JSON file name Default: `"git-timestamps.json"`
`filter_extensions`	`list of strings`	List of file extensions to filter Default: `["md", "rst", "txt"]`

@rules_docs@rules_docs//docgen/private:mkdocs_build.bzl

Rules for building MkDocs documentation sites.

Rules

mkdocs_build

Build a static MkDocs documentation site.

Example:
mkdocs_build(
name = "site",
config = ":mkdocs_config",
docs = [":docs"],
site_dir = "site",
)

The built site can then be found in bazel-bin/<package>/<name>/<site_dir>.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*mkdocs_executable`	`label`	The mkdocs executable. Defaults to @mkdocs//:mkdocs from the docgen extension.
`docs`	`list of labels`	The docs to include in the site Default: `[]`
`data`	`list of labels`	The data files to include in the site Default: `[]`
`*config`	`label`	The mkdocs.yml file
`docs_dir`	`string`	The directory containing the docs Default: `"docs"`
`site_dir`	`string`	The output directory for the site Default: `"site"`
`root_nav_folder`	`string`	The root nav folder Default: `""`
`use_default_shell_env`	`boolean`	Use the default shell environment Default: `False`

@rules_docs@rules_docs//docgen/private:mkdocs_config.bzl

Rules for generating MkDocs configuration files.

Rules

mkdocs_config

Generate an MkDocs configuration file from a template.

Example:
mkdocs_config(
name = "mkdocs_config",
docs = ":docs",
mkdocs_base = "mkdocs.tpl.yaml",
)

The base template should contain all MkDocs settings except the 'nav' section,
which will be automatically generated from the docs target.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`title`	`string`	The title of the site Default: `""`
`docs`	`label`	The docs to include in the site Default: `None`
`*mkdocs_base`	`label`	The base mkdocs.yml file
`root_nav_folder`	`string`	The root nav folder Default: `""`

@rules_docs@rules_docs//docgen/private:mkdocs_serve.bzl

Rules for serving MkDocs documentation sites locally.

Rules

mkdocs_serve

Serve MkDocs documentation locally for development.

Example:
mkdocs_serve(
name = "mkdocs.serve",
config = ":mkdocs_config",
docs = [":docs"],
)

Run with:
bazel run //:mkdocs.serve
# or for live reload:
ibazel run //:mkdocs.serve

The server will be available at http://localhost:8000 by default.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*mkdocs_executable`	`label`	The mkdocs executable. Defaults to @mkdocs//:mkdocs from the docgen extension.
`docs`	`list of labels`	The docs to include in the site Default: `[]`
`git_folder`	`label`	The git files to use to get last updated information Default: `None`
`data`	`list of labels`	The data files to include in the site Default: `[]`
`*config`	`label`	The mkdocs.yml file
`docs_dir`	`string`	The directory containing the docs Default: `"docs"`
`root_nav_folder`	`string`	The root nav folder Default: `""`

@rules_docs@rules_docs//docgen/private:providers.bzl

Providers for documentation rules.

Providers

DocsProviderInfo

Provider to specify docs information, such as files and navigation title

Fields

`title`	The title of the navigation element
`entrypoint`	The entrypoint file for the documentation
`files`	The files that are part of the documentation
`nav`	The sub navigation elements

DocsLinkInfo

Provider to specify a link to docs (external URL or internal path)

Fields

`title`	The title of the navigation element
`url`	The URL of the navigation element
`entrypoint`	The entrypoint file for the documentation
`files`	The files that are part of the documentation

@rules_docs@rules_docs//docgen/private:utils.bzl

Utility functions for documentation processing.

Functions & Macros

collect_inputs

Collects and organizes documentation inputs into a directory structure.

Parameters

`*ctx`	Rule context
`root`	Optional root navigation folder Default: `""`

@rules_docs//docgen:defs.bzl

Public API for docgen rules.

Functions & Macros

docs

Generate documentation from markdown files.

This macro creates a documentation target that processes markdown files and generates
a navigation structure. It can either use an existing entry file or generate one from
provided content.

Parameters

`name`	Name of the documentation target. Defaults to "docs". Default: `"docs"`
`entry`	The entry point markdown file for the documentation. If the file doesn't exist, it will be generated with content from readme_content. Defaults to "README.md". Default: `"README.md"`
`srcs`	List of source markdown files to include in the documentation. Defaults to ["README.md"]. Default: `["README.md"]`
`data`	Additional data files to include (images, assets, etc.). Default: `[]`
`deps`	Documentation dependencies - other docs/docs_index/docs_link targets. Default: `[]`
`title`	Title of the documentation section. If not provided, defaults to the package name. Default: `None`
`nav`	Navigation structure dictionary. Keys can be: "path/to/file.md": "Display Name" for markdown files ":link_target": "Display Name" for docs_link targets ":docs_target": "Display Name" for other docs targets ":index_target": "" for docs_index targets (empty string uses index's title) Default: `{}`
`out`	Output directory for generated documentation. If not specified, uses the target name. Default: `None`
`readme_content`	Content for the generated entry file if it doesn't exist as a file. Default: `""`
`readme_header_links`	Dictionary of links to add to the README header. Format same as nav. Default: `{}`
`kwargs`	Additional arguments passed to the underlying docs_action rule.

docs_action_impl

Implementation function for docs_action rule.

Processes documentation files and generates output with proper linking and file dependencies.

Parameters

*ctx

The rule context.

docs_index

Create a nested navigation structure for organizing documentation.

This macro creates a documentation index that can be referenced in the nav structure
of other docs targets. It allows building hierarchical navigation without duplicating
entries.

Parameters

`name`	Name of the index target. Defaults to "docs". Default: `"docs"`
`title`	Title of the navigation section. This will be used as the display text when referenced with an empty string in a parent nav dictionary. Default: `None`
`entry`	Optional entry point file for the index. If provided, clicking the index will navigate to this file. Default: `None`
`nav`	Navigation structure dictionary for this section. Same format as docs() nav: "path/to/file.md": "Display Name" for markdown files ":link_target": "Display Name" for docs_link targets ":docs_target": "Display Name" for other docs targets ":index_target": "" for nested docs_index targets Default: `{}`
`kwargs`	Additional arguments passed to the underlying docs_action rule.

Rules

docs_action

Processes documentation files and generates output with proper linking and file dependencies.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`title`	`string`	The title of the navigation element Default: `""`
`entrypoint`	`label`	The entrypoint file for the documentation Default: `None`
`srcs`	`list of labels`	The files that are part of the documentation Default: `[]`
`out`	`string`	The output directory for the documentation Default: `""`
`data`	`list of labels`	The data files that are part of the documentation Default: `[]`
`deps`	`list of labels`	The dependencies of the documentation Default: `[]`
`nav`	`dictionary: Label → String`	Sub navigation elements Default: `{}`
`rewrite_path`	`string`	The path prefix to rewrite documentation files to Default: `""`
`readme_filename`	`string`	The filename of the README.md file Default: `"README.md"`
`readme_content`	`string`	The content of the README.md file Default: `""`
`readme_header_links`	`dictionary: Label → String`	The links to add to the README.md file Default: `{}`

docs_link

Define an external link to be used in documentation navigation.

Example:
docs_link(
name = "github",
title = "GitHub Repository",
url = "https://github.com/username/repo",
)

docs(
    name = "docs",
    nav = {
        "README.md": "Home",
        ":github": "Source Code",  # Reference the link
    },
)

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`title`	`string`	The title of the navigation element Default: `""`
`url`	`string`	The URL of the navigation element Default: `""`
`entrypoint`	`string`	The entrypoint file for the documentation Default: `""`
`data`	`list of labels`	The data files that are part of the documentation Default: `[]`

docs_add_last_updated

Add "last updated" timestamps to documentation files from git history.

Example:
git_last_updated_timestamps(
name = "timestamps",
srcs = glob(["docs/**/*.md"]),
out = "last_updated.json",
)

docs_add_last_updated(
    name = "docs_with_timestamps",
    docs = ":docs",
    last_updated_json = ":timestamps",
    out_dir = "docs_updated",
)

The updated documentation files will be available in the specified output directory
and can be used as input to mkdocs_build or mkdocs_serve.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*last_updated_json`	`label`	JSON file with a key->value mapping of file paths to last updated timestamps
`*docs`	`label`	The docs to add last updated information to
`out_dir`	`string`	The output directory for the docs with last updated information Default: `""`
`last_updated_date_format`	`string`	The date format to use for last updated timestamps Default: `"+%B %d, %Y at %I:%M %p"`
`update_history_url`	`string`	The URL to the update history Default: `""`

mkdocs_build

Build a static MkDocs documentation site.

Example:
mkdocs_build(
name = "site",
config = ":mkdocs_config",
docs = [":docs"],
site_dir = "site",
)

The built site can then be found in bazel-bin/<package>/<name>/<site_dir>.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*mkdocs_executable`	`label`	The mkdocs executable. Defaults to @mkdocs//:mkdocs from the docgen extension.
`docs`	`list of labels`	The docs to include in the site Default: `[]`
`data`	`list of labels`	The data files to include in the site Default: `[]`
`*config`	`label`	The mkdocs.yml file
`docs_dir`	`string`	The directory containing the docs Default: `"docs"`
`site_dir`	`string`	The output directory for the site Default: `"site"`
`root_nav_folder`	`string`	The root nav folder Default: `""`
`use_default_shell_env`	`boolean`	Use the default shell environment Default: `False`

mkdocs_config

Generate an MkDocs configuration file from a template.

Example:
mkdocs_config(
name = "mkdocs_config",
docs = ":docs",
mkdocs_base = "mkdocs.tpl.yaml",
)

The base template should contain all MkDocs settings except the 'nav' section,
which will be automatically generated from the docs target.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`title`	`string`	The title of the site Default: `""`
`docs`	`label`	The docs to include in the site Default: `None`
`*mkdocs_base`	`label`	The base mkdocs.yml file
`root_nav_folder`	`string`	The root nav folder Default: `""`

mkdocs_serve

Serve MkDocs documentation locally for development.

Example:
mkdocs_serve(
name = "mkdocs.serve",
config = ":mkdocs_config",
docs = [":docs"],
)

Run with:
bazel run //:mkdocs.serve
# or for live reload:
ibazel run //:mkdocs.serve

The server will be available at http://localhost:8000 by default.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`*mkdocs_executable`	`label`	The mkdocs executable. Defaults to @mkdocs//:mkdocs from the docgen extension.
`docs`	`list of labels`	The docs to include in the site Default: `[]`
`git_folder`	`label`	The git files to use to get last updated information Default: `None`
`data`	`list of labels`	The data files to include in the site Default: `[]`
`*config`	`label`	The mkdocs.yml file
`docs_dir`	`string`	The directory containing the docs Default: `"docs"`
`root_nav_folder`	`string`	The root nav folder Default: `""`

git_last_updated_timestamps

Extract last updated timestamps from git history for documentation files.

Example:
git_last_updated_timestamps(
name = "timestamps",
srcs = glob(["docs/**/*.md"]),
out = "last_updated.json",
git_dir = ".git",
filter_extensions = ["md", "rst"],
)

The output JSON can then be used with docs_add_last_updated to annotate
documentation files with their modification times.

Note: This rule requires git to be available and the repository to have
git history. It uses the USE_DEFAULT_SHELL_ENV to access the git command.

Attribute	Type	Description
`*name`	`name`	A unique name for this target.
`git_dir`	`string`	Path to the .git directory Default: `".git"`
`srcs`	`list of labels`	Source files to track (git directory contents) Default: `[]`
`out`	`string`	Output JSON file name Default: `"git-timestamps.json"`
`filter_extensions`	`list of strings`	List of file extensions to filter Default: `["md", "rst", "txt"]`

Providers

DocsProviderInfo

Provider to specify docs information, such as files and navigation title

Fields

`title`	The title of the navigation element
`entrypoint`	The entrypoint file for the documentation
`files`	The files that are part of the documentation
`nav`	The sub navigation elements

DocsLinkInfo

Provider to specify a link to docs (external URL or internal path)

Fields

`title`	The title of the navigation element
`url`	The URL of the navigation element
`entrypoint`	The entrypoint file for the documentation
`files`	The files that are part of the documentation

@rules_docs//docgen:extensions.bzl

Extensions for bzlmod.

Module Extensions

docgen

Tag Classes

mkdocs

Attribute	Type	Description
`name`	`name`	The name of this mkdocs toolchain. Only used in the root module. Default: `"mkdocs"`
`pypi_hub`	`label`	Name of the pip repository hub that contains mkdocs Default: `"@default_pypi"`
`plugins`	`list of strings`	List of mkdocs plugins to install Default: `[]`

@rules_docs//docgen:repositories.bzl

Declare runtime dependencies

Repository Rules

mkdocs_repository

Fetch external tools needed for docgen toolchain

Attribute	Type	Description
`*name`	`name`	A unique name for this repository.
`repo_mapping`	`dictionary: String → String`	In `WORKSPACE` context only: a dictionary from local repository name to global repository name. This allows controls over workspace dependency resolution for dependencies of this repository. For example, an entry `"@foo": "@bar"` declares that, for any time this repository depends on `@foo` (such as a dependency on `@foo//some:target`, it should actually resolve that dependency within globally-declared `@bar` (`@bar//some:target`). This attribute is not supported in `MODULE.bazel` context (when invoking a repository rule inside a module extension's implementation function).
`*pypi_hub`	`label`	Name of the pip repository hub that contains mkdocs
`plugins`	`list of strings`	List of mkdocs plugins to install Default: `[]`