Remark-github-yaml-metadata NPM

remark-github-yaml-metadata

remark plugin to show frontmatter as a table.

What is this?

This plugin shows metadata authored with YAML frontmatter to readers.

This behavior is specific to github.com that only work in files, not in comments.

This plugin is part of a monorepo rehype-github. See its readme for more info.

When should I use this?

You can use this plugin when you want to match how github.com works or when you want to build similar pipelines.

This plugin is useful if you want to display metadata when the markdown is rendered as a preview and not as a finished, production, page. If you don’t use the metadata but something else might.

Install

This package is ESM only. In Node.js (version 16+), install with npm:

npm install remark-github-yaml-metadata

In Deno with esm.sh:

import remarkGithubYamlMetadata from 'https://esm.sh/remark-github-yaml-metadata@1'

In browsers with esm.sh:

<script type="module">
  import remarkGithubYamlMetadata from 'https://esm.sh/remark-github-yaml-metadata@1?bundle'
</script>

Use

Say our module example.js looks as follows:

import remarkFrontmatter from 'remark-frontmatter'
import remarkGithubYamlMetadata from 'remark-github-yaml-metadata'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import rehypeStringify from 'rehype-stringify'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkFrontmatter)
  .use(remarkGithubYamlMetadata)
  .use(remarkRehype)
  .use(rehypeStringify)
  .process('---\na: b\n---\n\n# hi')

console.log(String(file))

…now running node example.js yields:

<table><thead><tr><th>a</th></tr></thead><tbody><tr><td><div>b</div></td></tr></tbody></table>
<h1>hi</h1>

API

This package exports the identifiers defaultCreateErrorMessage and defaultParseOptions. The default export is remarkGithubYamlMetadata.

`defaultCreateErrorMessage(info)`

Create rich content to display an error message to the user, like GitHub does (CreateErrorMessage).

`defaultParseOptions`

Options defining how to parse YAML like GitHub (ParseOptions).

GH mostly follows YAML 1.1, with some non-standard behavior.

`remarkGithubYamlMetadata(options?)`

Plugin to show frontmatter as a table.

Parameters

options (Options) — configuration

`CreateErrorMessage`

Create rich content to display an error message to the user (TypeScript type).

Parameters

info (ErrorInfo) — info on what went wrong

Returns

One or more hast nodes (ElementContent or Array<ElementContent>).

`ErrorInfo`

Info on what went wrong (TypeScript type).

👉 Note: point and summary are defined by default, but not when turning parseOptions.prettyErrors: false.

Fields

message (string) — human readable parse error (from yaml)
point (Point or undefined) — where the error happened in the original file
summary (string or undefined) — summary with a pointer showing a codeframe of where the error happened
yaml (string) — original input YAML

`Options`

Configuration (TypeScript type).

👉 Note: it is recommended to turn allowArrayAtRoot and allowPrimitiveAtRoot on, so that arrays and primitives can be shown too. You should also probably pass parseOptions: {}, as that uses modern defaults of yaml: YAML 1.2 (which for example does not turn no into false) and not allowing duplicate keys in objects.

Fields

allowArrayAtRoot (boolean, default: false) — whether to allow arrays at the top of the YAML
allowPrimitiveAtRoot (boolean, default: false) — whether to allow primitives (and dates) at the top of the YAML
createErrorMessage (CreateErrorMessage, default: defaultCreateErrorMessage) — options defining how to show YAML errors
parseOptions (ParseOptions, default: defaultParseOptions) — options defining how to parse YAML

`ParseOptions`

Options defining how to parse YAML (TypeScript type).

Type

type ParseOptions = import('yaml').ParseOptions &
  import('yaml').DocumentOptions &
  import('yaml').SchemaOptions &
  import('yaml').ToJSOptions

Bugs

GitHub only allows top-level objects, not arrays or primitives. Instead, it parses that as if it was markdown. Which I believe to be unexpected and a bug.

GitHub also mostly follows the rules of YAML 1.1, which treats no as false, which I consider a bug.

Authoring

See § Authoring in micromark-extension-frontmatter for more info.

HTML

The markup for frontmatter is something like the following, for an object with one field:

<table>
  <thead>
    <tr><th>a</th></tr>
  </thead>
  <tbody>
    <tr><td><div>b</div></td></tr>
  </tbody>
</table>

CSS

The following CSS is needed to make frontmatter tables look like GitHub.

/* Default dark */
:root {
  --color-border-default: #30363d;
  --color-border-muted: #21262d;
  --color-canvas-default: #0d1117;
}

table {
  display: block;
  max-width: 100%;
  overflow: auto;
  width: 100%;
  width: max-content;
}

tr {
  background-color: var(--color-canvas-default);
  border-top: 1px solid var(--color-border-muted);
}

td, th {
  border: 1px solid var(--color-border-default);
  padding: 6px 13px;
}

th {
  font-weight: 600;
}

Syntax

See § Syntax in micromark-extension-frontmatter for more info.

Types

This package is fully typed with TypeScript. It exports the additional types CreateErrorMessage, ErrorInfo, Options, and ParseOptions.

Compatibility

Projects maintained by the unified collective are compatible with all maintained versions of Node.js. As of now, that is Node.js 16+. Our projects sometimes work with older versions, but this is not guaranteed.

This plugin works with unified version 6+ and remark version 7+.

Security

This package is safe.

remark-gfm — support GFM in remark
remark-frontmatter — support frontmatter syntax in remark

Contribute

See contributing.md in rehypejs/.github for ways to get started. See support.md for ways to get help.

This project has a code of conduct. By interacting with this repository, organization, or community you agree to abide by its terms.

Notice

This project is not affiliated with GitHub.

License

frontmatter github markdown mdast plugin remark

yaml @types/hast @types/mdast @types/unist micromark-util-types mdast-util-from-markdown

1.0.0

7 months ago

remark-github-yaml-metadata v1.0.0