Class MarkdownDocument

Creates instance for building a Markdown document.

Add all blocks from another document.

Useful for reusing code.

Example

const footerDoc = new MarkdownDocument().rule().paragraph('Some footer content.')
const mainDoc = new MarkdownDocument()
  // ... add main blocks ...
  .$concat(footerDoc)
Copy

Add all blocks from multiple other documents.

Useful for reusing code.

Example

const intro = new MarkdownDocument().heading(1, 'Main title').paragraph('Some text.')
const chapter1 = new MarkdownDocument().heading(2, 'Chapter title').paragraph('Some text.')
const chapter2 = new MarkdownDocument().heading(2, 'Chapter title').paragraph('Some text.')
const conclusion = new MarkdownDocument().heading(2, 'Conclusion').paragraph('Some text.')

new MarkdownDocument()
  .$concat(intro, chapter1, chapter2, conclusion)
Copy

Iteratively adds element to document using callback function.

Convenient when multiple elements need be added dynamically per item in array.

Example

new MarkdownDocument().$foreach(
  sections,
  (doc, section) => doc.heading(2, section.title).paragraph(section.content)
)
Copy

Conditionally adds elements to document using callback function.

Convenient when multiple elements are subject to same conditional logic.

Example

new MarkdownDocument()
  .$if(
    shouldIncludeFooter(),
    doc => doc.rule().paragraph('Some footer content.')
  )
Copy

Example

new MarkdownDocument()
  .$if(
    items.length > 0,
    doc => doc.paragraph(`${items.length} items found:`).list(items),
    doc => doc.paragraph('No items found.')
  )
Copy

Adds code block to document (unless empty), without any syntax highlighting.

Example

new MarkdownDocument().code('npm install build-md')
Copy

See

md.code

Adds code block to document (unless empty), with syntax highlighting.

Example

new MarkdownDocument().code('ts', `function greet(name: string): void {
  console.log('Hello, ' + name + '!');
}`)
Copy

See

md.code

Adds expandable details element (unless empty) to document, without custom summary text.

Not part of Markdown syntax, relies on support for HTML rendering.

Example

new MarkdownDocument()
  .details('text hidden until expanded')
  .details(md`text with ${bold('inline')} and ${list(['block'])} elements.`)
Copy

See

md.details

Adds expandable details element (unless empty) to document, with custom summary text.

Not part of Markdown syntax, relies on support for HTML rendering.

Example

new MarkdownDocument()
  .details('summary text always shown', 'text hidden until expanded')
  .details(
    md`summary text with ${italic('inline')} formatting`,
    md`text with ${bold('inline')} and ${list(['block'])} elements.`
  )
Copy

See

md.details method

Adds heading to document (unless empty).

Example

new MarkdownDocument()
  .heading(1, 'Top-level heading')
  .heading(2, md`Sub-heading with ${code('inline formatting')}`)
Copy

See

md.heading

Adds unordered list to document (unless empty).

Example

new MarkdownDocument()
  .list(['first item', 'second item'])
  .list([
    md`first item with ${italic('text formatting')}`,
    md`second item with nested list:${md.list([
     "second item's first item",
     "second item's second item"
    ])}`
  ])
Copy

See

md.list

Adds unordered list to document (unless empty).

Example

new MarkdownDocument()
  .list('unordered', ['first item', 'second item'])
  .list('unordered', [
    md`first item with ${italic('text formatting')}`,
    md`second item with nested list:${md.list('unordered', [
     "second item's first item",
     "second item's second item"
    ])}`
  ])
Copy

See

md.list

Adds ordered list to document (unless empty).

Example

new MarkdownDocument()
  .list('ordered', ['first item', 'second item'])
  .list('ordered', [
    md`first item with ${italic('text formatting')}`,
    md`second item with nested list:${md.list('ordered', [
     "second item's first item",
     "second item's second item"
    ])}`
  ])
Copy

See

md.list

Adds task list to document (unless empty). Also known as checklist or todo list.

Part of extended Markdown syntax, not supported by all Markdown processors.

Example

new MarkdownDocument().list('task', [
  [true, 'first task is done'],
  [false, 'second task is done']
])
Copy

See

md.list

Adds paragraph to document (unless empty).

Example

new MarkdownDocument()
  .paragraph('Some text content.')
  .paragraph(md`Some text content with ${bold('formatting')}.`)
Copy

See

md.paragraph

Adds quote block to document (unless empty).

Example

new MarkdownDocument()
  .quote('Some quoted text.')
  .quote(md`Some quoted text with ${bold('formatting')}.`)
Copy

See

md.quote

Adds horizontal rule to document.

Example

new MarkdownDocument().rule()
Copy

See

md.rule

Adds table to document (unless no columns).

Part of extended Markdown syntax, not supported by all Markdown processors.

Example

new MarkdownDocument().table(['x', 'y'], [['0', '0'], ['5', '20']])
Copy

Example

new MarkdownDocument().table(
  [
    { heading: 'Error', alignment: 'left' },
    { heading: link('./environments.md', 'Environment'), alignment: 'center' },
    { heading: 'Occurrences', alignment: 'right' },
  ],
  [
    [
      code("TypeError: Cannot read properties of undefined (reading 'push')"),
      'production',
      '19',
    ],
    [
      code("TypeError: Cannot read properties of null (reading '0')"),
      'staging',
      '5',
    ],
  ]
)
Copy

See

md.table

Renders document to Markdown.