readme.md

rehype-github

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

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

Contents

• 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:

1. match GitHub in how it transforms markdown to HTML
2. 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.

Related

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

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

MIT © Titus Wormer