Standard Syntax

Heading

Create headings from level 1 (#) through level 6 (######).

Factory	Aliases
`b.heading()`	`b.head()`, `b.h()`

b.heading("Introduction")

# Introduction

MarkdownHeadingBlock
└── "Introduction"

Methods

Method	Description	Aliases
`.level(1–6)`	Set the heading level	`.l()`
`.identifier(value)`	Set a custom anchor identifier	`.id()`

b.heading("Introduction").level(3)

### Introduction

MarkdownHeadingBlock [level=3]
└── "Introduction"

b.heading("API Reference").level(2).id("api-ref")

## API Reference {#api-ref}

MarkdownHeadingBlock [identifier=api-ref, level=2]
└── "API Reference"

Level Locking

Calling .level() locks the heading level — subsequent .level() calls are ignored. This prevents accidental overwrites.

When headings are placed inside a b.document() or b.section(), their levels are derived from the nesting depth instead. Auto-nesting unlocks heading levels so depth propagation can adjust them. See Heading Depth for details.

Paragraph

A plain paragraph block. Content is rendered as-is without any wrapping markers.

Factory	Aliases
`b.paragraph()`	`b.para()`, `b.p()`

b.paragraph("Hello, world!")

Hello, world!

MarkdownParagraphBlock
└── "Hello, world!"

b.paragraph("Mix ", b.bold("bold"), " and ", b.italic("italic"), " freely.")

Mix **bold** and *italic* freely.

MarkdownParagraphBlock
├── "Mix "
├── MarkdownBoldBlock
│   └── "bold"
├── " and "
├── MarkdownItalicBlock
│   └── "italic"
└── " freely."

Bold

Wrap content in bold markers.

Factory	Aliases
`b.bold()`	`b.b()`

b.bold("important")

**important**

MarkdownBoldBlock
└── "important"

Methods

Method	Description	Aliases
`.style("**" \| "__")`	Choose asterisk or underscore style. Default: `**`	—

b.bold("important").style("__")

__important__

MarkdownBoldBlock [style=__]
└── "important"

Italic

Wrap content in italic markers.

Factory	Aliases
`b.italic()`	`b.i()`

b.italic("emphasis")

*emphasis*

MarkdownItalicBlock
└── "emphasis"

Methods

Method	Description	Aliases
`.style("*" \| "_")`	Choose asterisk or underscore style. Default: `*`	—

b.italic("emphasis").style("_")

_emphasis_

MarkdownItalicBlock [style=_]
└── "emphasis"

Link

Create an inline link. If no label is provided, the URL is rendered as an autolink.

Factory	Aliases
`b.link(url, ...label)`	`b.url()`

b.link("https://example.com", "Example")

[Example](https://example.com)

MarkdownLinkBlock [url=https://example.com]
└── "Example"

b.link("https://example.com")

<https://example.com>

MarkdownLinkBlock [url=https://example.com]

Methods

Method	Description	Aliases
`.target(value)`	Set the link target. Renders as an `<a>` tag when used	—

Target Types

Type	Description
`_blank`	Open in a new tab or window
`_self`	Open in the current frame (default)
`_parent`	Open in the parent frame
`_top`	Open in the full body of the window

b.link("https://example.com", "Example").target("_blank")

<a href="https://example.com" target="_blank">Example</a>

MarkdownLinkBlock [url=https://example.com, target=_blank]
└── "Example"

Image

Embed an image with alt text.

Factory	Aliases
`b.image(src, ...alt)`	`b.img()`

b.image("photo.png", "A sunset")

![A sunset](photo.png)

MarkdownImageBlock [src=photo.png]
└── "A sunset"

Methods

Method	Description	Aliases
`.caption(...content)`	Add a figure caption (renders as `<figure>` HTML)	—

b.image("photo.png", "A sunset").caption("Fig 1. Sunset")

<figure>
  <img src="photo.png" alt="A sunset">
  <figcaption>Fig 1. Sunset</figcaption>
</figure>

MarkdownImageBlock [src=photo.png]
├── alt
│   └── "A sunset"
└── caption
    └── "Fig 1. Sunset"

Code

Create inline code or fenced code blocks. Multiline content automatically renders as a fenced block.

Factory	Aliases
`b.code()`	`b.codeblock()`

b.code("hello")

`hello`

MarkdownCodeBlock
└── "hello"

b.code("const x = 1", "const y = 2")

```
const x = 1
const y = 2
```

MarkdownCodeBlock
├── "const x = 1"
└── "const y = 2"

Methods

Method	Description	Aliases
`.language(lang)`	Set the language for syntax highlighting	`.lang()`

b.code("const x = 1", "const y = 2").language("ts")

```ts
const x = 1
const y = 2
```

MarkdownCodeBlock [language=ts]
├── "const x = 1"
└── "const y = 2"

The codeblock() alias auto-detects the language from the last argument if it is a common language identifier:

b.codeblock("const x = 1", "ts")

```ts
const x = 1
```

MarkdownCodeBlock [language=ts]
└── "const x = 1"

Inline vs. Fenced

Code renders as inline or fenced depending on the content:

Inline: Single content argument with no .language() set renders as backtick-wrapped inline code.
Fenced: Multiple content arguments or a .language() call renders as a triple-backtick fenced block.

Blockquote

Create a blockquote. Lines are prefixed with > .

Factory	Aliases
`b.blockquote()`	`b.block()`, `b.bq()`

b.blockquote("To be or not to be.")

> To be or not to be.

_MarkdownBlockquoteBlock
└── "To be or not to be."

b.blockquote(
  "First paragraph.",
  "Second paragraph."
)

> First paragraph.
> Second paragraph.

_MarkdownBlockquoteBlock
├── "First paragraph."
└── "Second paragraph."

Nesting

Blockquotes can be nested. Inner blockquotes use >> (without a space between > markers):

b.blockquote(
  "Outer quote.",
  b.blockquote("Inner quote."),
)

> Outer quote.
>> Inner quote.

_MarkdownBlockquoteBlock
├── "Outer quote."
└── _MarkdownBlockquoteBlock
    └── "Inner quote."

See also: Blockquote Alerts for GitHub-flavored alert syntax.

Horizontal Rule

Insert a horizontal rule (thematic break).

Factory	Aliases
`b.horizontalRule()`	`b.hr()`

b.hr()

---

MarkdownHorizontalRuleBlock

Methods

Method	Description	Aliases
`.style("-" \| "*" \| "_")`	Choose the rule character. Default: `-`	—
`.count(n)`	Set the number of characters (minimum 3)	—

b.hr().style("*").count(5)


*****

MarkdownHorizontalRuleBlock [style=*, count=5]

Ordered List

Create a numbered list. Items are automatically wrapped.

Factory	Aliases
`b.list.ordered()`	`b.list.ol()`

b.list.ordered("First", "Second", "Third")

1. First
2. Second
3. Third

MarkdownOrderedListBlock
├── MarkdownOrderedListItemBlock [index=1]
│   └── "First"
├── MarkdownOrderedListItemBlock [index=2]
│   └── "Second"
└── MarkdownOrderedListItemBlock [index=3]
    └── "Third"

Methods

Method	Description	Aliases
`.startingIndex(n)`	Set the starting number	—

b.list.ordered("First", "Second").startingIndex(5)

5. First
6. Second

MarkdownOrderedListBlock
├── MarkdownOrderedListItemBlock [index=5]
│   └── "First"
└── MarkdownOrderedListItemBlock [index=6]
    └── "Second"

Lists can be nested by passing a list block as an item:

b.list.ordered(
  "Item one",
  b.list.ordered("Nested A", "Nested B"),
  "Item two",
)

1. Item one
  1. Nested A
  2. Nested B
2. Item two

MarkdownOrderedListBlock
├── MarkdownOrderedListItemBlock [index=1]
│   └── "Item one"
├── MarkdownOrderedListBlock [indent=2]
│   ├── MarkdownOrderedListItemBlock [index=1]
│   │   └── "Nested A"
│   └── MarkdownOrderedListItemBlock [index=2]
│       └── "Nested B"
└── MarkdownOrderedListItemBlock [index=2]
    └── "Item two"

Nested lists are indented by 2 spaces by default. Override this globally with enforce.list.indent in Rendering Options.

Unordered List

Create a bulleted list.

Factory	Aliases
`b.list.unordered()`	`b.list.ul()`

b.list.unordered("Apples", "Bananas", "Cherries")

- Apples
- Bananas
- Cherries

MarkdownUnorderedListBlock
├── MarkdownUnorderedListItemBlock
│   └── "Apples"
├── MarkdownUnorderedListItemBlock
│   └── "Bananas"
└── MarkdownUnorderedListItemBlock
    └── "Cherries"

Methods

Method	Description	Aliases
`.style("-" \| "*" \| "+")`	Set the bullet character for all items	—

b.list.unordered("Apples", "Bananas").style("*")

* Apples
* Bananas

MarkdownUnorderedListBlock
├── MarkdownUnorderedListItemBlock [style=*]
│   └── "Apples"
└── MarkdownUnorderedListItemBlock [style=*]
    └── "Bananas"

Line Break

Insert a line break (\n).

Factory	Aliases
`b.lineBreak()`	`b.br()`

b.paragraph("Line one", b.br(), "Line two")

Line one
Line two

MarkdownParagraphBlock
├── "Line one"
├── MarkdownLineBreakBlock
└── "Line two"

Standard Syntax

On this page