VuePress Theme QuickSand

The document is only used for theme display, please go to the official site for the latest Vuepress documentation

Config

@vuepress/cli@vuepress/core

Reference of VuePress config, which can be set via config file. The conventional config files are (in order of precedence):

  • In current working directory cwd:
    • vuepress.config.ts
    • vuepress.config.js
  • In source directory sourceDir:
    • .vuepress/config.ts
    • .vuepress/config.js

You can also specify the config file via --config option of CLI.

Site Config

base

  • Type: string

  • Default: /

  • Details:

    The base URL the site will be deployed at.

    You will need to set this if you plan to deploy your site under a sub path. It should always start and end with a slash. For example, if you plan to deploy your site to GitHub pages at https://foo.github.io/bar/, then you should set base to "/bar/".

    The base is automatically prepended to all the URLs that start with / in other options, so you only need to specify it once.

  • Also see:

lang

  • Type: string

  • Default: en-US

  • Details:

    Language for the site.

    This will be the lang attribute of the <html> tag in the rendered HTML.

    This can be specified in different locales.

  • Also see:

title

  • Type: string

  • Default: ''

  • Details:

    Title for the site.

    This will be the suffix for all page titles, and displayed in the navbar in the default theme.

    This can be specified in different locales.

  • Also see:

description

  • Type: string

  • Default: ''

  • Details:

    Description for the site.

    This will be the content attribute of <meta name="description" /> tag in the rendered HTML, which will be overrode by the description field of page frontmatter.

    This can be specified in different locales.

  • Also see:

  • Type: HeadConfig[]

  • Default: []

  • Details:

    Extra tags to inject into the <head> tag in the rendered HTML.

    You can specify each tag in the form of [tagName, { attrName: attrValue }, innerHTML?].

    This can be specified in different locales.

  • Example:

    To add a custom favicon:

module.exports = {
  head: [['link', { rel: 'icon', href: '/images/logo.png' }]],
}
1
2
3

Rendered as：

<head>
  <link rel="icon" href="/images/logo.png" />
</head>
1
2
3

locales

Theme Config

theme

  • Type: string

  • Default: '@vuepress/default'

  • Details:

    Name or absolute path of theme your want to use.

    This option accepts theme name, theme name shorthand, or absolute path to theme.

  • Example:

module.exports = {
  theme: 'vuepress-theme-quicksand',
  // or
  theme: 'quicksand',
}
1
2
3
4
5

themeConfig

  • Type: ThemeConfig

  • Default: {}

  • Details:

    Provide config options to the used theme. The options will vary depending on the theme you are using.

  • Also see:

Bundler Config

bundler

  • Type: string

  • Default: '@vuepress/webpack'

  • Details:

    Name of bundler your want to use.

    Bundler name shorthand is acceptable.

  • Also see:

bundlerConfig

Directory Config

dest

  • Type: string

  • Default: `${sourceDir}/.vuepress/dist`

  • Details:

    Specify the output directory for vuepress build command.

temp

  • Type: string

  • Default: `${sourceDir}/.vuepress/.temp`

  • Details:

    Specify the directory for temporary files.

cache

  • Type: string

  • Default: `${sourceDir}/.vuepress/.cache`

  • Details:

    Specify the directory for cache .

public

Markdown Config

markdown

markdown.anchor

markdown.assets

  • Type: AssetsPluginOptions | false

  • Details:

    Options for VuePress built-in markdown-it assets plugin.

    Set to false to disable this plugin.

DANGER

You should not configure it unless you understand what it is for.

markdown.code

markdown.code.highlightLines

markdown.code.lineNumbers

markdown.code.preWrapper

  • Type: boolean

  • Default: true

  • Details:

    Enable the extra wrapper of the <pre> tag or not.

    The wrapper is required by the highlightLines and lineNumbers. That means, if you disable preWrapper, the line highlighting and line numbers will also be disabled.

TIP

You can disable it if you want to implement them in client side. For example, Prismjs Line Highlightopen in new window or Prismjs Line Numbersopen in new window.

markdown.code.vPre

markdown.customComponent

  • Type: undefined | false

  • Details:

    Options for VuePress built-in markdown-it custom-component plugin.

    Set to false to disable this plugin.

DANGER

You should not configure it unless you understand what it is for.

markdown.emoji

markdown.extractHeaders

  • Type: ExtractHeadersPluginOptions | false

  • Details:

    Options for VuePress built-in markdown-it extract-headers plugin.

    It will extract page headers to page data, which would be used for generating sidebar, table of contents, etc. For example, the sidebar of current page is auto generated from the headers that extracted by this plugin.

    Set to false to disable this plugin.

