Use the Markdown builder when JavaScript has structured data and needs to emit a clean Markdown document. The builder avoids brittle string concatenation by giving scripts typed operations for headings, paragraphs, lists, checklists, callouts, code blocks, raw blocks, tables, and inline formatting.

The builder is Go-backed. JavaScript calls exported Go methods such as Title, Paragraph, Table, RenderString, and RenderHTML. Rendered results expose exported Go fields such as Text, Bytes, and Blocks.

Loading the API

Load the existing markdown module and create a builder. The builder is part of require("markdown"); there is no separate module name.

const markdown = require("markdown");

const text = markdown.builder()
  .Title("Status report")
  .Paragraph("Generated from structured data.")
  .RenderString();

Use this API when the document shape is assembled programmatically. Use the template module when the document shape is fixed and mostly described by a template file.

Builder lifecycle

A MarkdownBuilder starts empty. Each block method appends one Markdown block and returns the same builder so calls can be chained.

const doc = markdown.builder()
  .Title("Release notes")
  .Paragraph("This release contains generated sections.")
  .Heading(2, "Changes")
  .BulletList(["Added builder API", "Added table rendering"]);

const result = doc.Render();
console.log(result.Text);
console.log(result.Bytes);
console.log(result.Blocks);

Call Validate() when a script wants to inspect errors without rendering. Call Render() for a structured result, RenderString() for only Markdown text, and RenderHTML() to pass the generated Markdown through goldmark.

MarkdownBuilder methods

Title(text)

Adds a level-one heading. This is equivalent to Heading(1, text).

markdown.builder().Title("Project report");

Heading(level, text)

Adds a heading from level 1 through 6. Invalid levels are recorded as validation errors and fail rendering.

markdown.builder()
  .Heading(2, "Implementation")
  .Heading(3, "Tests");

Paragraph(...parts) and Text(text)

Adds a paragraph. Ordinary strings are escaped as Markdown text. Multiple parts are concatenated, so inline helper values can be mixed with strings.

const i = markdown.inline();

markdown.builder()
  .Paragraph("Run ", i.Code("go test ./..."), " before committing.");

Text(text) is convenience sugar for a one-part paragraph.

Raw(markdown)

Adds trusted raw Markdown as a block. Use this for advanced Markdown that the builder does not model yet. Do not use it for untrusted user input.

markdown.builder()
  .Raw("<details>\n<summary>More</summary>\n\nRaw Markdown here.\n</details>");

ThematicBreak()

Adds a thematic break rendered as ---.

markdown.builder()
  .Paragraph("Before")
  .ThematicBreak()
  .Paragraph("After");

Blockquote(body)

Adds a blockquote. String bodies are split on newlines and every line receives the > prefix.

markdown.builder()
  .Blockquote("This text is quoted.\nSo is this line.");

Callout(kind, title, body)

Adds an Obsidian-style callout block. The kind is uppercased in the marker.

markdown.builder()
  .Callout("warning", "Review needed", "Check table escaping before release.");

Output:

> [!WARNING] Review needed
> Check table escaping before release.

BulletList(items)

Adds a bullet list from a JavaScript array.

markdown.builder()
  .BulletList(["Parse data", "Build report", "Upload PDF"]);

OrderedList(items, start?)

Adds an ordered list. The optional start value defaults to 1 and must be positive.

markdown.builder()
  .OrderedList(["Design", "Implement", "Review"], 1);

Checklist(items)

Adds a GitHub-style task list. Items may be strings or objects with text and checked fields.

markdown.builder()
  .Checklist([
    { text: "Service layer", checked: true },
    { text: "CLI docs", checked: false },
  ]);

CodeBlock(language, code)

Adds a fenced code block. The renderer chooses a fence long enough to contain code that itself includes backticks.

markdown.builder()
  .CodeBlock("js", "console.log('hello');");

The language name must not contain whitespace.

Table()

Starts a TableBuilder. A table is appended only when End() is called.

markdown.builder()
  .Table()
    .Columns("Name", "Status")
    .Row("Parser", "done")
    .Row("Builder", "planned")
    .End()
  .RenderString();

TableBuilder methods

Tables are first-class because they are easy to get wrong by hand. The renderer escapes pipes in cells, turns cell newlines into <br>, pads columns for readable source output, and validates that every row has the same number of cells as the header.

Columns(...columns)

Sets the table columns. Each column can be a string or an object with label and optional align.

