rehype-github

November 27, 2024 · View on GitHub

rehype plugins that match how GitHub transforms markdown on their site.

👉 Note: work in progress. some things are not yet finished.

What is this?
When should I use this?
Install
Packages
Examples
- Example: comments
- Example: files
Types
Compatibility
Security
Related
Contribute
Notice
License

What is this?

This project is a monorepo that contains many packages that can be used together or on their own, with defaults to match GitHub or with configuration to match your site, to process user content for safe use on the web.

When should I use this?

You can use these tools when you need to:

match GitHub in how it transforms markdown to HTML
build similar pipelines to bring user content to the masses

Install

Currently, install and use each package manually.

Packages

remark-github-break — turn normal line endings into hard breaks (comments)
remark-github-yaml-metadata — show frontmatter as a table (files)
rehype-github-alert — enhance alerts (everywhere)
rehype-github-color — enhance code for colors (comments)
rehype-github-dir — add dir=auto to elements (everywhere)
rehype-github-emoji — enhance emoji and gemoji (everywhere)
rehype-github-heading — enhance headings (files)
rehype-github-highlight — perform syntax highlighting on code (to do, meanwhile use rehype-starry-night)
rehype-github-image — enhance images (everywhere)
rehype-github-link — enhance links (everywhere)
rehype-github-mention — enhance mentions (to do)
rehype-github-notranslate — enhance raw text with notranslate (comments)
rehype-github-reference — enhance references (to do)
rehype-github-sanitize — clean dangerous HTML (to do, meanwhile use rehype-sanitize)

GitHub additionally includes client side code to enhance certain code blocks by evaluating their contents. This behavior is performed by:

viewscreen-geojson — viewscreen component for geojson and topojson
viewscreen-mermaid — viewscreen component for mermaid
viewscreen-stl — viewscreen component for STL (3D geometry)

See example/viewscreen/ on how to use them together.

To do:

investigate task lists
investigate mathjax
investigate port of treelights
investigate linking to labels, issues, pulls, files, lines in files

Examples

Example: comments

A pipeline that gets close to how GitHub transforms comments:

import rehypeGithubAlert from 'rehype-github-alert'
import rehypeGithubColor from 'rehype-github-color'
import rehypeGithubDir from 'rehype-github-dir'
import rehypeGithubEmoji from 'rehype-github-emoji'
import rehypeGithubImage from 'rehype-github-image'
import rehypeGithubLink from 'rehype-github-link'
import rehypeGithubNoTranslate from 'rehype-github-notranslate'
import rehypeRaw from 'rehype-raw'
import rehypeSanitize from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'
import remarkGithubBreak from 'remark-github-break'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkGithubBreak)
  .use(remarkRehype, {allowDangerousHtml: true})
  .use(rehypeRaw)
  .use(rehypeGithubAlert)
  .use(rehypeGithubColor)
  .use(rehypeGithubDir)
  .use(rehypeGithubEmoji)
  .use(rehypeGithubImage)
  .use(rehypeGithubLink)
  .use(rehypeGithubNoTranslate)
  .use(rehypeSanitize)
  .use(rehypeStringify)
  .process('hi!')

console.log(String(file))

Yields:

<p dir="auto">hi!</p>

Example: files

A pipeline that gets close to how GitHub transforms files:

import rehypeGithubAlert from 'rehype-github-alert'
import rehypeGithubDir from 'rehype-github-dir'
import rehypeGithubEmoji from 'rehype-github-emoji'
import rehypeGithubHeading from 'rehype-github-heading'
import rehypeGithubImage from 'rehype-github-image'
import rehypeGithubLink from 'rehype-github-link'
import rehypeRaw from 'rehype-raw'
import rehypeSanitize from 'rehype-sanitize'
import rehypeStringify from 'rehype-stringify'
import remarkGithubYamlMetadata from 'remark-github-yaml-metadata'
import remarkParse from 'remark-parse'
import remarkRehype from 'remark-rehype'
import {unified} from 'unified'

const file = await unified()
  .use(remarkParse)
  .use(remarkGithubYamlMetadata)
  .use(remarkRehype, {allowDangerousHtml: true})
  .use(rehypeRaw)
  .use(rehypeGithubAlert)
  .use(rehypeGithubDir)
  .use(rehypeGithubEmoji)
  .use(rehypeGithubHeading)
  .use(rehypeGithubImage)
  .use(rehypeGithubLink)
  .use(rehypeSanitize)
  .use(rehypeStringify)
  .process('hi!')

console.log(String(file))

Yields:

<p dir="auto">hi!</p>

Types

These packages are fully typed with TypeScript.

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.

Security

Be wary of user input and use rehype-sanitize.

rehype-sanitize — sanitize HTML
rehype-starry-night — apply syntax highlighting to code with starry-night