From 0dde083fc658f429ddfe73726d0573df4fcfb438 Mon Sep 17 00:00:00 2001 From: Anthony Fu Date: Thu, 23 Nov 2023 11:54:12 +0100 Subject: [PATCH] feat: update docs --- docs/reference/site-config.md | 86 +------------------- package.json | 4 +- pnpm-lock.yaml | 18 ++--- src/node/markdown/markdown.ts | 106 +++++++++++++++++++++---- src/node/markdown/plugins/highlight.ts | 2 +- 5 files changed, 103 insertions(+), 113 deletions(-) diff --git a/docs/reference/site-config.md b/docs/reference/site-config.md index a5386f57..b5e124d2 100644 --- a/docs/reference/site-config.md +++ b/docs/reference/site-config.md @@ -462,91 +462,7 @@ export default { } ``` -Below are all the options that you can have in this object: - -```ts -interface MarkdownOptions extends MarkdownIt.Options { - // Custom theme for syntax highlighting. - // You can use an existing theme. - // See: https://github.com/shikijs/shiki/blob/main/docs/themes.md#all-themes - // Or add your own theme. - // See: https://github.com/shikijs/shiki/blob/main/docs/themes.md#loading-theme - theme?: - | Shikiji.BuiltInTheme - | Shikiji.ThemeRegistration - | { - light: Shikiji.BuiltInTheme | Shikiji.ThemeRegistration; - dark: Shikiji.BuiltInTheme | Shikiji.ThemeRegistration - } - - // Enable line numbers in code block. - lineNumbers?: boolean - - // Add support for your own languages. - // https://github.com/shikijs/shiki/blob/main/docs/languages.md#supporting-your-own-languages-with-shiki - languages?: (Shikiji.BuiltInLanguage | Shikiji.LanguageRegistration)[] - - // markdown-it-anchor plugin options. - // See: https://github.com/valeriangalliat/markdown-it-anchor#usage - anchor?: anchorPlugin.AnchorOptions - - // markdown-it-attrs plugin options. - // See: https://github.com/arve0/markdown-it-attrs - attrs?: { - leftDelimiter?: string - rightDelimiter?: string - allowedAttributes?: Array - disable?: boolean - } - - // specify default language for syntax highlighter - defaultHighlightLang?: string - - // @mdit-vue/plugin-frontmatter plugin options. - // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-frontmatter#options - frontmatter?: FrontmatterPluginOptions - - // @mdit-vue/plugin-headers plugin options. - // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers#options - headers?: HeadersPluginOptions | boolean - - // @mdit-vue/plugin-sfc plugin options. - // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-sfc#options - sfc?: SfcPluginOptions - - // @mdit-vue/plugin-toc plugin options. - // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options - toc?: TocPluginOptions - - // @mdit-vue/plugin-component plugin options. - // See: https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-component#options - component?: ComponentPluginOptions - - // Configure the Markdown-it instance. - config?: (md: MarkdownIt) => void - - // Same as `config` but will be applied before all other plugins. - preConfig?: (md: MarkdownIt) => void - - // Disable cache (experimental) - cache?: boolean - - // Math support (experimental) - // You need to install `markdown-it-mathjax3` and set `math` to `true` to enable it. - // You can also pass options to `markdown-it-mathjax3` here. - // See: https://github.com/tani/markdown-it-mathjax3#customization - math?: boolean | any - - // Global custom container titles - container?: { - infoLabel?: string - tipLabel?: string - warningLabel?: string - dangerLabel?: string - detailsLabel?: string - } -} -``` +Check the [type declaration and jsdocs](https://github.com/vuejs/vitepress/blob/main/src/node/markdown/markdown.ts) for all the options available. ### vite diff --git a/package.json b/package.json index c7944d06..c1d3f9c7 100644 --- a/package.json +++ b/package.json @@ -101,8 +101,8 @@ "mark.js": "8.11.1", "minisearch": "^6.2.0", "mrmime": "^1.0.1", - "shikiji": "^0.7.1", - "shikiji-transformers": "^0.7.1", + "shikiji": "^0.7.2", + "shikiji-transformers": "^0.7.2", "vite": "^5.0.0", "vue": "^3.3.8" }, diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 41ca14be..7593fd33 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -45,11 +45,11 @@ importers: specifier: ^1.0.1 version: 1.0.1 shikiji: - specifier: ^0.7.1 - version: 0.7.1 + specifier: ^0.7.2 + version: 0.7.2 shikiji-transformers: - specifier: ^0.7.1 - version: 0.7.1 + specifier: ^0.7.2 + version: 0.7.2 vite: specifier: ^5.0.0 version: 5.0.0(@types/node@20.9.1) @@ -4163,14 +4163,14 @@ packages: resolution: {integrity: sha512-6j1W9l1iAs/4xYBI1SYOVZyFcCis9b4KCLQ8fgAGG07QvzaRLVVRQvAy85yNmmZSjYjg4MWh4gNvlPujU/5LpA==} dev: true - /shikiji-transformers@0.7.1: - resolution: {integrity: sha512-Y4MsRl8s/rx6xnO3kckKC6j93YJepeGT8ye9Bnz6ecadrtqKXZbDeERLX9OgkEhKNwxLlvo9Yk9N59oNj/O0QQ==} + /shikiji-transformers@0.7.2: + resolution: {integrity: sha512-Nxg79GL++TvMjprCwhKzXWA4UFTP4fP3jZrkJAkUnSchqV20T2emyy/NgNhNjeX69JoUqTbB82rfVASj5Vec9Q==} dependencies: - shikiji: 0.7.1 + shikiji: 0.7.2 dev: false - /shikiji@0.7.1: - resolution: {integrity: sha512-w/zKRaYe6RhkksZily2WG7yzz/g6qJsqrJom9OVbhLd4pzONXbVNWOlNHYhpMJ1SRvRp7CWVbh3MXy34bLKV4g==} + /shikiji@0.7.2: + resolution: {integrity: sha512-gOaq7lqi3zSqGm+pMVxDD9NXA6myj5/7s7ZXgJcGdM5eHa49FrUPV46C5nl13rZnN3ZDjEmqF8ZPpNJjXeiBrQ==} dependencies: hast-util-to-html: 9.0.0 dev: false diff --git a/src/node/markdown/markdown.ts b/src/node/markdown/markdown.ts index c98ce46f..67c631a1 100644 --- a/src/node/markdown/markdown.ts +++ b/src/node/markdown/markdown.ts @@ -45,47 +45,121 @@ export type ThemeOptions = } export interface MarkdownOptions extends MarkdownIt.Options { - lineNumbers?: boolean + /* ==================== General Options ==================== */ + + /** + * Setup markdown-it instance before applying plugins + */ preConfig?: (md: MarkdownIt) => void + /** + * Setup markdown-it instance + */ config?: (md: MarkdownIt) => void + /** + * Disable cache (experimental) + */ + cache?: boolean + externalLinks?: Record + + /* ==================== Syntax Highlighting ==================== */ + + /** + * Custom theme for syntax highlighting. + * + * You can also pass an object with `light` and `dark` themes to support dual themes. + * + * @example { theme: 'github-dark' } + * @example { theme: { light: 'github-light', dark: 'github-dark' } } + * + * You can use an existing theme. + * @see https://github.com/antfu/shikiji/blob/main/docs/themes.md#all-themes + * Or add your own theme. + * @see https://github.com/antfu/shikiji/blob/main/docs/themes.md#load-custom-themes + */ + theme?: ThemeOptions + /** + * Languages for syntax highlighting. + * @see https://github.com/antfu/shikiji/blob/main/docs/languages.md#all-themes + */ + languages?: LanguageInput[] + /** + * Custom language aliases. + * + * @example { 'my-lang': 'js' } + * @see https://github.com/antfu/shikiji/tree/main#custom-language-aliases + */ + languageAlias?: Record + /** + * Show line numbers in code blocks + * @default false + */ + lineNumbers?: boolean + /** + * Fallback language when the specified language is not available. + */ + defaultHighlightLang?: string + /** + * Transformers applied to code blocks + * @see https://github.com/antfu/shikiji#hast-transformers + */ + codeTransformers?: ShikijiTransformer[] + + /* ==================== Markdown It Plugins ==================== */ + + /** + * Options for `markdown-it-anchor` + * @see https://github.com/valeriangalliat/markdown-it-anchor + */ anchor?: anchorPlugin.AnchorOptions + /** + * Options for `markdown-it-attrs` + * @see https://github.com/arve0/markdown-it-attrs + */ attrs?: { leftDelimiter?: string rightDelimiter?: string allowedAttributes?: Array disable?: boolean } - defaultHighlightLang?: string + /** + * Options for `@mdit-vue/plugin-frontmatter` + * @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-frontmatter + */ frontmatter?: FrontmatterPluginOptions + /** + * Options for `@mdit-vue/plugin-headers` + * @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-headers + */ headers?: HeadersPluginOptions | boolean + /** + * Options for `@mdit-vue/plugin-sfc` + * @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-sfc + */ sfc?: SfcPluginOptions - theme?: ThemeOptions - languages?: LanguageInput[] - languageAlias?: Record + /** + * Options for `@mdit-vue/plugin-toc` + * @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc + */ toc?: TocPluginOptions - externalLinks?: Record - cache?: boolean /** * Options for `@mdit-vue/plugin-component` * @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-component */ component?: ComponentPluginOptions - /** - * Enable math support by `markdown-it-mathjax3` - * @default false - * @see https://vitepress.dev/guide/markdown#math-equations - */ - math?: boolean | any /** * Options for `markdown-it-container` * @see https://github.com/markdown-it/markdown-it-container */ container?: ContainerOptions /** - * Transformers applied to code blocks - * @see https://github.com/antfu/shikiji#hast-transformers + * Math support (experimental) + * + * You need to install `markdown-it-mathjax3` and set `math` to `true` to enable it. + * You can also pass options to `markdown-it-mathjax3` here. + * @default false + * @see https://vitepress.dev/guide/markdown#math-equations */ - codeTransformers?: ShikijiTransformer[] + math?: boolean | any } export type MarkdownRenderer = MarkdownIt diff --git a/src/node/markdown/plugins/highlight.ts b/src/node/markdown/plugins/highlight.ts index ce3f83d0..da9524ab 100644 --- a/src/node/markdown/plugins/highlight.ts +++ b/src/node/markdown/plugins/highlight.ts @@ -67,7 +67,7 @@ export async function highlight( ? [theme] : [theme.light, theme.dark], langs: languages?.length ? languages : Object.keys(bundledLanguages), - langAlias: languageAlias, + langAlias: languageAlias }) const transformers: ShikijiTransformer[] = [