Loaders

Loaders transform content files by file extension. Register them with the $loaders config field.

Register a loader

A loader gets the file name, its content, and a set of utilities. It returns the new file name, the new content, and optional metadata and headings:

export const $loaders = {
	md(filename, content, utils) {
		return {
			filename: filename + '.html',
			content: renderedHtml,
			metadata: { title: '...' },
			headings: [{ level: 2, id: 'install', text: 'Install' }],
		};
	},
};

bongo passes the content of the file as a Uint8Array. Use utils.decode to read it as text. The metadata becomes the frontmatter of the page, in $page.params.

headings lists the headings of the HTML, in document order, as { level, id, text, html }. html is optional: without it, bongo uses the escaped text. The list becomes $page.headings, and the page's entry in $pages. When more than one loader in a chain gives headings, the last one wins.

Loader chains

bongo chains loaders by extension. A .md file produces .md.html. The .html extension stops the chain, and the file enters the template pipeline as a page.

When a loader returns a file name with a new extension that has its own loader, that loader runs next. The chain stops when the extension does not change, when no loader exists for it, or when it is .html, .htm, or .hbs.

Loader utilities

• utils.decode(uint8array) — convert a buffer to a string.
• utils.render(partialName, args) — invoke a registered partial. See Partials.
• utils.attrs(input) — parse element attributes, like title="Hi" count=2 tags=[a, b] featured, into data. Values are never evaluated. @bongo/markdown uses it for <bongo:*> partial elements. See Elements.
• utils.frontmatter(content) — parse the --- block at the top of content, as Frontmatter describes. It returns { offset, value }, where offset is where the body starts.

Types

Type a loader with the Loader type from bongo. See TypeScript.