# @sdxc/markdown
GitHub Flavored Markdown: parse to a typed AST, transform it, write it back.
The dialect is [CommonMark](https://spec.commonmark.org/) plus
[GitHub Flavored Markdown](https://github.github.com/gfm/)'s tables, task lists, strikethrough
and autolinks, GitHub's alerts and footnotes, and a few extensions: annotations, registered
tags, allowlisted HTML, variables and comments. Every node is a plain JSON object with a `type`
and a `position`, so a parsed document can be cached, sent in a payload and diffed in a test.
## Installation
```sh
npm add @sdxc/markdown
```
Results come from [`@sdxc/result`](https://www.npmjs.com/package/@sdxc/result). Frontmatter is
read as YAML and validated with any [Standard Schema](https://standardschema.dev) validator, such
as `remix/data-schema` from [`remix`](https://www.npmjs.com/package/remix), which
`@sdxc/markdown/remix` also renders into.
## Usage
### Parse a document
```typescript
import { Markdown } from "@sdxc/markdown";
import { isFailure } from "@sdxc/result";
let result = Markdown.parse("# Hello\n\nSome **markdown**.");
if (isFailure(result)) throw result.error; // a MarkdownParseError with a position
let { document } = result.data;
document.children[0]; // { type: "heading", level: 1, children: [...], position: {...} }
```
### Validate the frontmatter
```typescript
import { Markdown } from "@sdxc/markdown";
import { isFailure } from "@sdxc/result";
import * as s from "remix/data-schema";
import * as coerce from "remix/data-schema/coerce";
let Frontmatter = s.object({ title: s.string(), publishedAt: coerce.date() });
let result = Markdown.parse(source, { frontmatter: Frontmatter });
if (isFailure(result)) throw result.error; // names the line of the bad or missing field
result.data.frontmatter.publishedAt; // Date
let meta = Markdown.frontmatter(source, { frontmatter: Frontmatter }); // the block alone, body unparsed
```
### Transform it with visitors
A visitor is an object with one optional handler per node type. `Markdown.walk` applies it and
returns a new tree; `Markdown.compose` merges several so they run in one pass.
```typescript
import { Markdown } from "@sdxc/markdown";
import { headings } from "@sdxc/markdown/plugin/headings";
import { typography } from "@sdxc/markdown/plugin/typography";
let walked = Markdown.walk(
document,
Markdown.compose(headings(), typography(), {
image(node) {
return { ...node, src: new URL(node.src, "https://cdn.example.com/").href };
},
}),
);
```
### Render it
```tsx
import type { Markdown } from "@sdxc/markdown";
import type { Handle } from "remix/component";
import { toHTML } from "@sdxc/markdown/html";
import { toPlainText } from "@sdxc/markdown/plain";
import { toRemix } from "@sdxc/markdown/remix";
let html = toHTML(document); // static markup, for a feed or an email
let excerpt = toPlainText(document); // prose only, for a description or a search index
export default function Article(handle: Handle<{ document: Markdown.Document }>) {
return () => {toRemix(handle.props.document)};
}
```
### Write it back
```typescript
import { Markdown } from "@sdxc/markdown";
import { unwrap } from "@sdxc/result";
let { frontmatter, document } = unwrap(Markdown.parse(source, { frontmatter: Frontmatter }));
let written = Markdown.stringify(document, {
frontmatter: { ...frontmatter, updatedAt: new Date() },
});
```
The output is normalized markdown: parsing it and writing it again yields the same string.
## API
### `@sdxc/markdown`
#### `Markdown.parse(source: string, options?: Markdown.Options): Result<{ frontmatter, document }, MarkdownParseError>`
Reads the frontmatter block and the body. `frontmatter` is the schema's output, the YAML value as
`unknown` without a schema, or `{}` when the file has no block (a schema then runs against `{}`).
A delimited block that is not a mapping counts as body.
#### `Markdown.frontmatter(source: string, options?: Markdown.Options): Result<{ frontmatter }, MarkdownParseError>`
Reads only the frontmatter block, with the same options and rules as `parse`, so an index over
many documents skips their bodies.
#### `Markdown.stringify(document: Markdown.Document, options?: Markdown.StringifyOptions): Result`
Writes a document as markdown, with `options.frontmatter` as a YAML block ahead of it. It fails
only for a frontmatter value YAML cannot write.
#### `Markdown.walk(node: N, visitor: Markdown.Visitor): Result`
Rewrites a tree top-down, returning a node of the same type that shares every untouched subtree.
It returns a promise of the result when any handler is asynchronous.
#### `Markdown.compose(...visitors: Markdown.Visitor[]): Markdown.Visitor`
Merges visitors into one. Handlers for the same node type run in order, each on the node the
previous one returned.
#### `MarkdownParseError`, `MarkdownStringifyError`, `MarkdownWalkError`
The failures. `MarkdownParseError` carries the `position` and any schema `issues`;
`MarkdownWalkError` carries the `position` and the thrown value as `cause`.
#### `namespace Markdown`
The AST and option types. `Markdown.Node` is `Document | Block | Inline`:
| Blocks | Inline |
| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `heading` `paragraph` `code` `list` `listItem` `blockquote` `alert` `table` `tableRow` `tableCell` `thematicBreak` `html` `footnoteDefinition` `comment` `element` `tag` | `text` `emphasis` `strong` `strikethrough` `inlineCode` `link` `image` `softBreak` `hardBreak` `inlineHtml` `footnoteReference` `variable` `comment` `element` `tag` |
Each `type` names one interface (`Markdown.Heading`, `Markdown.Link`, …). `tag`, `element` and
`comment` are block or inline depending on where they are written. Every node has a `position`
(`start` and `end` points with 1-based `line` and `column` and 0-based `offset`), and every block
but `comment` has `attributes`. Link reference definitions resolve into `link` nodes.
The namespace also holds `Options` (`frontmatter`, `tags`, `html`), `StringifyOptions`,
`TagDefinition`, `Visitor`, `Attributes`, `AttributeValue`, `Position` and `Point`.
### `@sdxc/markdown/html`
#### `toHTML(node: Markdown.Node, options?: HTMLOptions): string`
Renders any node as static HTML with no wrapper. `options.tags` maps a tag name to an
`HTMLTagRenderer` (`({ name, attributes, children }) => string`, children already rendered); a tag
without one renders its children. `options.syntax: "xhtml"` self-closes void elements and writes
boolean attributes as `name="name"`, for EPUB and other XML consumers.
Raw HTML renders as escaped text. An annotation's `id` and `class` land on the element and other
attributes as `data-*`. Elements are semantic, with `md-` classes where HTML has no element:
| Class | On |
| ------------------------------------------------------------------------- | ----------------------------------------- |
| `md-alert md-alert-` | an alert's `