markdown.extractTitle

  • Type: undefined | false

  • Details:

    Options for VuePress built-in markdown-it extract-title plugin.

    It will extract title to page data, which will be used as the page title.

    Set to false to disable this plugin.

DANGER

You should not configure it unless you understand what it is for.

markdown.hoistTags

  • Type: HoistTagsPluginOptions | false

  • Details:

    Options for VuePress built-in markdown-it hoist-tags plugin.

    It will hoist specific HTML tags in your Markdown to the top-level of SFC. By default, only <script> and <style> tags will be hoisted. You can set this option to support SFC custom blocks in Markdown.

    Set to false to disable this plugin.

  • Also see:

markdown.importCode

markdown.importCode.handleImportPath

  • Type: (str: string) => string

  • Default: (str) => str

  • Details:

    A function to handle the import path of the import code syntax.

  • Type: LinksPluginOptions | false

  • Details:

    Options for VuePress built-in markdown-it links plugin.

    It will convert internal links to <RouterLink>, and add extra attributes and icon to external links.

    Set to false to disable this plugin.

  • Also see:

  • Type: 'a' | 'RouterLink'

  • Default: 'RouterLink'

  • Details:

    Tag for internal links.

    By default, this plugin will transform internal links to <RouterLink>. You can set this option to 'a' to disable this feature.

  • Type: Record<string, string>

  • Default: { target: '_blank', rel: 'noopener noreferrer' }

  • Details:

    Additional attributes for external links.

  • Type: boolean

  • Default: true

  • Details:

    Whether to append an open in new window icon to external links.

    You can override this global option via externalIcon frontmatter in your pages.

markdown.toc

Development Config

debug

  • Type: boolean

  • Default: false

  • Details:

    Enable debug mode or not.

    This would be helpful for developers. Also, we are using debugopen in new window package for debug logging, which can be enabled via DEBUG=vuepress* environment variable.

host

  • Type: string

  • Default: '0.0.0.0'

  • Details:

    Specify the host to use for the dev server.

port

  • Type: number

  • Default: 8080

  • Details:

    Specify the port to use for the dev server.

open

  • Type: boolean

  • Default: false

  • Details:

    Whether to open the browser after dev-server had been started.

pagePatterns

  • Type: string[]

  • Default: ['**/*.md', '!.vuepress', '!node_modules']

  • Details:

    Specify the patterns of files you want to be resolved as pages. The patterns are relative to the source directory.

templateDev

  • Type: string

  • Default: '@vuepress/client/templates/index.dev.html'

  • Details:

    Specify the HTML template to be used for dev.

templateSSR

  • Type: string

  • Default: '@vuepress/client/templates/index.ssr.html'

  • Details:

    Specify the HTML template to be used for build (SSR).

shouldPreload

  • Type: ((file: string, type: string) => boolean)) | boolean

  • Default: true

  • Details:

    A function to control what files should have <link rel="preload"> resource hints generated. Set to true or false to enable or disable totally.

    By default, only those files that are required by current page will be preloaded. So you can keep it true in most cases.

shouldPrefetch

  • Type: ((file: string, type: string) => boolean)) | boolean

  • Default: false

  • Details:

    A function to control what files should have <link rel="prefetch"> resource hints generated. Set to true or false to enable or disable for all files.

    If you set it to true, all files that required by other pages will be prefetched. This is good for small sites, which will speed up the navigation, but it might not be a good idea if you have lots of pages in your site.

Plugin Config

plugins

  • Type: PluginConfig[]

  • Details:

    Plugins to use.

    This option accepts an array, each item of which is a two-element tuple:

    • The first element is the plugin name or the plugin itself. It accepts plugin name, plugin name shorthand, absolute path to plugin, or the plugin object.
    • The second element is the plugin options. It accepts boolean or object. Set it to false to skip the plugin. Set it to true to enable the plugin without any options. Use object to enable the plugin with options.

    For simplicity, you can use the first element of the tuple that described above as the array item, which equals enabling the plugin without any options.

  • Example:

module.exports = {
  plugins: [
    // two-element tuple
    ['vuepress-plugin-foo', false],
    ['bar', true],
    [path.resolve(__dirname, './path/to/local/plugin'), { /* options */ }],
    [require('vuepress-plugin-baz'), true],

    // only use the first element
    'foobar', // equals to ['foobar', true]
  ],
}
1
2
3
4
5
6
7
8
9
10
11
12

Plugin API

User config file also works as a VuePress plugin, so all of the Plugin APIs are available except the name and multiple options.

Please check out Plugin API Reference for a full list of Plugin APIs.