rules_markdown

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

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

load("@rules_markdown//markdown:defs.bzl", "markdown_fragment", "markdown_document")

markdown_fragment(name = "intro", src = "intro.md", title = "Introduction", weight = 0)
markdown_fragment(name = "usage", src = "usage.md", title = "Usage", weight = 10)

markdown_document(
    name = "guide",
    out = "GUIDE.md",
    template = "GUIDE.md.tmpl",   # has <!-- TOC --> and <!-- FRAGMENTS -->
    fragments = [":intro", ":usage"],
    write_to = "GUIDE.md",        # bazel run //:guide.write ; bazel test //:guide.write_test
)

See [the introduction](https://github.com/tomato-bazel/rules_markdown/blob/main/mdref:intro) for the idea.

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

examples/basic/BUILD.bazel

load("//markdown:defs.bzl", "markdown_document", "markdown_fragment")

# Two composable sections. `usage` deep-links into `intro` via mdref:intro.
markdown_fragment(
    name = "intro",
    src = "intro.md",
    title = "Introduction",
    weight = 0,
)

markdown_fragment(
    name = "usage",
    src = "usage.md",
    title = "Usage",
    weight = 10,
)

# Aggregate into GUIDE.md with a TOC + a prose template; resolve + check the
# deep link; materialize into the tree (GUIDE.md) with a drift gate.
markdown_document(
    name = "guide",
    out = "GUIDE.md",
    template = "README.md.tmpl",
    fragments = [
        ":intro",
        ":usage",
    ],
    link_check = True,
    toc = True,
    write_to = "GUIDE.md",
)

examples/slots/BUILD.bazel

load("//markdown:defs.bzl", "markdown_document", "markdown_fragment")

# Two fragments targeting two named template slots — generated content placed at
# specific spots (the gitlab-profile two-tables-at-two-locations pattern).
markdown_fragment(
    name = "a",
    content = "Content routed to the **alpha** slot.",
    slot = "alpha",
)

markdown_fragment(
    name = "b",
    content = "Content routed to the **beta** slot.",
    slot = "beta",
)

markdown_document(
    name = "doc",
    out = "SLOTS.md",
    template = "tmpl.md",
    fragments = [
        ":a",
        ":b",
    ],
    link_check = False,
    toc = False,
    write_to = "SLOTS.md",
)

from docs/defs.md

Public API for rules_markdown.

load("@rules_markdown//markdown:defs.bzl", "markdown_fragment", "markdown_document")

markdown_fragment

load("@rules_markdown//markdown: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

MarkdownDocInfo

load("@rules_markdown//markdown:defs.bzl", "MarkdownDocInfo")

MarkdownDocInfo(md, anchor_index, fragments)

A rendered markdown document — exposed so a doc can be embedded, link-checked, or published without re-rendering.

FIELDS

Name	Description
md	File: the rendered document.
anchor_index	File: JSON map of deep-link handle -> final in-doc anchor slug.
fragments	depset of the fragment structs that composed it.

MarkdownFragmentInfo

load("@rules_markdown//markdown:defs.bzl", "MarkdownFragmentInfo")

MarkdownFragmentInfo(fragments)

A markdown fragment + its metadata, gathered transitively by markdown_link_aspect. Each contribution is a hashable struct so it can ride a depset.

FIELDS

Name	Description
fragments	depset of struct(frag_id, md_file, title, level, weight, handle, tags).

markdown_document

load("@rules_markdown//markdown: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

markdown_link_aspect

load("@rules_markdown//markdown:defs.bzl", "markdown_link_aspect")

markdown_link_aspect()

Walk deps/fragments/roots edges collecting markdown fragment contributions.

ASPECT ATTRIBUTES

Name	Type
deps	String
fragments	String
roots	String

ATTRIBUTES