rehype-code-titles

Rehype plugin for parsing code blocks and adding titles to code blocks

Downloads in past

Stats

StarsIssuesVersionUpdatedCreatedSize
rehype-code-titles
19101.2.0a year ago3 years agoMinified + gzip package size for rehype-code-titles in KB

Readme

rehype-code-titles
npm

All Contributors

Rehype plugin for parsing code blocks and adding titles to code blocks

Why?

I moved my blog over to using mdx-bundler which uses xdm under the hood to parse the markdown and MDX files. I was using remark-code-titles prior to this move and unfortunately it no longer worked. I believe this was because of the order plugins were being applied internally for xdm. I'd never really worked with remark or rehype directly before and didn't have a lot of experience with ASTs so this was a fun little project that I initially built directly into my blog before pulling it out at a plugin to ship to other developers.
Many thanks to @mottox2, @mapbox, & @wooorm for their prior work in this ecosystem it was of great help when creating this plugin.

Installation

This package is ESM only: Node 12+ is needed to use it and it must be imported instead of required.

npm install rehype-code-titles

yarn add rehype-code-titles

pnpm add rehype-code-titles

API

This package exports no identifiers. The default export is rehypeCodeTitles

rehype().use(rehypeCodeTitles[, options])

Add support for stripping out code titles from input.

options

options.customClassName
Specify your own custom css class name to apply. Defaults to rehype-code-title. Note: you will have to write the CSS implementation yourself.
For example
// some global css file
.rehype-code-title {
  margin-bottom: -0.6rem;
  padding: 0.5em 1em;
  font-family: Consolas, 'Andale Mono WT', 'Andale Mono', 'Lucida Console',
    'Lucida Sans Typewriter', 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono',
    'Liberation Mono', 'Nimbus Mono L', Monaco, 'Courier New', Courier,
    monospace;

  background-color: black;
  color: white;
  z-index: 0;

  border-top-left-radius: 0.3em;
  border-top-right-radius: 0.3em;
}
options.titleSeparator
Specify the title separator for rehype-code-title. Defaults to: :.
// default behavior will be
'language-typescript:lib/mdx.ts' // the title will be lib/mdx.ts
'language-typescript:title=lib/mdx.ts' // title will be title=lib/mdx.ts

// titleSeparator set to :title=
'language-typescript:lib/mdx.ts' // Wont work! 😱. Does not match the separator
'language-typescript:title=lib/mdx.ts' // title will be lib/mdx.ts

Input

````md

Code Example

```typescript:lib/mdx.ts // code here
````

### Output

```html
<div class="rehype-code-title">lib/mdx.ts</div>
<pre>
  <code class="language-typescript">
  <!-- HTML parse code here -->
  </code>
</pre>

Usage

Use this package as a rehype plugin.
const rehype = require('rehype')
const rehypeCodeTitles = require('rehype-code-titles')
const rehypePrism = require('@mapbox/rehype-prism')

rehype()
  .use(rehypeCodeTitles) // should always be before rehypePrism.
  .use(rehypePrism)
  .process(/* some html */)

const unified = require('unified')
const rehypeParse = require('rehype-parse')
const rehypeCodeTitles = require('rehype-code-titles')
const rehypePrism = require('@mapbox/rehype-prism')

unified()
  .use(rehypeParse)
  .use(rehypeCodeTitles)
  .use(rehypePrism)
  .processSync(/* some html */)

Development

This repository makes use of @arkweid/lefthook and will run eslint, jest, and prettier against all staged files.
git clone https://github.com/rockchalkwushock/rehype-code-titles.git
cd rehype-code-titles
pnpm i
# Do cool stuff with code
git add .
git commit -m "feat(src): a cool new feature"
# pre-commit hooks run: eslint, jest, and prettier
git push

Contributing

Please visit CONTRIBUTING.md

License

MIT © Cody Brunner

Contributors ✨

Thanks goes to these wonderful people (emoji key):
<td align="center"><a href="https://codybrunner.com"><img src="https://avatars.githubusercontent.com/u/19720404?v=4?s=100" width="100px;" alt=""/><br /><sub><b>Cody Brunner</b></sub></a><br /><a href="https://github.com/rockchalkwushock/rehype-code-titles/commits?author=rockchalkwushock" title="Code">💻</a> <a href="https://github.com/rockchalkwushock/rehype-code-titles/commits?author=rockchalkwushock" title="Documentation">📖</a> <a href="https://github.com/rockchalkwushock/rehype-code-titles/commits?author=rockchalkwushock" title="Tests">⚠️</a></td>



This project follows the all-contributors specification. Contributions of any kind welcome!