preface

Hi, I’m Ah Jiang. I wrote an article yesterday about how to build a scaffold from scratch. At that time, I left a knowledge point on the official website. In fact, because the documents on the official website are too brief, each item needs to be configured separately by Google. Therefore, today I will single out an article to talk about the common configuration items I use and try to explain the functions of each step in detail.

start

Since we have reference vite template source code for the construction of scaffolding, then we will give priority to vitePress for the official website of the document we build this time. After all, we can’t just eat steamed bread without eating vegetables.

Let me first explain that the official website I built is based on the project structure of the last article, so the screenshot will appear before the structure, please don’t be offended. This article builds the latest version of “VitePress “: “^0.20.9”.

VitePress is why

Vitepress is used to quickly build static web projects. Generally used for the development of more documents, can also be customized theme development official website, blog and other projects.

And based on. Md file generated HTML support makedown text development, and support vUE components use development, enjoy vite hot update.

How to use vitePress

Yarn download

yarn add --dev vitepress
Copy the code

NPM download

npm i vitepress --save
Copy the code

Create a folder for your pages like docs, or website for your website. This is equivalent to creating a folder in the root directory of the project. Then create an index.md file in the outermost layer or use this command

 mkdir docs && echo '# Hello VitePress' > docs/index.md
Copy the code

This is the outermost initialization page and the first page.

Add a command

Add the following instructions to package.json in the root path

"docs:dev": "vitepress dev docs".// Start command
"docs:build": "vitepress build docs".// Package instruction
"docs:serve": "vitepress serve docs"// Test run the packaged file directive
Copy the code

Note that docs is based on the name of the folder you created. If your name is website the command should be: “website:dev”: “vitepress dev website”

Start the project

Yarn to start

yarn docs:dev
Copy the code

NPM start

npm run docs:dev
Copy the code

Open http://localhost:3000/ and you will see the following page

Set the configuration

Create a.vitepress folder under the docs folder you just created, and internally create a config.js for configuring all the configuration items in VitePress.

The directory level is as follows:

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

Alternatively, execute the following create command directly from the package.json root directory

cd docs && mkdir .vitepress && cd .vitepress && touch config.js
Copy the code

Go to the docs directory -> create. Vitepress folder -> go to. Vitepress folder -> create config.js

module.exports = {
    base:'/vue3-vite-cli/'.title: 'Vue3-Vite-Cli Chinese documentation '.// The description of the home page
    description: 'Vite based style scaffolding, provide a variety of templates for more efficient solutions to business needs! '.lang: 'zh-CN'.head: [['link', { rel: 'icon'.type: 'image/svg+xml'.href: 'logo.jpeg'}}]],Copy the code

parameter

The following parameters include those not written in the vitePress document, which are generally my own experience and understanding after use. Please point out if there is any mistake!

base

base:'/vue3-vite-cli/'.Copy the code

The base URL of the site will be deployed in. You’ll need to set this up if you plan to deploy your site under a subpath, such as the GitHub page. If you plan to deploy your site to foo.github. IO /bar/, then you should set the base to /bar/. It should always start and end with a slash

title

title: 'Vue3-Vite-Cli Chinese documentation '.Copy the code

The title of the site. This will be the suffix for all page titles and will appear in the navigation bar.

description

description: 'Vite based style scaffolding, provide a variety of templates for more efficient solutions to business needs! '.Copy the code

The description of the site is displayed by default in index.md(home page)

lang

lang: 'zh-CN'.Copy the code

The lang property of the site. This will render as a tag in the HTML page.

head

head: [['link', { rel: 'icon'.type: 'image/svg+xml'.href: 'logo.jpeg' }]],
Copy the code

The site’s head property. Array types, mainly two-dimensional arrays, are not affected by compilation.

// Compile and introduce the index.html effect
<link rel="icon" type="image/svg+xml" href="logo.jpeg">
Copy the code

The logo setting here requires the creation of a public folder in the Docs hierarchy to hold static resources

themeConfig

