VuePress uses notes

Recently, I helped to build an official website for a product in the group, which required a cool homepage, and then the product user manual. I checked several types of static website generators. Finally, I chose the powerful VuePress because the homepage still had some customization requirements and I was familiar with Vue.

1. Build projects

There is no need to pay attention to this step, just follow the tutorial on the website step by step. VuePress requires Node.js >= 8.6, and my Node.js environment is V12.

#Create and enter a new directory
mkdir vuepress-starter && cd vuepress-starter
#Initialize using your favorite package manager
yarn init # npm init
#Install VuePress as a local dependency
yarn add -D vuepress # npm install -D vuepress
#Create your first document
mkdir docs && echo '# Hello VuePress' > docs/README.md
Copy the code

Then add some scripts to package.json

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

Start the server locally

yarn docs:dev # npm run docs:dev
Copy the code

2. Project structure

VuePress follows the principle of convention over configuration. The recommended directory structure is as follows:

.├ ── docs │ ├─.vuePress (Optional) # For storing global configurations, components, static resources, etc. │ ├─ Components # Vue components in this directory will be automatically registered as global components. │ ├─ Theme (Optional) # For local themes. │ ├─ Public (Optional) # Static Resources. │ ├─ Styles (Optional) # For storing style related files. │ ├─ Templates store HTML template files. │ ├─ ├─ ├─ ├─ ├.js (optional) # ├─ ├─ ├.js (optional) # │ │ ├ ─ ─ the README. Md ├ ─ ─ guide │ │ └ ─ ─ the README. Md │ └ ─ ─ config. The md │ └ ─ ─ package. The jsonCopy the code

All document-related files are written in the Docs folder, and all pages correspond to a Markdown file.

For the directory structure above, the default page routing address is as follows:

The relative path of the file	Page routing address
/README.md	/
/guide/README.md	/guide/
/config.md	/config.html

3. Configure the page

Logo navigation bar and Favicon configuration

Add logo.png and idec.ico image files under docs/.vuepress/public and configure them in.vuepress/config.js

// docs/.vuepress/config.js
module.exports = {
    head: [['link', { rel: 'icon'.href: '/idec.ico'}]],themeConfig: {
        logo: '/logo.jpg',}};Copy the code

Display effect:

Navigation link

You can add some navigation links via themeConfig. Nav

themeConfig: {
    nav: [{text: 'Home'.link: '/' },
        { text: 'Part1'.link: '/part1/' },
        { text: 'Part2'.link: '/part2/' },
        { text: 'External'.link: 'https://google.com']}},Copy the code

Sidebar configuration

1. You can omit the.md extension, and paths ending in/will be treated as */README. Md, and the text of the link will be retrieved automatically (whether you declare it as the first header of the page, or explicitly specify the page title in YAML Front Matter). If you want to explicitly specify the text of the link, use a format of[link, text]The array.

themeConfig: {
    sidebar: [
        '/'.'/part1/'['/part1/chapter1'.'Whatever the title is, it'll show up on the left.']]},Copy the code

Corresponding file structure

| - docs └ ─ ─. Vuepress └ ─ ─ part1 └ ─ ─ chapter1. Corresponding/part1 / md # chapter1 └ ─ ─ the README. Corresponding/part1 / md # └ ─ ─ the README. # corresponding/mdCopy the code

2. The left column is displayed in groups

themeConfig: {
    sidebar: [{title: 'part1'./ / necessary
            path: '/part1/'.// Optionally, the jump link for the title should be an absolute path and must exist
            collapsable: false.// Optional, default is true,
            sidebarDepth: 1.// The default value is 1
            children: [['/part1/chapter1'.'Whatever the title is, it'll show up on the left.'].'/part1/chapter2'] {},title: 'part2'./ / necessary
            children: [
                '/part2/'.'/part2/chapter1'.'/part2/chapter2',]},]}Copy the code

File structure and display effect

3. Multiple left columns

The file structure remains the same, change the sidebar to the following form, the left column will show different contents under ‘/part1/’ and ‘/part2/’ respectively.

themeConfig: {
    sidebar: {
        '/part1/': [
            ' './* /part1/ */
            'chapter1'./* /part1/chapter1.html */
            'chapter2'   /* /part1/chapter2.html */].'/part2/': [
            ' './* /part2/ */
            'chapter1'./* /part2/chapter1.html */
            'chapter2'   /* /part2/chapter2.html */].}}Copy the code

The effect is as follows:

Home page configuration

The default theme provides a layout for a Homepage. To use it, specify home: true in YAML Front Matter of your root readme. md.

You can use the default home page layout to configure the home page title, image and other content.

-- Home: true heroImage: /logo.png heroText: Hero Tagline: Hero Subtitle actionText: Quick start → actionLink: /part1/ features:-Markdown-centric project structure that helps you focus on writing with minimal configuration.-Enjoy the development experience of Vue + Webpack, use Vue components in Markdown, and develop custom themes using Vue.-VuePress 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

4. Customize the page

Custom styles

If you want to simple replacement of default default styles, or define some variables for later use, you can create a. Vuepress/styles/palette. Styl file. Refer to palette-styl for details.

VuePress provides an easy way to add additional styles. You can create a. Vuepress/styles/index. Styl file. This is a Stylus file, but you can also use normal CSS syntax.

Custom page classes

Declare a pageClass in the YAML Front Matter of the page

---
pageClass: custom-page-class
---
Copy the code

Then in the vuepress/styles/index. Styl set corresponding style

/* .vuepress/styles/index.styl */
.theme-container.custom-page-class {
  color: tomato;
}
Copy the code

Custom layout for a particular page

Components can be specified on the page YAML Front Matter.

---
layout: Home
---
Copy the code

Then implement Home components. Vuepress/components/Home. Vue, this page will be completely custom, not the left navigation bar and bar, etc. The default content. More suitable for custom home page.

<template>
    <div class="home-container">Custom layout -Home</div>
</template>

<script>
    export default {
        name: 'Home'
    }
</script>

<style scoped>
    .home-container {
        text-align: center;
        color: tomato;
    }
</style>
Copy the code

Introducing third-party libraries

Since I need a cool home page, I would like to introduce the Element library.

Install it through YARN Add element-UI and then configure it in.vuepress/ enhanceapp.js.

// .vuepress/enhanceApp.js
// Globally register the Element component library
import ElementUI from 'element-ui';
import 'element-ui/lib/theme-chalk/index.css';

export default ({
                    Vue, // VuePress is using the Vue constructor
                    options, // Some options to attach to the root instance
                    router, // Route instance of the current application
                    siteData // Site metadata
                }) => {
    Vue.use(ElementUI)
}
Copy the code

And then I realized I had an error =. =

assign.js? 3f6b:1 Uncaught Error: Cannot find module ‘core-js/library/fn/object/assign’

For details, see github.com/vuejs/vuepr… The conflict is caused by inconsistent core-JS versions. Run yarn add [email protected] to resolve the problem.

You can now use element components directly in markdown files.

reference

• vuepress.vuejs.org/zh/guide/
• Vuepress.vuejs.org/zh/theme/de…
• Segmentfault.com/a/119000002…