Vuepress Introductory Notes

background

Every company has a component library or a variety of front-end tools, and having a good technical document for using these tools is a good choice. Like ele. me UI component library, VUE documents, etc., they are clear, concise and generous, which can save more learning costs for team members. From this, You dada invented a magical baby —–vuepress

As we all know, programmers pay a lot of attention to md syntax when writing documents, and more and more tools give md syntax to create more useful tools. In the case of nuggets, nuggets documentation is also written using md syntax. This article does not cover md syntax, which can be learned from markdown via this link.

Vuepress introduction

VuePress consists of two parts: the first part is a minimalist static web site generator that includes a VUUe-driven theme system and plug-in API, and the other part is a default theme optimized for writing technical documentation, which was originally created to support the documentation needs of Vue and its subprojects.

Every page generated by VuePress comes with pre-rendered HTML, which is good for loading performance and search engine optimization (SEO). Meanwhile, once the page is loaded, Vue takes over the static content and turns it into a full single-page application (SPA), while other pages load on demand only as the user navigates through them

In fact, a VuePress website is a one-page application powered by Vue, Vue Router, and WebPack. If you have used Vue before, you will have a very familiar development experience when developing a custom theme, and you can even use Vue DevTools to debug your custom theme

Vuepress uses md syntax to write documents, but you can also use VUE syntax in MD files, such as adding HTML tags, leaving empty lines to display, adding script tags for JS logic, adding style tags for CSS styles

Create vuepress

Install VuePress globally

yarn globalNPM install -g vuepressCopy the code

New Folder

You can manually right-click to create a new folder, or use the following command to create a new folder:

mkdir project
Copy the code

Project initialization

Go to the project folder and initialize the project using the command line:

Yarn init -y # or NPM init -yCopy the code

A package.json file will be created that looks like this:

{
  "name": "project"."version": "1.0.0"."description": ""."main": "index.js"."scripts": {
    "test": "echo "Error: no test specified" && exit 1"
  },
  "keywords": []."author": ""."license": "ISC"
}
Copy the code

Create a new docs folder under the root of project:

This document will be used as the root of the project document:

mkdir docs
Copy the code

Create it in the docs folder`.vuepress`Folders:

mkdir .vuepress
Copy the code

All vuepress-related files will be placed here

in`.vuepress`Create it under folder`config.js`:

touch config.js
Copy the code

Config.js is the necessary configuration file for VuePress, which exports a javascript object.

You can add the following configuration first:

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

in`.vuepress`Create public folder under folder:

mkdir public
Copy the code

Vuepress /dist/ this folder is used to store static resources, which when packaged will be placed in the root directory of.vuepress/dist/.

Home page (like VuePress document home page)

Create a readme.md under the docs folder:

The default theme provides a home page. Just set home: True as shown below. Put the following Settings into readme. md and you will see the same home page as VuePress.

---
home: true
heroImage: /logo.jpg
actionText: Quick start →actionLink: /zh/guiDe/features: - title: Simplicity is Paramountdetails: Markdown-centric project structure that helps you focus on writing with minimal configuration. - title: indicates the Vue driverdetails: Enjoy the development experience of Vue + Webpack, use Vue components in Markdown and develop custom themes using Vue. - title: high performancedetailsVuePress pre-renders static HTML for each page and runs as a SPA when the page is loaded.footer: MIT Licensed | Copyright © 2018-present Evan You
---
Copy the code

Ps: You need to put an image in the public folder.

Our project structure has been set up:

│ ├─ ├─ public │ ├─ customs.txt ├─ customs.txt ├─ customs.txtCopy the code

in`package.json`Add two startup commands to:

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

Start your VuePress:

The default is port localhost:8080.

Or: NPM run docs:devCopy the code

Construction:

Build generates static HTML files in the.vuepress/dist folder by default

Yarn docs:build # or NPM run docs:buildCopy the code

Basic configuration:

The most standard, of course, is the official documentation, which allows you to configure config.js for your own needs.

