rules_mdbook

bazel_dep(name = "rules_mdbook", version = "0.3.1")

common --registry=https://registry.fastverk.com/
common --registry=https://bcr.bazel.build/

bazel_dep(name = "rules_mdbook", version = "0.2.0")

mdbook = use_extension("@rules_mdbook//mdbook:extensions.bzl", "mdbook")
use_repo(mdbook, "mdbook", "mdbook_mermaid")
register_toolchains("@mdbook//:mdbook_toolchain_def")

mdbook.toolchain(
    mdbook_version  = "0.5.2",
    mermaid_version = "0.17.0",
)

docs/
├── BUILD.bazel
├── book.toml
└── src/
    ├── SUMMARY.md
    ├── intro.md
    └── ...

load("@rules_mdbook//mdbook:defs.bzl", "mdbook_book")

mdbook_book(
    name      = "site",
    book_toml = "book.toml",
    srcs      = glob(["src/**/*.md"]),
    plugins   = ["@mdbook_mermaid//:mdbook-mermaid"],
    out       = "site.tar.gz",
)

bazel run //docs:update

Real usage, taken from the module’s examples/.

examples/smoke/BUILD.bazel

load("@rules_mdbook//mdbook:defs.bzl", "mdbook_book", "mdbook_serve")

mdbook_book(
    name = "site",
    srcs = glob(["src/**/*.md"]),
    out = "site.tar.gz",
    book_toml = "book.toml",
    plugins = ["@mdbook_mermaid//:mdbook-mermaid"],
)

# `bazel run //examples/smoke:serve` -> mdbook serve at localhost:3000
# with watch + live reload over the live source tree.
mdbook_serve(
    name = "serve",
    plugins = ["@mdbook_mermaid//:mdbook-mermaid"],
)

examples/treesrc/BUILD.bazel

load("@rules_mdbook//mdbook:defs.bzl", "mdbook_book")
load(":gen_tree.bzl", "gen_tree")

# Upstream generator: emits a directory of chapters whose filenames aren't
# known statically. The dir is named "chapters" so it stages at $STAGE/chapters,
# matching book.toml's `src = "chapters"`.
gen_tree(
    name = "chapters",
)

# mdbook_book consumes the directory directly (recursive copy) alongside the
# committed book.toml.
mdbook_book(
    name = "site",
    srcs = [":chapters"],
    out = "site.tar.gz",
    book_toml = "book.toml",
)

from docs/defs.md

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

Name	Description
tarball	File: the gzipped tar of the rendered HTML tree.

from docs/extensions.md

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

Name	Description	Type	Mandatory	Default
mdbook_version	Override mdbook version. Defaults to the value in known_versions.bzl.	String	optional	""
mermaid_version	Override mdbook-mermaid version. Defaults to the value in known_versions.bzl.	String	optional	""

from docs/toolchains.md

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

Name	Description
mdbook	File: the mdbook executable.