rules_docs¶

Public API for docgen rules.

docs_action¶

load("@rules_docs//docgen:defs.bzl", "docs_action")

docs_action(name, deps, srcs, data, out, entrypoint, nav, readme_content, readme_filename,
            readme_header_links, rewrite_path, title)

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

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	The dependencies of the documentation	List of labels	optional	`[]`
srcs	The files that are part of the documentation	List of labels	optional	`[]`
data	The data files that are part of the documentation	List of labels	optional	`[]`
out	The output directory for the documentation	String	optional	`""`
entrypoint	The entrypoint file for the documentation	Label	optional	`None`
nav	Sub navigation elements	Dictionary: Label -> String	optional	`{}`
readme_content	The content of the README.md file	String	optional	`""`
readme_filename	The filename of the README.md file	String	optional	`"README.md"`
readme_header_links	The links to add to the README.md file	Dictionary: Label -> String	optional	`{}`
rewrite_path	The path prefix to rewrite documentation files to	String	optional	`""`
title	The title of the navigation element	String	optional	`""`

docs_add_last_updated¶

load("@rules_docs//docgen:defs.bzl", "docs_add_last_updated")

docs_add_last_updated(name, docs, last_updated_date_format, last_updated_json, out_dir,
                      update_history_url)

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.

ATTRIBUTES

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

docs_link¶

load("@rules_docs//docgen:defs.bzl", "docs_link")

docs_link(name, data, entrypoint, title, url)

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
    },
)

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	The data files that are part of the documentation	List of labels	optional	`[]`
entrypoint	The entrypoint file for the documentation	String	optional	`""`
title	The title of the navigation element	String	optional	`""`
url	The URL of the navigation element	String	optional	`""`

git_last_updated_timestamps¶

load("@rules_docs//docgen:defs.bzl", "git_last_updated_timestamps")

git_last_updated_timestamps(name, srcs, out, filter_extensions, git_dir)

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.

ATTRIBUTES

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

mkdocs_build¶

load("@rules_docs//docgen:defs.bzl", "mkdocs_build")

mkdocs_build(name, data, config, docs, docs_dir, mkdocs_executable, root_nav_folder, site_dir,
             use_default_shell_env)

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///.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
data	The data files to include in the site	List of labels	optional	`[]`
config	The mkdocs.yml file	Label	required
docs	The docs to include in the site	List of labels	optional	`[]`
docs_dir	The directory containing the docs	String	optional	`"docs"`
mkdocs_executable	The mkdocs executable. Defaults to @mkdocs//:mkdocs from the docgen extension.	Label	required
root_nav_folder	The root nav folder	String	optional	`""`
site_dir	The output directory for the site	String	optional	`"site"`
use_default_shell_env	Use the default shell environment	Boolean	optional	`False`

mkdocs_config¶

load("@rules_docs//docgen:defs.bzl", "mkdocs_config")

mkdocs_config(name, docs, mkdocs_base, root_nav_folder, title)

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.

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
docs	The docs to include in the site	Label	optional	`None`
mkdocs_base	The base mkdocs.yml file	Label	required
root_nav_folder	The root nav folder	String	optional	`""`
title	The title of the site	String	optional	`""`

mkdocs_serve¶

load("@rules_docs//docgen:defs.bzl", "mkdocs_serve")

mkdocs_serve(name, data, config, docs, docs_dir, git_folder, mkdocs_executable, root_nav_folder)

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.

ATTRIBUTES

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

DocsLinkInfo¶

load("@rules_docs//docgen:defs.bzl", "DocsLinkInfo")

DocsLinkInfo(title, url, entrypoint, files)

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

FIELDS

Name	Description
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

DocsProviderInfo¶

load("@rules_docs//docgen:defs.bzl", "DocsProviderInfo")

DocsProviderInfo(title, entrypoint, files, nav)

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

FIELDS

Name	Description
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

docs¶

load("@rules_docs//docgen:defs.bzl", "docs")

docs(name, entry, srcs, data, deps, title, nav, out, readme_content, readme_header_links, **kwargs)

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	Description	Default Value
name	Name of the documentation target. Defaults to "docs".	`"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".	`"README.md"`
srcs	List of source markdown files to include in the documentation. Defaults to ["README.md"].	`["README.md"]`
data	Additional data files to include (images, assets, etc.).	`[]`
deps	Documentation dependencies - other docs/docs_index/docs_link targets.	`[]`
title	Title of the documentation section. If not provided, defaults to the package name.	`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)	`{}`
out	Output directory for generated documentation. If not specified, uses the target name.	`None`
readme_content	Content for the generated entry file if it doesn't exist as a file.	`""`
readme_header_links	Dictionary of links to add to the README header. Format same as nav.	`{}`
kwargs	Additional arguments passed to the underlying docs_action rule.	none

docs_action_impl¶

load("@rules_docs//docgen:defs.bzl", "docs_action_impl")

docs_action_impl(ctx)

Implementation function for docs_action rule.

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

PARAMETERS

Name	Description	Default Value
ctx	The rule context.	none

RETURNS

A list of providers including DefaultInfo and DocsProviderInfo.

docs_index¶

load("@rules_docs//docgen:defs.bzl", "docs_index")

docs_index(name, title, entry, nav, **kwargs)

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	Description	Default Value
name	Name of the index target. Defaults to "docs".	`"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.	`None`
entry	Optional entry point file for the index. If provided, clicking the index will navigate to this file.	`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	`{}`
kwargs	Additional arguments passed to the underlying docs_action rule.	none

Last updated: January 01, 2026 at 08:16 PM