https://github.com/rockchalkwushock/rehype-code-titles
Rehype plugin for parsing code blocks and adding titles to code blocks
https://github.com/rockchalkwushock/rehype-code-titles
mdx rehype rehype-plugin remark unified
Last synced: 2 months ago
JSON representation
Rehype plugin for parsing code blocks and adding titles to code blocks
- Host: GitHub
- URL: https://github.com/rockchalkwushock/rehype-code-titles
- Owner: rockchalkwushock
- License: mit
- Created: 2021-04-22T23:53:11.000Z (about 4 years ago)
- Default Branch: production
- Last Pushed: 2023-03-06T03:57:48.000Z (about 2 years ago)
- Last Synced: 2025-02-27T09:50:24.285Z (3 months ago)
- Topics: mdx, rehype, rehype-plugin, remark, unified
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/rehype-code-titles
- Size: 455 KB
- Stars: 22
- Watchers: 3
- Forks: 2
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
Awesome Lists containing this project
README
# rehype-code-titles
[](https://www.npmjs.com/package/rehype-code-titles)
[](#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 12+ 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
```
## 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
lib/mdx.ts
```
## 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 makes use of [`@arkweid/lefthook`](https://github.com/evilmartians/lefthook) and will run `eslint`, `jest`, and `prettier`
against all staged files.
```shell
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](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)):
Cody Brunner
💻 📖 ⚠️
Taran Bains
This project follows the [all-contributors](https://github.com/all-contributors/all-contributors) specification. Contributions of any kind welcome!