themeConfig:{
    repo: 'wushijiang13/vue3-vite-cli'.repoLabel:'GitHub'.docsDir: 'docs'.docsBranch: 'master'.editLinks: true.editLinkText: 'Help us improve the page! '.lastUpdated: 'Last Updated'.nav: [{text: 'entry'.link: '/getting/why.html' },
        { text: 'yards cloud'.link: 'https://gitee.com/wushijiang13/vue3-vite-cli'},].sidebar: {
        '/': [{text: 'entry'.children: [{text: 'introduction'.link: '/getting/why.html'
                    },
                    {
                        text: 'Introduction to Formwork Scaffolding'.link: '/getting/template_introduction.html'}]}}Copy the code

The site subject configuration object, configurable navigation bar, side function bar, bottom help bar, routing address and so on.

repo

repo: 'wushijiang13/vue3-vite-cli'.Copy the code

The GitHub user name /GitHub project name corresponding to the document project is used to configure the GitHub jump in the navigation bar, and is also used to configure the bottom navigation in all pages to help us edit GitHub to modify the jump function

repoLabel

repoLabel:'GitHub'.Copy the code

Used to configure the name of the GitHub link in the navigation bar. The default is GitHub.

docsDir

docsDir: 'docs'.Copy the code

The name of the folder in which documents are placed in the project

docsBranch

docsBranch: 'master'.Copy the code

The GitHub repository branch of the project is also used to configure the bottom navigation on all pages to help us edit the GitHub change jump feature

editLinks

editLinks: true.Copy the code

The global display in the control project helps us edit GitHub to change the jump function, and can also be controlled by setting editLink: True in the head of each MD file.

editLinkText

editLinkText: 'Help us improve the page! '.Copy the code

The default copy that helps us modify is Edit this page.

lastUpdated

lastUpdated: 'Last Updated'.Copy the code

The lower right corner shows the latest update time copy and controls the display.

nav

nav: [
    { text: 'entry'.link: '/getting/why.html' },
    { text: 'yards cloud'.link: 'https://gitee.com/wushijiang13/vue3-vite-cli'},].Copy the code

In the navigation bar of this website, text is the title and link is the address. Local relative path or link can be filled in

sidebar

sidebar: {
    '/': [{text: 'entry'.children: [{text: 'introduction'.link: '/getting/why.html'
                },
                {
                    text: 'Introduction to Formwork Scaffolding'.link: '/getting/template_introduction.html'}]}]}Copy the code

The site side navigation bar option, ‘/’ represents the default match path, if no other match is set default all pages according to ‘/’ match under the side navigation bar display. Text stands for title and children stands for subset.

Complete configuration

module.exports = {
    base:'/vue3-vite-cli/'.title: 'Vue3-Vite-Cli Chinese documentation '.description: 'Vite based style scaffolding, provide a variety of templates for more efficient solutions to business needs! '.lang: 'zh-CN'.head: [['link', { rel: 'icon'.type: 'image/svg+xml'.href: 'logo.jpeg' }]],
    themeConfig: {repo: 'wushijiang13/vue3-vite-cli'.repoLabel:'test'.docsDir: 'docs'.docsBranch: 'master'.editLinks: true.editLinkText: 'Help us improve the page! '.lastUpdated: 'Last Updated'.nav: [{text: 'entry'.link: '/getting/why.html' },
            { text: 'template'.link: '/template/template-vue3-ts-initial.html' },
            { text: 'Related Documents'.link: '/documentation/vue.html' },
            { text: 'yards cloud'.link: 'https://gitee.com/wushijiang13/vue3-vite-cli'},].sidebar: {
            '/': [{text: 'entry'.children: [{text: 'introduction'.link: '/getting/why.html'
                        },
                        {
                            text: 'Introduction to Formwork Scaffolding'.link: '/getting/template_introduction.html'}]}, {text: 'Template internal structure parsing'.children: [{text: 'vue3-ts-initial'.link: '/template/template-vue3-ts-initial.html'
                        },
                        {
                            text: 'webpack-protist-js'.link: '/template/template-webpack-protist-js.html'}]}, {text: 'Related Documents'.children: [{text: 'Vue related Documents'.link: '/documentation/vue.html'
                        },
                        {
                            text: 'Webpack related Documents'.link: '/documentation/webpack.html'}]}}}Copy the code

The above is my commonly used configuration items, I hope to help you.

The index.md header is configured

HeroImage: /logo.jpeg // Big picture logo address actionText: Getting started // Left button actionLink: /getting/why.html // redirect address altActionText: template document // right button altActionLink: / template/template - vue3 - ts - initial. HTML/footer/right address: MIT Licensed | Copyright © 2019 - present Wu Xiansen - product / / at the bottom of the descriptionCopy the code

The renderings are as follows

The deployment of test

Remember those two commands? Is used to package and test packaged service tests

"docs:build": "vitepress build docs"."docs:serve": "vitepress serve docs"
Copy the code

Note that if you need to run docs:serve to test whether the package is available, be sure to comment out the base:’/vue3-vite-cli/’ address, otherwise it will cause an exception. If not set, do not need to modify, the final test completed to restore annotations.

Since I am deploying to my own cloud server, I have added.html to all of the paths mentioned above, which you would not need to set if you were just deploying to Github.

The Github Page deployment scheme is included

conclusion

The above is the author vitePress scaffolding official website all the content, in fact, this section of the experience of building documents is also counted as stepping on a lot of pits, the main document is not complete, resulting in the configuration of the need to check left and right. Here I put the author out. Offer to the person that is using him, author still quite happy. Finally, I leave the author’s achievement address here, I hope friends can dot star to support the author. I will bring you a better article later! Work together and progress together, I am Jiang!