/artisan • Aubade

aubade@0.11.5

Overview /artisan /manifest /conductor /palette /transform /browser Libretto Philosophy

the /artisan module provides Aubade’s content processing utilities — a token-based markdown compiler rather than a regex-based parser. it’s built to handle nested structures reliably, and can be used on its own or alongside other Aubade components in any JavaScript environment.

here be dragons — this feature is experimental. expect missing pieces and breaking changes as the compiler evolves.

Aubade implements Libretto, a markdown dialect designed to keep documents readable while giving Aubade precise control over parsing and rendering. this section covers the compiler interface and customization hooks exposed through /artisan.

engrave

export function engrave(input: string): {
	tokens: Token[];
	html(overrides?: Options['renderer']): string;
	visit(visitors: Options['transform']): Block[];
};

engrave() is the default parser, pre-configured with Aubade’s settings. use it for common cases where you don’t need custom rendering.

import { engrave } from 'aubade/artisan';

engrave('hello world').html();
// -> <p>hello world</p>

forge

export type Director = (panel: {
	data: Extract<Token, { type: 'aubade:directive' }>['meta']['data'];
	annotate(source: string): string;
	print(...lines: Array<string | false>): string;
	sanitize: typeof escape;
}) => string;

export type Resolver<T extends Token['type'] = Token['type']> = (panel: {
	token: Extract<Token, { type: T }>;
	render(token: Token): string;
	sanitize: typeof escape;
}) => string;

export interface Options {
	directive?: { [key: string]: Director };
	renderer?: { [T in Token as T['type']]?: Resolver<T['type']> };
	transform?: { [T in Token as T['type']]?: (token: T) => T };
}

export function forge(options: Options = {}): typeof engrave;

forge() creates a parser instance with custom rendering rules. use it when you need to override how specific tokens are transformed into HTML.

import { engrave, forge } from 'aubade/artisan';

engrave('hello *world*').html();
// -> <p>hello <em>world</em></p>

const mark = forge({
	renderers: {
		'inline:emphasis': ({ token, render }) => `<i>${token.children.map(render).join('')}</i>`,
	},
});

mark('hello *world*').html();
// -> <p>hello <i>world</i></p>

typography

export function typography(text: string): string;

typography() applies smart punctuation transformations to plain text, such as converting typewriter (straight) quotes to typographic (fancy) quotes, replacing double and triple hyphens with en and em dashes, and converting three consecutive dots to an ellipsis.