.Table()
  .Columns(
    { label: "Name", align: "left" },
    { label: "Score", align: "right" },
    "Notes"
  )

Supported alignments are default, left, center, and right.

Align(...alignments)

Updates alignments after columns are set.

.Table()
  .Columns("Name", "Score")
  .Align("left", "right")

Row(...cells)

Adds one row. Cells can be strings, numbers, booleans, inline helper values, or arrays of inline parts.

const i = markdown.inline();

.Table()
  .Columns("Function", "Description")
  .Row(i.Code("builder()"), "Create a document builder")

Rows(rows)

Adds multiple rows from an array of arrays.

.Table()
  .Columns("Name", "Status")
  .Rows([
    ["Parser", "done"],
    ["Builder", "planned"],
  ])

End()

Appends the table to the parent document and returns the MarkdownBuilder. Call End() once before continuing with more document blocks.

markdown.builder()
  .Table()
    .Columns("Name", "Status")
    .Row("Parser", "done")
    .End()
  .Heading(2, "After the table");

Calling table methods after End() records validation errors.

InlineFactory methods

Call markdown.inline() to create explicit inline nodes. Use inline helpers when ordinary escaped strings are not enough.

const i = markdown.inline();

Text(text)

Creates escaped text.

i.Text("literal *stars*")

Raw(markdown)

Creates trusted raw inline Markdown. Use sparingly and never for untrusted data.

i.Raw("<kbd>Ctrl</kbd> + <kbd>C</kbd>")

Code(code)

Creates a code span with safe backtick fencing.

i.Code("go test ./...")

Em(...parts) and Strong(...parts)

Creates emphasis and strong emphasis.

markdown.builder()
  .Paragraph("Status: ", i.Strong("complete"));

Link(text, url, title?)

Creates a Markdown link.

i.Link("docs", "https://example.com/docs", "Documentation")

Render results

Render() returns a Go-backed result object.

const result = markdown.builder().Title("Report").Render();

console.log(result.Text);   // rendered Markdown
console.log(result.Bytes);  // byte length of Text
console.log(result.Blocks); // number of document blocks

RenderString() returns only result.Text. RenderHTML() renders the generated Markdown through the same goldmark path used by markdown.renderHTML(input).

Validation behavior

The builder accumulates structural errors and reports them during Validate(), Render(), RenderString(), or RenderHTML().

Common validation failures include:

• heading level outside 1..6,
• table without columns,
• table row width mismatch,
• unknown table alignment,
• ordered-list start less than 1,
• code-block language containing whitespace,
• table mutation after End().

Example:

const result = markdown.builder()
  .Heading(9, "bad")
  .Table().Columns("A", "B").Row("only one cell").End()
  .Validate();

if (!result.Valid) {
  console.error(result.Errors.join("\n"));
}

Complete example

This example generates a small report with a table, checklist, and inline code.

const markdown = require("markdown");
const i = markdown.inline();

const rows = [
  { name: "Service layer", status: "done", owner: "Ada" },
  { name: "Goja module", status: "done", owner: "Linus" },
  { name: "Docs", status: "review", owner: "Intern" },
];

const table = markdown.builder()
  .Title("Markdown Builder Report")
  .Paragraph("Generated by ", i.Code('require("markdown").builder()'), ".")
  .Table()
    .Columns(
      { label: "Name", align: "left" },
      { label: "Status", align: "center" },
      { label: "Owner", align: "left" }
    );

for (const row of rows) {
  table.Row(row.name, row.status, row.owner);
}

const output = table.End()
  .Heading(2, "Next steps")
  .Checklist([
    { text: "Run tests", checked: true },
    { text: "Review generated Markdown", checked: false },
  ])
  .RenderString();

console.log(output);

CLI examples

The generated binary bundles example data for the builder API.

./dist/goja-text markdown builder-examples
./dist/goja-text markdown builder-example report
./dist/goja-text markdown builder-example api-table
./dist/goja-text markdown builder-example report --output-path report.md

These commands are examples of using the JavaScript API from jsverbs. They are not required when writing normal scripts; scripts can call require("markdown").builder() directly.

Troubleshooting

See also

• goja-text-markdown-api-reference for parsing, traversal, validation, and HTML rendering.
• goja-text-markdown-user-guide for the broader Markdown module workflow.
• goja-text-template-api-reference when a fixed template file is a better fit than programmatic document assembly.
• goja-text-template-writing-documentation for template-based documentation generation.