@hashicorp/remark-plugins

HashiCorp Remark Plugins

A potpourri of remark plugins used by HashiCorp to process markdown files.

Overview

MDX uses remark internally to process and transform markdown via plugins. We use MDX to process markdown content to build out our docs, learning guides, and write rich content from our CMS. This set of plugins ensures that written markdown is translated properly into markup.

Linkable Headings

The headingLinkable plugin adds anchor links to our headings so that users are able to easily link to a specific heading even if it is further down the page. See its readme for more details.

Linkable Inline Code

The inlineCodeLinkable plugin adds anchor links when a list begins with an inline code element. In many places in our docs, there are lists of methods that are structured this way, and this plugin makes it easier for users to link to a specific method. See its readme for more details.

Custom Alerts

The paragraphCustomAlerts plugin adds a custom syntax for creating alert boxes. See its readme for more details. This plugin will be deprecated for a <Alert /> component in the future in a step to move us toward full commonmark compliance.

Typography

The typography plugin adds css classes to certain typographical elements so that they adhere to the typography standards from our design system. See its readme for more details.

Usage

Each of the plugins are individually exposed from the default export from this module and can be used as any other remark plugin would be normally. For example, with raw mdx:

const mdx = require('@mdx-js/mdx')
const {typography, headingLinkable} = require('@hashicorp/remark-plugins')

console.log(mdx.sync('some markdown content', {
  remarkPlugins: [typography, headingLinkable]
})

If you'd like to use all of the plugins in one shot, which is typically the case with this module, an array of all the plugins is returned from the allPlugins export, as such:

const mdx = require('@mdx-js/mdx')
const {allPlugins} = require('@hashicorp/remark-plugins')

console.log(mdx.sync('some markdown content', {
  remarkPlugins: allPlugins
})

If you are using next-hashicorp, all of these plugins will be included by default.