Documents and sections
Document
A document is the top-level container for Markdown output. When coerced to a string via String(), it auto-collects footnotes, assigns identifiers, and appends definitions at the end.
| Factory | Aliases |
|---|---|
b.document() | b.doc(), b.d() |
const note = b.footnote("A citation.")
b.document(
b.heading("Introduction"),
b.paragraph("Some text", note, " here."),
)# Introduction
Some text[^1] here.
[^1]: A citation.MarkdownDocument
├── MarkdownHeadingBlock [level=1]
│ └── "Introduction"
└── MarkdownParagraphBlock
├── "Some text"
├── MarkdownFootnoteBlock [identifier=1]
│ └── footer
│ └── "A citation."
└── " here."Section
Sections are an alias of documents — they collect footnotes and propagate heading depth — but represent a logical subsection. They exist purely for semantic purposes and don't affect rendering.
| Factory | Aliases |
|---|---|
b.section() | b.sec(), b.s() |
b.section(
b.heading("Part One"),
b.paragraph("Content for part one."),
)# Part One
Content for part one.MarkdownSectionBlock
├── MarkdownHeadingBlock [level=1]
│ └── "Part One"
└── MarkdownParagraphBlock
└── "Content for part one."Heading Depth
When a document or section contains headings, their levels are derived from the nesting depth. You write headings without worrying about absolute levels — the structure determines them.
b.document(
b.heading("Top Level"),
b.section(
b.heading("Nested"),
b.paragraph("Inside a section."),
),
)# Top Level
## Nested
Inside a section.MarkdownDocument
├── MarkdownHeadingBlock [level=1]
│ └── "Top Level"
└── MarkdownSectionBlock
├── MarkdownHeadingBlock [level=2]
│ └── "Nested"
└── MarkdownParagraphBlock
└── "Inside a section."Sections nest arbitrarily deep, up to heading level 6:
b.document(
b.heading("H1"),
b.section(
b.heading("H2"),
b.section(
b.heading("H3"),
b.paragraph("Deep content."),
),
),
)# H1
## H2
### H3
Deep content.MarkdownDocument
├── MarkdownHeadingBlock [level=1]
│ └── "H1"
└── MarkdownSectionBlock
├── MarkdownHeadingBlock [level=2]
│ └── "H2"
└── MarkdownSectionBlock
├── MarkdownHeadingBlock [level=3]
│ └── "H3"
└── MarkdownParagraphBlock
└── "Deep content."Auto-Nesting
When multiple headings at different levels are passed directly to a document, bbmd automatically groups deeper headings into sections. The shallowest heading level becomes the root.
b.document(
b.heading("Chapter").level(1),
b.paragraph("Intro."),
b.heading("Section").level(2),
b.paragraph("Details."),
)# Chapter
Intro.
## Section
Details.MarkdownDocument
├── MarkdownHeadingBlock [level=1]
│ └── "Chapter"
├── MarkdownParagraphBlock
│ └── "Intro."
└── MarkdownSectionBlock
├── MarkdownHeadingBlock [level=2]
│ └── "Section"
└── MarkdownParagraphBlock
└── "Details."Auto-nesting preserves the relative structure of heading levels. Level-1 headings become root entries, and all deeper headings are wrapped in sections at the appropriate depth.