Small knowledge, big challenge! This article is participating in the creation activity of “Essential Tips for Programmers”.

preface

VuePress is a project written by THE University of Utah to support the documentation requirements of Vue and its subprojects. The interface is simple and easy to use, with the architecture of a project being put together in an hour. There are a lot of these types of documents out there, and if you have a need to write technical documentation for a project, VuePress can definitely be one of your options.

VuePress features:

  • Built-in Markdown extensions optimized for technical documentation
  • The ability to use Vue components in Markdown files
  • Vue driven custom theme system
  • Automatically generate Service workers
  • Google Analytics integration
  • Git-based “Last Updated Time”
  • Multilingual support
  • The default topics include:

It is recommended to read the official document 1.x first

Environment to prepare

Windows

  1. Install cmder and use the tutorial

After the decompression is complete, copy its path address and add it to the environment variable. Use Win + R to quickly start cmDER. If successful, add environment variables successfully. 2. Go to next to install the Git installation package. Right-click git bash here on the desktop or enter git –version in the command line. 3. Install the NodeJS installation package in the same way as next. On the cli, enter node -v. 4. Install YARN. After the installation is complete, enter YARN –version on the CLI. 5. Create projects

  • Creating projects can take two forms:
    • Remote warehouse 
      Git clone XXX CD your_project_name NPM init -yCopy the code
    • Local repository 
      NPM init your_project_name -y CD your_project_name git remote add origin XXXCopy the code
  1. Install vuepress
# NPM install -g vuepress@next # NPM install yarn add -d vuepress@next # npm install -D vuepress@nextCopy the code
  1. configurationpackage.jsonThe script

If your document is not under Docs, follow your Settings:

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

After the above configuration, you can test:

Or: NPM run docs:devCopy the code

If the browser can be accessed, the installation is successful.

Setup and Optimization

1. Configure routes and navigation

On how the file is rendered to the corresponding route:

The relative path of the file Page routing address
/README.md /
/guide/README.md /guide/
/config.md /config.html
  • Now that you understand this basic concept, you can configure the navigation. For details on the navigation bar configuration, see the official documentation
  • After practice found that if all content placed indocs/.vuepress/config.jsYou are advised to create a new directory in the root directoryconfigFolders:
// docs/.vuepress/config.js const navConf = require('.. /.. /config/navConf.js'); module.exports = { themeConfig: { nav: navConf }, }Copy the code
  • Here’s an example:
module.exports = [ { text: 'Home', link: '/' }, { text: 'Guide', link: '/guide/' }, { text: 'External', link: 'https://google.com' }, { text: 'Languages', items: [ { text: 'Chinese', link: '/language/chinese/' }, { text: 'Japanese', link: '/language/ Japanese /'}]}, {text: 'about ', items: [{text:' about me ', items: [{text: 'about me ', items: [{text:' about me ', items: [{text: 'about me ', items: [{text:' about me ', link: '/about/ curriculums /'},]}, {text: 'curriculums ', items: [{text:' CurriculumVitae ', link: '/about/CurriculumVitae ']}]}]Copy the code

2. Configure the sidebar

  • The sidebar is a little more cumbersome than the navigation bar. For details on the navigation bar configuration, see the official documentation.
  • Start by creating a new directory and file under the Docs folder:
├─ "CurriculumVitae" ├── "school exercises" ─ "School exercises" ─ "School exercises" ─ "School exercises" ─ "School exercises" ─ "School exercises" ─ "School exercises" ─ "School exercises" ─ "School exercises Self1. Md └ ─ ─ the README. MdCopy the code
  • configurationconfigFiles, when many articles are concentrated in config files, will explode:
// docs/.vuepress/config.js const sidebarConf = require('.. /.. /config/sidebarConf/index.js'); module.exports = { themeConfig: { sidebar: sidebarConf }, }Copy the code
  • Articles need to be sorted, so they are divided into more sub-files, managed through index.js:
# config/sidebarConf sidebarConf ├ ─ ─ the about │ ├ ─ ─ algorithm │ │ └ ─ ─ index. The js │ ├ ─ ─ the clean │ │ └ ─ ─ index. The js │ ├ ─ ─ git │ │ ├ ─ sci-imp ─ sci-imp ─ sci-imp ─ sci-impCopy the code
// config/sidebarConf/index.js

const CurriculumVitae = require('./about/CurriculumVitae/index');
const SelfIntroduction = require('./about/SelfIntroduction/index');

module.exports = {
    '/about/CurriculumVitae/': CurriculumVitae,
    '/about/SelfIntroduction/': SelfIntroduction,
   // Sidebar in the root directory. This sidebar will be applied to all unmatched objects
  // '/': [''] // Select disable
};

// config/sidebarConf/about/CurriculumVitae/index.js
const utils = require('.. /.. /.. /.. /utils/index');
const children = [' '.'viate1'.'viate2'.'viate3']
module.exports =[
    utils.genSidebar(Resume, children, false)];/ / genSidebar function:
// utils/index.js
const utils = {
  // Generate a sidebar
  genSidebar: function(title, children = [' '], collapsable = true, sidebarDepth = 1) {
    return {
      title,   / / necessary
      children,
      collapsable, // Optional, default is true,
      sidebarDepth,    // The default value is 1}}};module.exports = utils;
Copy the code

3. SEO configuration

  • Basic configuration can help us do a good job of SEO website, easier to be searched. For details about basic configuration, see the official documents
// docs/.vuepress/config.js
module.exports = {
  title: 'Fish flying over mountains and oceans'.description: 'Documents of fish flying over mountains and oceans, Vuepress documents',}Copy the code

4. Update time and static resources

  • Update time, if the time format is not Chinese style according to the document configuration, the solution is very simple:
// Add multiple languages
module.exports = {
  locales: {
    '/': {
      lang: 'zh-CN',}},themeConfig: {
    lastUpdated: 'Last update',}}Copy the code
  • All static resources need to be placed in the.vuepress/public directory, you can also create folder categories for them (the bad effect here is that you can’t see images when previewing local Markdown files) :
Public ├── ├─ ├─ ├─ ├─ favicon-2.png public ├── ├─ ├─ ├─ favicon-2.png ├── ├─ ├─ ├─ ├─ ├── favicon manifest.jsonCopy the code

5. Deploy to Github and associate it with the custom domain name

GithuPage: https://

.github. IO /yufanBlog/, so you need to configure the base attribute of the file and specify the yufanBlog repository

# .vurpress/config.js 
base: "/yufanBlog/".Copy the code
#! /usr/bin/env sh

Make sure the script throws any errors it encounters
set -e

Generate static files
npm run docs:build

Go to the generated folder
cd docs/.vuepress/dist

# if publish to custom domain name
# echo 'www.example.com' > CNAME

git init
git add -A
git commit -m 'deploy'

Github. IO /
      
git push -f [email protected]:shanyuhai123/documents.git master:gh-pages

cd -

Copy the code

6. Add Git repository and edit link

Reference documents as above:

// docs/.vuepress/config.js

module.exports = {
  themeConfig: {
    // Your Git project address will be appended at the end of the navigation bar
    repo: 'shanyuhai123/documents'.// Enable editing
    editLinks: true.// Edit the Text of the button
    editLinkText: 'Edit the document! '.// Edit the directory where the document resides
    docsDir: 'docs'.// If the document is placed under a specific branch:
    // docsBranch: 'master',}},Copy the code

7. Domain name resolution

For details on domain name resolution, see the video (the fifth video has a problem with resolution). The parse mode needs to be changed to the form of CNAME: