@nasa-gcn/remark-rehype-astro
v1.1.4
Published
A Remark plugin for Astro Flavored Markdown
Downloads
1,774
Readme
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