Markdown Tags for VitePress VitePress plugin

Reading Time

Reading time for this document is 1 minute for 241 words.

@binarynoir/vitepress-markdown-tags turns ((tag|Done|green)) into styled badges on a VitePress 2 site. See the syntax and a live demo first if you haven't.

Install

npm install --save-dev @binarynoir/vitepress-markdown-tags

Use

Three small pieces: config, theme and Markdown.

// .vitepress/config.mts
import { defineConfig } from 'vitepress';
import { markdownTags, stripTags } from '@binarynoir/vitepress-markdown-tags';

export default defineConfig({
  markdown: {
    config(md) {
      md.use(markdownTags);
    },
  },
  // Keep tag syntax out of page titles.
  transformPageData(pageData) {
    if (typeof pageData.title === 'string') pageData.title = stripTags(pageData.title);
  },
});

// .vitepress/theme/index.ts
import DefaultTheme from 'vitepress/theme';
import { registerMarkdownTags } from '@binarynoir/vitepress-markdown-tags/theme';
import '@binarynoir/vitepress-markdown-tags/style.css';

export default {
  extends: DefaultTheme,
  enhanceApp({ app }) {
    registerMarkdownTags(app);
  },
};

Prefer one call? withMarkdownTags(config) from @binarynoir/vitepress-markdown-tags/vitepress does the config part for you.

Tagged pages

Add tagged: true to any page's frontmatter and it lists every tag used across the site, grouped by label, each with a link to the section that uses it. The list goes at the end of the page, or wherever you put a <!-- tagged-pages --> comment on its own line.

Builds need nothing else. To keep these pages current while you edit in vitepress dev, also add the Vite plugin (withMarkdownTags adds it for you):

// .vitepress/config.mts
import { taggedPagesVitePlugin } from '@binarynoir/vitepress-markdown-tags/vitepress';

export default defineConfig({
  vite: { plugins: [taggedPagesVitePlugin()] },
});

See the site-wide list on Tagged pages. To narrow a list, give tagged settings instead of true. The apps roadmap only looks inside apps/ and only lists two labels:

---
tagged:
  include: [done, planned]
  folders: [apps]
---

Setting	Default	Description
include	all labels	Only list these labels.
exclude	none	Never list these labels. Wins over include.
folders	whole site	Only scan pages in these folders, relative to the docs root.

Labels match case-insensitively, and tags inside code are ignored.

Options

Option	Default	Description
componentName	'MarkdownTag'	Component the syntax compiles to.
stripFromTitles	true	withMarkdownTags only: remove tag syntax from page titles.

Style any color with one custom property: .md-tag--green { --md-tag-color: #2e8555; }.

Source and full README on GitHub