$3

If you find remark-flexible-code-titles useful in your projects, consider supporting my work.
Your sponsorship means a lot 💖

Be the first sponsor and get featured here and on my sponsor wall.
Thank you for supporting open source! 🙌

remark-flexible-code-titles

[![npm version][badge-npm-version]][url-npm-package]
[![npm downloads][badge-npm-download]][url-npm-package]
[![publish to npm][badge-publish-to-npm]][url-publish-github-actions]
[![code-coverage][badge-codecov]][url-codecov]
[![type-coverage][badge-type-coverage]][url-github-package]
[![typescript][badge-typescript]][url-typescript]
[![license][badge-license]][url-license]

This package is a [unified][unified] ([remark][remark]) plugin to add title or/and container for code blocks with customizable properties in markdown.

[unified][unified] is a project that transforms content with abstract syntax trees (ASTs) using the new parser [micromark][micromark]. [remark][remark] adds support for markdown to unified. [mdast][mdast] is the Markdown Abstract Syntax Tree (AST) which is a specification for representing markdown in a syntax tree.

This plugin is a remark plugin that transforms the mdast.

When should I use this?

remark-flexible-code-titles is useful if you want to add title and container or any of two for code blocks in markdown. It is able to:

- add title node above the code node, providing _custom tag name, custom class name and also additional properties_.
- add container node for the code node, providing _custom tag name, custom class name and also additional properties_.
- correct the syntax of code highligting directives on behalf of related rehype plugins (like [rehype-prism-plus][rehypeprismplus])
- handle the titles even if there is no language provided,
- handle the titles composed by more than one word (handle spaces in the title),
- provide a fallback language as an option if the language is missing.

Installation

This package is suitable for ESM only. In Node.js (16.0+), install with npm:

``bash
npm install remark-flexible-code-titles
`

or

`bash
yarn add remark-flexible-code-titles
`

Usage

Say we have the following file, example.md, which consists a code block. The code block's language is "javascript" and its title is "file.js" specified _after a colon_ :

``markdown
`javascript:file.js

`
``

And our module, example.js, looks as follows:

`javascript
import { read } from "to-vfile";
import remark from "remark";
import gfm from "remark-gfm";
import remarkRehype from "remark-rehype";
import rehypeStringify from "rehype-stringify";
import remarkCodeTitles from "remark-flexible-code-titles";

main();

async function main() {
const file = await remark()
.use(gfm)
.use(remarkCodeTitles)
.use(remarkRehype)
.use(rehypeStringify)
.process(await read("example.md"));

console.log(String(file));
}
`

Now, running node example.js yields:

`html


Without remark-flexible-code-titles, you’d get:

`html


You can use remark-flexible-code-titles even without a language, _setting the title just after a colon_ :

``markdown
`:title
This is a line of pseudo code.
`
``

Options

All options are optional and some of them have default values.

`tsx
type RestrictedRecord = Record & { className?: never };
type PropertyFunction = (language?: string, title?: string) => RestrictedRecord;

use(remarkCodeTitles, {
title?: boolean; // default is true
titleTagName?: string; // default is "div"
titleClassName?: string; // default is "remark-code-title"
titleProperties?: PropertyFunction;
container?: boolean; // default is true
containerTagName?: string; // default is "div"
containerClassName?: string; // default is "remark-code-container"
containerProperties?: PropertyFunction;
handleMissingLanguageAs?: string;
tokenForSpaceInTitle?: string;
} as CodeTitleOptions);
`

#### title

It is a boolean option for whether or not to add a title node.

By default, it is true, meaningly adds a title node if a title is provided in the language part of the code block.

`javascript
use(remarkCodeTitles, {
title: false,
});
`

If the option is false, the plugin will not add any title node.

``markdown
`javascript:file.js
console.log("Hi")
`
``

`html


    console.log("Hi")
  

#### titleTagName

It is a string option for providing custom HTML tag name for title nodes.

By default, it is div.

`javascript
use(remarkCodeTitles, {
titleTagName: "span",
});
`

Now, the title element tag names will be span.

``markdown
`javascript:file.js
console.log("Hi")
`
``

`html


    console.log("Hi")
  

#### titleClassName

It is a string option for providing custom class name for title nodes.

By default, it is remark-code-title, and all title elements' class names will contain remark-code-title.

`javascript
use(remarkCodeTitles, {
titleClassName: "custom-code-title",
});
`

Now, the title element class names will be custom-code-title.

``markdown
`javascript:file.js
console.log("Hi")
`
``

`html


    console.log("Hi")
  

#### titleProperties

It is a callback (language?: string, title?: string) => Record & { className?: never } option to set additional properties for the title node.

The callback function that takes the language and the title as optional arguments and returns object which is going to be used for adding additional properties into the title node.

The className key is forbidden and effectless in the returned object.

`javascript
use(remarkCodeTitles, {
titleProperties(language, title) {
return {
title,
["data-language"]: language,
};
},
});
`

Now, the title elements will contain title and data-color properties.

``markdown
`javascript:file.js
console.log("Hi")
`
``

`html


    console.log("Hi")
  

#### container

It is a boolean option for whether or not to add a container node.

By default, it is true, meaningly adds a container node.

`javascript
use(remarkCodeTitles, {
container: false,
});
`

If the option is false, the plugin doesn't add any container node.

``markdown
`javascript:file.js
console.log("Hi")
`
``

`html



  console.log("Hi")
`
#### containerTagName
It is a string option for providing custom HTML tag name for container nodes.
By default, it is div.
`javascript
use(remarkCodeTitles, {
  containerTagName: "section",
});
`
Now, the container element tag names will be section.
``markdown
`javascript:file.js
console.log("Hi")
`
``
`html

  
file.js

  

    console.log("Hi")