feat: update docs

2 years ago · 0dde083fc6
parent e8ca2de421
commit 0dde083fc6
5 changed files with 103 additions and 113 deletions
--- 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<string | RegExp>
-    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

--- 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"
  },
--- 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
--- 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<string, string>
+
+  /* ==================== 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<string, string>
+  /**
+   * 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<string | RegExp>
    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<string, string>
+  /**
+   * Options for `@mdit-vue/plugin-toc`
+   * @see https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc
+   */
  toc?: TocPluginOptions
-  externalLinks?: Record<string, string>
-  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
--- 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[] = [