rules_readme

bazel_dep(name = "rules_readme", version = "0.0.3")

bazel_dep(name = "rules_readme", version = "0.0.1")

load("@rules_readme//readme:defs.bzl", "readme", "markdown_fragment")

markdown_fragment(name = "overview", src = "overview.md", title = "Overview", weight = 0)
markdown_fragment(name = "repos",    src = "repos.md",    title = "Repositories", weight = 10)

readme(
    name = "readme",
    template = "README.md.tmpl",        # has <!-- TOC --> and <!-- FRAGMENTS -->
    fragments = [":overview", ":repos"],
    # write_to defaults to "README.md" -> creates readme.write + readme.write_test
)

bazel run  //:readme.write        # regenerate README.md in the tree
bazel test //:readme.write_test   # CI drift gate

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

examples/profile/BUILD.bazel

load("//readme:defs.bzl", "markdown_fragment", "readme")

markdown_fragment(
    name = "overview",
    src = "overview.md",
    title = "Overview",
    weight = 0,
)

markdown_fragment(
    name = "repos",
    src = "repos.md",
    title = "Repositories",
    weight = 10,
)

# readme() defaults write_to = "README.md", so this auto-creates:
#   bazel run  //examples/profile:readme_doc.write        (materialize README.md)
#   bazel test //examples/profile:readme_doc.write_test   (drift gate)
#
# Named readme_doc, NOT readme: markdown_document renders to `<name>.md`, so a
# target named `readme` produces `readme.md` alongside the materialized
# `README.md`. Those are two files on Linux and one on macOS, where the build
# then fails with an opaque "Could not copy inputs into sandbox ... (File
# exists)". readme() now rejects that collision at load time.
readme(
    name = "readme_doc",
    fragments = [
        ":overview",
        ":repos",
    ],
    template = "README.md.tmpl",
)

from docs/defs.md

Public API for rules_readme — README-shaped sugar over rules_markdown.

load("@rules_readme//readme:defs.bzl", "readme", "markdown_fragment")

markdown_fragment

load("@rules_readme//readme:defs.bzl", "markdown_fragment")

markdown_fragment(name, deps, src, anchor, classifiers, content, level, slot, title, weight)

Declare one composable markdown fragment (a section of a document).

ATTRIBUTES

Name	Description	Type	Mandatory	Default
name	A unique name for this target.	Name	required
deps	Child fragments folded in transitively.	List of labels	optional	[]
src	The fragment body (.md). Mutually exclusive with content.	Label	optional	None
anchor	Explicit deep-link handle (defaults to the target name). Reference it elsewhere as mdref:<handle>.	String	optional	""
classifiers	Free-form classifiers (e.g. category/section); exposed in fragment metadata.	List of strings	optional	[]
content	Inline fragment body. Mutually exclusive with src.	String	optional	""
level	Heading level for title (default 2 -> ##).	Integer	optional	2
slot	Target a named template placeholder <!-- FRAGMENTS:<slot> --> (for generated content placed at a specific spot). Default: the unnamed <!-- FRAGMENTS -->.	String	optional	""
title	Section heading text. If set, md_gen injects a level heading; it’s also the deep-link target.	String	optional	""
weight	Sort key within the document (ascending).	Integer	optional	0

markdown_document

load("@rules_readme//readme:defs.bzl", "markdown_document")

markdown_document(name, out, template, fragments, roots, toc, link_check, write_to, **kwargs)

Aggregate fragments into one rendered markdown document.

PARAMETERS

Name	Description	Default Value
name	target name.	none
out	output filename (defaults to <name>.md).	None
template	optional prose template with <!-- FRAGMENTS --> + <!-- TOC -->.	None
fragments	fragment targets to compose.	[]
roots	arbitrary targets whose graph contributes fragments (via the aspect).	[]
toc	emit a table of contents.	True
link_check	fail on a dangling mdref: deep link.	True
write_to	if set (a source-relative path), also create <name>.write (bazel run materializes the doc into the tree) + <name>.write_test (drift gate), via write_source_files.	None
kwargs	forwarded (visibility, tags, …).	none

readme

load("@rules_readme//readme:defs.bzl", "readme")

readme(name, template, fragments, roots, toc, link_check, write_to, **kwargs)

Render a templated README from fragments and materialize it into the tree.

A thin façade over markdown_document with README defaults. Because materialize-to-source is the dominant case, write_to defaults to "README.md" — so readme(...) creates <name>.write (bazel run materializes the README) + <name>.write_test (the drift gate) out of the box, via write_source_files. Pass write_to = None to opt out (you then just get the rendered file in bazel-bin + MarkdownDocInfo).

PARAMETERS

Name	Description	Default Value
name	target name.	none
template	prose template with <!-- FRAGMENTS --> (required) and an optional <!-- TOC --> marker.	none
fragments	fragment targets to compose (ordered by their weight).	[]
roots	arbitrary targets whose graph contributes fragments.	[]
toc	emit a table of contents.	True
link_check	fail the build on a dangling mdref: deep link.	True
write_to	source-relative path to materialize into (default "README.md"); None to skip materialization.	"README.md"
kwargs	forwarded (visibility, tags, …).	none