What is VitePress?

VitePress is the younger brother of VuePress, but VitePress is built on top of Vite.

motivation

Mainly because it’s too slow! But don’t blame VuePress, blame Webpack!

Vite solves the problem perfectly:

1. Almost real-time service startup

2. Compile the page as needed

3. Very lightweight and fast HMR (hot module overload)

In addition, there was no time to fix some design problems of VuePress itself, so I just did a big reconstruction this time.

Areas for improvement

1. Take advantage of Vue 3’s improved template static analysis to string static content wherever possible

2. Static content is sent in string mode instead of rendering function code, JS load is cheaper and flooding (generating JS interactive logic code in SSR) is faster

3. These optimizations still allow you to mix Vue components in Markdown, and the compiler handles static/dynamic separation for you

4. Use Vite

5. Faster dev server startup

6. Faster hot updates

7. Faster builds (using Rollup)

Lighter pages

Vue 3 + Rollup code separation does not send metadata for all pages in one request. The client gets the components and metadata of the new page together as it navigates

Other differences

1.VitePress is more arbitrary and less configurable. VitePress aims to reduce the complexity of current VuePress and start again from its minimalist roots

2.VitePress is future-oriented: its target browser is a browser that only supports native ES module imports. It encourages the use of raw JavaScript without escaping and the use of CSS variables to theme

Will this be the next version of VuePress?

Probably not. To avoid impacting VuePress’s current theme and plug-in ecosystem, the core logic is fewer theme apis (favoring JavaScript apis over file layouts) and no plug-ins (all customizations are within themes).

start

1. Initialize the directory and index.md

take vitepress-starter
yarn init
yarn add --dev vitepress
mkdir && echo '# Hello VitePress' > docs/index.md
Copy the code

2. Add these scripts to package.json

{
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }
}
Copy the code

3. Start the service locally

yarn docs:dev
Copy the code

configuration

Without configuration, the page is simple and the user cannot navigate. To set up the configuration, create the.vitepress directory under the docs directory

.├ ─ ├─ download.txt ├─ download.txt ├─ download.txtCopy the code

.vitepress/config.js is the necessary file to configure the Vitepress site, which exports a JavaScript object:

module.exports = {
  title: 'Hello VitePress',
  description: 'Just playing around.'
}
Copy the code

Resource file processing

Resource files can be pointed to by relative urls:

! [An image](./image.png)Copy the code

All referenced resource files will be copied to the dist directory during production packaging and the file name will be hashed. Unreferenced resource files will not be copied. Image resources less than 4KB will be base64

Open the file

The public directory is a special directory

The file names in this directory will not be renamed. Hash references to resources in this directory need to be directly referenced using the root path, such as public/icon. PNG files need to be referenced via /icon.png

Based on the URL

Resolve the situation where your site is not deployed in the root directory.

Take domain.com/sub-path/ for example:

Set the base parameter of.vitepress/config.js to /sub-path/ (note that it must start and end with /). If you want to reference public images, use $withBase (injected into the Vue prototype). This can be used in both theme components and Markdown files

<img :src="$withBase('/foo.png')" alt="foo">
Copy the code

Markdown extension

The title of anchor point

The title automatically generates anchor points

Anchor rendering can be set with the Markdown. anchor option

link

Internal links

The index.md in each subdirectory is automatically converted to index. HTML, and the access path is /

Here’s an example:

. ├ ─ index. The md ├ ─ foo │ ├ ─ index. The md │ ├ ─ one. The md │ └ ─ two md └ ─ bar ├ ─ index. The md ├ ─ three. The md └ ─ four. The mdCopy the code

Suppose you are currently at foo/one.md

[Home](/) <! Readme.md --> [foo](/foo/) <! HTML --> [foo heading](./#heading) <! -- point to a title in the README file in the foo directory --> [bar-three](.. /bar/three) <! --> [bar-three](... /bar/three.md) <! Md --> [bar-four](.. /bar/four.html) <! -- or add.html -->Copy the code

Page suffix

Pages and internal links are automatically suffixed with.html by default.

External links

Target =”_blank” rel=”noopener noreferrer”:

vuejs.org
VitePress on GitHub
Copy the code

Frontmatter

Support YAML frontmatter

title: Blogging Like a Hacker lang: en-US

GitHub- Style sheet

The input

Tables Are Cool
col 3 is right-aligned The $1600
col 2 is centered $12
zebra stripes are neat The $1

The output

Tables Are Cool col 3 is right-aligned 1600 col2iscentered1600\ col 2 is centered 1600 col2iscentered12 zebra stripes Are neat $1 #



Output 🎉 💯

Table of contents

[[toc]]

Custom container

::: tip

This is a tip

:::

This is a warning

This is a dangerous warning

Custom title

Danger zone, do not proceed

Syntax highlighting within code blocks

VitePress uses the Prism library for syntax highlighting, plus language identifiers, a list of supported languages

Line highlighting within a code block

export default { data () { return { msg: 'Highlighted! '}}}Copy the code

Instead of just single-line highlighting, you can do this:

Scope: {5-8}, {3-10}, {10 to 17} multi-line:,7,9 {4} line range and multi-line hybrid: 13,16,23-27, 40} {4, 7 –

According to the line Numbers

module.exports = {
  markdown: {
    lineNumbers: true
  }
}
Copy the code

Advanced configuration

VitePress uses Markdown-it as the Markdown renderer. This can be customized by using the markdown option in.vitepress/config.js:

module.exports = {
  markdown: {
    // options for markdown-it-anchor
    anchor: { permalink: false },

    // options for markdown-it-toc
    toc: { includeLevel: [1, 2] },

    config: (md) => {
      // use more markdown-it plugins!
      md.use(require('markdown-it-xxx'))
    }
  }
}
Copy the code

The deployment of

The following contents have these common agreements:

Vitepress is installed as a local dependency in your project, and the following script has been added

{
  "scripts": {
    "docs:build": "vitepress build docs",
    "docs:serve": "vitepress serve docs"
  }
}
Copy the code

Build the document

Yarn docs:build # Build and store the results to '. Vitepress /dist 'YARN docs:serve # preview the results of the previous build, that is, start a static file serviceCopy the code

You can also change the static file service port

{
  "scripts": {
    "docs:serve": "vitepress serve docs --port 8080"
  }
}
Copy the code