rehype-code-titles

# rehype-code-titles [![npm](https://img.shields.io/npm/v/rehype-code-titles?style=flat-square)](https://www.npmjs.com/package/rehype-code-titles)  [![All Contributors](https://img.shields.io/badge/all_contributors-1-orange.svg?style=flat-square)](#contributors-)  Rehype plugin for parsing code blocks and adding titles to code blocks ## Why? I moved my blog over to using [`mdx-bundler`](https://github.com/kentcdodds/mdx-bundler) which uses [`xdm`](https://github.com/wooorm/xdm) under the hood to parse the markdown and MDX files. I was using [`remark-code-titles`](https://github.com/mottox2/remark-code-titles#readme) 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](https://github.com/mottox2), [@mapbox](https://github.com/mapbox), & [@wooorm](https://github.com/wooorm) for their prior work in this ecosystem it was of great help when creating this plugin. ## Installation > This package is [ESM only](https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c): > Node 16+ is needed to use it and it must be `import`ed instead of `require`d. ```shell npm install rehype-code-titles yarn add rehype-code-titles pnpm add rehype-code-titles bun add rehype-code-titles ``` ## Node.js Support This plugin supports **Node.js 16+**, tested on Node 16, 18, 20, and 22. ⚠️ **Note**: Node 16 reached End-of-Life in September 2023 and no longer receives security updates. We recommend upgrading to Node 18 or 20 (Active LTS) for security and performance improvements. - **Minimum**: Node.js 16+ (⚠️ EOL) - **Recommended**: Node.js 18+ or 20+ (Active LTS) - **Tested**: Node.js 16, 18, 20, 22 ## 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 ```css // 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: `:`. ```tsx // 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">  </code> </pre> ``` ## Usage Use this package [as a rehype plugin](https://github.com/rehypejs/rehype/blob/main/doc/plugins.md#using-plugins). ```javascript 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 */); ``` ```javascript 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 uses [Bun](https://bun.sh) for package management and testing. ```shell git clone https://github.com/rockchalkwushock/rehype-code-titles.git cd rehype-code-titles bun install # Do cool stuff with code bun test # Run tests bun run lint # Run linter bun run build # Build the package git add . git commit -m "feat(src): a cool new feature" git push ``` ## Contributing Please visit [CONTRIBUTING.md](https://github.com/rockchalkwushock/rehype-code-titles/blob/master/CONTRIBUTING.md) ## License [MIT](https://github.com/rockchalkwushock/rehype-code-titles/blob/master/LICENSE) © [Cody Brunner](https://codybrunner.com) ## Contributors ✨ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/docs/en/emoji-key)):    <table> <tr> <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> <td align="center"><a href="https://taranveerbains.ca"><img src="https://avatars.githubusercontent.com/u/16584942?v=4" width="100px;" alt=""/><br /><sub><b>Taran Bains</b></sub></a><br /> </td> </tr> </table>    This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!