frontmatter

A YAML and formatted-markdown frontmatter processor

---

source

FrontmatterProc

 FrontmatterProc (nb)

A YAML and formatted-markdown frontmatter processor

YAML frontmatter can be added to notebooks in one of two ways:

1. By adding a raw notebook cell with --- as the first and last lines, and YAML between them, or
2. A specially formatted markdown cell. The first line should be start with a single # (creating an H1 heading), and becomes the title. Then, optionally, a line beginning with > (creating a quote block), which becomes the description. Finally, zero or more lines beginning with - (creating a list), each of which contains YAML. (If you already have “title” defined in frontmatter in a raw cell, then markdown cells will be ignored.)

For instance, our test notebook contains the following markdown cell:

# a title
> A description
- key1: value1
- key2: value2
- categories: [c1, c2]

It also contains the following raw cell:

---
execute:
  echo: false
---

When we process with FrontmatterProc, these will both be removed, and a single raw cell will be added to the top, containing the combined YAML frontmatter:

nbp = NBProcessor(_test_file, procs=FrontmatterProc)
nbp.process()
print(nbp.nb.cells[0].source)

---
categories:
- c1
- c2
description: A description
execute:
  echo: false
key1: value1
key2: value2
output-file: docs_test.html
title: a title

---

In addition, a frontmatter_ attr will be added to the notebook, containing this information as a dict:

d = nbp.nb.frontmatter_
d

{'execute': {'echo': False},
 'title': 'a title',
 'description': 'A description',
 'key1': 'value1',
 'key2': 'value2',
 'categories': ['c1', 'c2'],
 'output-file': 'docs_test.html'}