You can refer to the following configuration:

module.exports = {
  title: 'Site title'.description: 'Site Description'.// The tag injected into the HTML  of the current page
  head: [['link', { rel: 'icon'.href: '/favicon.ico'}].// Add a custom d favicon].base: '/web_accumulate/'.// This is the configuration associated with deploying to Github, which will be covered below
  markdown: {
    lineNumbers: true // The code block displays the line number
  },
  themeConfig: {
    sidebarDepth: 2.// e'b will extract both h2 and H3 headers from Markdown and display them in the sidebar.
    lastUpdated: 'Last Updated' // Document update time: the last time git committed each file}};Copy the code

Navigation bar configuration:

module.exports = {
  themeConfig: {
    nav:[
      { text: 'Front-end algorithm'.link: '/algorithm/' }, // Internal links are rooted in docs
      { text: 'blog'.link: 'http://obkoro1.com/' }, // External links
      // Drop down list
      {
        text: 'GitHub'.items: [{text: 'making address'.link: 'https://github.com/OBKoro1' },
          {
            text: 'Algorithm Warehouse'.link: 'https://github.com/OBKoro1/Brush_algorithm'}]}}Copy the code

Sidebar configuration:

module.exports = {
  themeConfig: {
      sidebar: {// accumulate the location of the md file in the accumulate folder.
        '/accumulate/': [
            '/accumulate/'.// accumulate the readme. md folder is not in a drop - down form
            {
              title: 'Title 1 of the sidebar dropdown'.children: [
                '/accumulate/JS/test'.// use docs as the root directory to find files
                Accumulate >JS>test.md
                // Auto-add.md The title of each suboption is the first H1 / H2 / H3 title in the MD file]}],// Algorithm folder under the docs folder. This is the second sidebar
          '/algorithm/': [
            '/algorithm/', 
            {
              title: 'Title 1 of the second sidebar dropdown'.children: [
                '/algorithm/simple/test']}]}}Copy the code

Of course, you can also search and download the configuration of a certain god from Github. Here is a simple and basic configuration introduction

Install the latest version of VuePress, which is based on the basic framework of VUe3. Of course, you can use the syntax of VUe2 as well as vue3

FAQ

Need to use other vue plugins when writing your own documentation, use the lower version of vuepress to create enhanchapp.js file to configure and import the global application configuration, no effect?

The way to import other third-party plug-ins in the latest version of Vuepress is different from that in the earlier version of Vuepress. This can be done by configuring an API in the config file —–clientAppEnhanceFiles. The clientappenhance. ts file is created at the same level as the config configuration file. In this file, you can configure some global application configurations, such as setting vUE global properties or importing vue plug-ins

//// clientAppEnhance.ts

import { defineClientAppEnhance } from '@vuepress/client';

export default defineClientAppEnhance(({ app, router, siteData }) = > {
    // VueClipboard.config.autoSetContainer = true
})
Copy the code

///// config.js

import { resolve } from 'path'

module.exports = {
  clientAppEnhanceFiles: path.resolve(__dirname, './clientAppEnhance.ts')}Copy the code

background

Vuepress introduction

Create vuepress

Install VuePress globally

New Folder

Project initialization

Create a new docs folder under the root of project:

Create it in the docs folder.vuepressFolders:

in.vuepressCreate it under folderconfig.js:

in.vuepressCreate public folder under folder:

Home page (like VuePress document home page)

Our project structure has been set up:

inpackage.jsonAdd two startup commands to:

Start your VuePress:

Construction:

Basic configuration:

Navigation bar configuration:

Sidebar configuration:

FAQ

Related Posts

Should kill too much if-else

Didi Chuxing applet I18n best practices

HTML self-use Study Notes (3)

Create it in the docs folder`.vuepress`Folders:

in`.vuepress`Create it under folder`config.js`:

in`.vuepress`Create public folder under folder:

in`package.json`Add two startup commands to: