DOCSEARCHbyAlgolia
Submit Docs

mdit-plugins

website·Indexed 30 days ago

https://mdit-plugins.github.io

A collection of plugins for markdown-it, providing extended grammar and rendering support. Includes plugins for math expressions (@mdit/plugin-tex, @mdit/plugin-mathjax, @mdit/plugin-katex), layout and containers (@mdit/plugin-container, @mdit/plugin-layout, @mdit/plugin-tab), image enhancements (@mdit/plugin-img-size, @mdit/plugin-img-mark, @mdit/plugin-img-lazyload), and various syntax extensions like footnotes, tasklists, subscripts, superscripts, and GFM style alerts.

Tokens
17.1K
Snippets
111
Records
125
Agent score
75%

What's inside mdit-plugins

  1. Apply default styles for @mdit/plugin-alert

    To apply the default visual styles for the alert boxes, import the provided CSS file from the package.
    import "@mdit/plugin-alert/style";

  2. Install and initialize @mdit/plugin-include

    The @mdit/plugin-include plugin allows you to include other files in your markdown. Because markdown-it only receives content strings in its render() method, you must provide the current file path via the env object and configure the currentPath option so the plugin can resolve relative paths for included files.
    import MarkdownIt from "markdown-it";
import { include } from "@mdit/plugin-include";

const mdIt = new MarkdownIt().use(include, {
  // currentPath is required to resolve relative includes
  currentPath: (env) => env.filePath,
});

// Pass the current file path in the env object during render
mdIt.render("<!-- @include: ./path/to/include/file.md -->", {
  filePath: "path/to/current/file.md",
});

  3. Install and use @mdit/plugin-img-mark in markdown-it

    The @mdit/plugin-img-mark plugin allows you to specify which images should appear in light mode versus dark mode by appending a suffix to the image URL (e.g., #light or #dark). The plugin converts these suffixes into data-mode="lightmode-only" or data-mode="darkmode-only" attributes on the <img> tag.
    import MarkdownIt from "markdown-it";
import { imgMark } from "@mdit/plugin-img-mark";

const mdIt = new MarkdownIt().use(imgMark, {
  // options are optional
});

// Example usage in markdown
mdIt.render("![image](https://example.com/image.png#light)");

  4. Install and configure @mdit/plugin-advanced-links

    The @mdit/plugin-advanced-links plugin allows you to register custom identifiers (names) that trigger a specific HTML renderer when the @[name ...props](link) syntax is encountered in Markdown. You can call .use(advancedLinks, config) multiple times to register different identifiers.
    import MarkdownIt from "markdown-it";
import { advancedLinks } from "@mdit/plugin-advanced-links";

const md = new MarkdownIt()
  .use(advancedLinks, {
    name: "video",
    renderer: (link, props) =>
      `<video src="${link}" controls${props.autoplay ? " autoplay" : ""}></video>`,
  })
  .use(advancedLinks, {
    name: "badge",
    inline: true,
    renderer: (link, props) => `<span class="badge badge-${link}">${props.text || link}</span>`,
  });

  5. Integrate @mdit/plugin-tex into markdown-it

    @mdit/plugin-tex is a developer-facing plugin that registers markdown rules for TeX. It identifies TeX tokens in the markdown source and replaces them with the output of a user-provided render function. For out-of-the-box solutions, use @mdit/plugin-katex or @mdit/plugin-mathjax.
    import MarkdownIt from "markdown-it";
import { tex } from "@mdit/plugin-tex";

const mdIt = new MarkdownIt().use(tex, {
  render: (content, displayMode) => {
    // render tex here and return the resulting string
    return renderTex(content, displayMode);
  },
});

mdIt.render("$E=mc^2$");

  6. Integrate @mdit/plugin-uml into markdown-it

    @mdit/plugin-uml is a plugin that extracts content between a specified opening marker and closing marker into a single token. Unlike container plugins, the content inside these markers is treated as plain text and is not parsed as markdown. To avoid parsing markers, you can escape the @ symbol using a backslash (e.g., \@demostart).
    import MarkdownIt from "markdown-it";
import { uml } from "@mdit/plugin-uml";

const mdIt = new MarkdownIt().use(uml, {
  name: "demo",
  open: "demostart",
  close: "demoend",
  renderer: (tokens, index) => {
    // render content here
  },
});

mdIt.render(`\n@demostart
Content
Another content
@demoend
`);

  7. Create tabs using @mdit/plugin-tab syntax

    Tabs are created using a container syntax and markers:

    1. Container: Open with ::: name and close with :::, where name is the value configured in the plugin options (e.g., tabs).
    2. Tab Markers: Use @tab to separate tab contents.
      • Text following @tab becomes the tab title.
      • Use @tab:active to set a tab as the default active state.
    3. Content: Any content after a @tab marker and before the next marker or the closing ::: is treated as the tab body. Content appearing before the first @tab marker is ignored.
    4. Identifiers: You can add an ID suffix to the container (::: tabs#id) and the markers (@tab title#id) to synchronize switching states across different tab sets.
    5. Escaping:
      • Use \@tab to render the literal text @tab at the start of a line.
      • Use \# to include a hash symbol in a tab title (e.g., @tab c\#).
    ::: tabs#fruit

@tab apple#apple
Apple content here

@tab:active banana#banana
Banana content here

:::

  8. Install and use @mdit/plugin-spoiler in markdown-it

    The @mdit/plugin-spoiler plugin allows you to hide content within markdown using the !!content!! syntax. To use it, import the plugin and add it to your markdown-it instance via the .use() method. To apply the default visual styles for the spoiler elements, import @mdit/plugin-spoiler/style in your project.
    import MarkdownIt from "markdown-it";
import { spoiler } from "@mdit/plugin-spoiler";

const mdIt = new MarkdownIt().use(spoiler);

mdIt.render("VuePress Theme Hope is !!powerful!!.");

  9. Install and use @mdit/plugin-figure

    The @mdit/plugin-figure plugin for markdown-it automatically wraps standalone images (or linked images) in a <figure> element. The image's title or alt text is used as the content for the <figcaption>.
    import MarkdownIt from "markdown-it";
import { figure } from "@mdit/plugin-figure";

const mdIt = new MarkdownIt().use(figure, {
  // your options, optional
});

mdIt.render("![image](https://example.com/image.png)");

  10. Install and initialize @mdit/plugin-tab

    The @mdit/plugin-tab plugin allows you to create block-level custom tabs in Markdown. To use it, import the tab plugin and register it with a markdown-it instance. The name option is required and defines the identifier used to open the tab container.
    import MarkdownIt from "markdown-it";
import { tab } from "@mdit/plugin-tab";

const mdIt = new MarkdownIt().use(tab, {
  name: "tabs", // Required: the name of the tab container
});

mdIt.render("content");

  11. Install and initialize @mdit/plugin-snippet

    The @mdit/plugin-snippet plugin allows you to import code snippets into markdown. It requires a Node.js runtime. Because markdown-it does not natively know the file path of the content being rendered, you must provide a currentPath function in the options to resolve the location of the markdown file relative to the snippets.
    import MarkdownIt from "markdown-it";
import { snippet } from "@mdit/plugin-snippet";

const mdIt = new MarkdownIt().use(snippet, {
  // currentPath is required
  currentPath: (env) => env.filePath,
});

// Pass the filePath in the env object during render
mdIt.render("<<< example.ts", {
  filePath: "path/to/current/file.md",
});

  12. Install and use @mdit/plugin-attrs

    The @mdit/plugin-attrs plugin allows you to add HTML attributes to Markdown content. It is integrated into markdown-it using the .use() method.
    import MarkdownIt from "markdown-it";
import { attrs } from "@mdit/plugin-attrs";

const mdIt = new MarkdownIt().use(attrs, {
  // your options, optional
});

mdIt.render("# Heading 🎉{#heading}");