rules_mdbook
API reference, generated from the module’s .bzl docstrings (stardoc).
User-facing Bazel rules for rules_mdbook.
Exports mdbook_book, which runs mdbook build over a staged source
tree and packages the rendered HTML into a tarball. Optional plugin
executables (e.g. mdbook-mermaid) are staged onto PATH so mdbook can
resolve them by their bare names.
Targets returning MdbookSiteInfo expose the site tarball
programmatically so future rules (a deploy step, a link checker, a
mdbook serve wrapper) can consume the output without re-running
mdbook.
mdbook_book
load("@rules_mdbook//mdbook:defs.bzl", "mdbook_book")
mdbook_book(name, srcs, out, book_toml, plugins, src_strip_prefix)
Run mdbook build over a staged source tree and produce an HTML tarball.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| srcs | All source files (Markdown, SUMMARY.md, theme assets, etc.). Each file is staged at its package-relative path minus src_strip_prefix. A directory (tree artifact produced by an upstream rule) is copied recursively into its computed relative path, so a rule that stages a generated chapter tree can feed it here directly. | List of labels | required | |
| out | The rendered site, packaged as a .tar.gz. | Label | required | |
| book_toml | The mdbook configuration file. Staged at the root of the build sandbox. | Label | required | |
| plugins | mdbook plugin executables (e.g. @mdbook_mermaid//:mdbook-mermaid). Staged onto PATH so mdbook can resolve them by bare name. | List of labels | optional | [] |
| src_strip_prefix | Prefix to strip from each src’s package-relative path before staging. Empty means files land at their package-relative paths. | String | optional | "" |
mdbook_serve
load("@rules_mdbook//mdbook:defs.bzl", "mdbook_serve")
mdbook_serve(name, plugins)
Run mdbook serve (with watch + live reload) against the live user source tree under $BUILD_WORKSPACE_DIRECTORY/<package>. Invoke via bazel run //path/to:target. The target’s package directory must contain the book.toml; mdbook’s own watch picks up edits without Bazel re-running.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| plugins | mdbook plugin executables, staged onto PATH so mdbook resolves them by bare name. Match the plugins listed in your book.toml. | List of labels | optional | [] |
MdbookSiteInfo
load("@rules_mdbook//mdbook:defs.bzl", "MdbookSiteInfo")
MdbookSiteInfo(tarball)
A rendered mdbook site.
FIELDS
Module extension for rules_mdbook.
Auto-fetches prebuilt mdbook + mdbook-mermaid binaries for the host
platform. Versions are pinned by sha256 in
private/known_versions.bzl. Consumers can override the version per
tool via the toolchain tag class.
Default usage (pulls the default-pinned mdbook + mdbook-mermaid):
mdbook = use_extension("@rules_mdbook//mdbook:extensions.bzl", "mdbook")
use_repo(mdbook, "mdbook", "mdbook_mermaid")
Pin a specific version:
mdbook = use_extension("@rules_mdbook//mdbook:extensions.bzl", "mdbook")
mdbook.toolchain(mdbook_version = "0.5.2", mermaid_version = "0.17.0")
use_repo(mdbook, "mdbook", "mdbook_mermaid")
Release fetching is delegated to
@rules_github//github:repositories.bzl%github_binary_repository
so all our rules_* repos share one URL-shape + sha-pinning impl.
mdbook
mdbook = use_extension("@rules_mdbook//mdbook:extensions.bzl", "mdbook")
mdbook.toolchain(mdbook_version, mermaid_version)
Sets up @mdbook and @mdbook_mermaid as Bazel-fetched prebuilt binaries.
TAG CLASSES
toolchain
Attributes
Toolchain rule for rules_mdbook.
mdbook_toolchain wraps a single mdbook binary as a Bazel toolchain.
Consumers (the mdbook_book and mdbook_serve rules) resolve mdbook
through @rules_mdbook//mdbook:toolchain_type, so users can register
custom mdbook binaries (locally-built fork, alternate version, …) via
register_toolchains(...) without modifying rule attributes.
The module extension at @rules_mdbook//mdbook:extensions.bzl generates
a default toolchain (@mdbook//:mdbook_toolchain_def) wrapping the
prebuilt binary. Users register it from their MODULE.bazel:
register_toolchains("@mdbook//:mdbook_toolchain_def")
mdbook_toolchain
load("@rules_mdbook//mdbook:toolchains.bzl", "mdbook_toolchain")
mdbook_toolchain(name, mdbook)
Declare an mdbook binary as a Bazel toolchain.
ATTRIBUTES
| Name | Description | Type | Mandatory | Default |
|---|---|---|---|---|
| name | A unique name for this target. | Name | required | |
| mdbook | Path to the mdbook executable. | Label | required |
MdbookToolchainInfo
load("@rules_mdbook//mdbook:toolchains.bzl", "MdbookToolchainInfo")
MdbookToolchainInfo(mdbook)
The mdbook binary, resolved via a toolchain.
FIELDS