@nasa-gcn/remark-rehype-astro

remark-rehype-astro

This is the reference implementation of Astro Flavored Markdown, a dialect of Markdown for rapid astronomy communications. Astro Flavored Markdown detects and enriches dates, times, sky coordinates, and bibliographic references in text.

The package is a plugin for the Unified parser ecosystem. It can be used as either a plugin for Remark or for Rehype. Use it in Remark mode to output a symbolic representation of the Markdown content (for example, to extract data nodes from it). Use it in Rehype mode if you want to render Astro Flavored Mardkown as HTML (for example, for inclusion in a Web page).

For supported syntax, see the src/replacements directory. In each directory there is a file called test.md illustrating the Markdown syntax, a file called test.json containing the resulting astract syntax tree, and a file called test.html showing how it is rendered in HTML.

You can experiment with Astro Flavored Markdown from the command line using https://github.com/nasa-gcn/afm.

Remark mode

When you use the plugin in Remark mode, it tags Astro Flavored Markdown nodes in the mdast syntax tree by adding data attributes with class and value attributes indicating the kind of data and a normalized, computable value.

Here is a basic pipeline for processing in Remark mode:

import { remarkAstro } from '@nasa-gcn/remark-rehype-astro'
import remarkParse from 'remark-parse'
import { unified } from 'unified'

const processor = unified().use(remarkParse).use(remarkAstro)

The following Markdown text:

See GCN Circular 123

is represented by the following syntax tree:

{
  "type": "root",
  "children": [
    {
      "type": "text",
      "value": "See GCN Circular "
    },
    {
      "type": "text",
      "value": "123",
      "data": {
        "class": "gcn-circular",
        "value": 123
      }
    }
  ]
}

Rehype mode

When you use the plugin in Rehype mode, it converts Astro Flavored Markdown nodes into HTML <data> elements with class and value attributes indicating the kind of data and a normalized, computable value.

Here is a basic pipeline for processing in Remark mode:

import { rehypeAstro } from '@nasa-gcn/remark-rehype-astro'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import { unified } from 'unified'

const processor = unified().use(remarkParse).use(remarkRehype).use(rehypeAstro)

The following Markdown text:

See GCN Circular 123

is represented by the following HTML:

<p>See <data class="gcn-circular" value="123">123</data></p>

You can enrich these <data> elements using CSS, JavaScript, or by rendering them as custom React components using rehype-react.

For an example of Astro Flavored Markdown enriched with React components, see the following files:

• https://github.com/nasa-gcn/gcn.nasa.gov/blob/main/app/routes/circulars.%24circularId.(%24version)/Body.tsx
• https://github.com/nasa-gcn/gcn.nasa.gov/blob/main/app/routes/circulars.%24circularId.(%24version)/AstroData.tsx
• https://github.com/nasa-gcn/gcn.nasa.gov/blob/main/app/routes/circulars.%24circularId.(%24version)/AstroData.components.tsx