Liverpoolfc.tv: vuepress.vuejs.org/zh/

Quick learning

The premise condition

VuePress needs Node.js (new window)>= 8.6

1. Install vuepress

yarn add -D vuepress # npm install -D vuepress
Copy the code

2. Create your first document

mkdir docs && echo '# Hello VuePress' > docs/README.md
Copy the code

3. Add scripts to package.json

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

4. Start the server locally

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

VuePress starts a hot-loaded development server at http://localhost:8080.

The directory structure

  • docs/.vuepress: Stores global configurations, components, and static resources.
  • docs/.vuepress/componentsVue components in this directory will be automatically registered as global components.
  • docs/.vuepress/theme: Stores the local theme.
  • docs/.vuepress/styles: used to store style related files.
  • docs/.vuepress/styles/index.styl: The global style file that will be automatically applied, will be generated at the end of the final CSS file, and has higher priority than the default style.
  • docs/.vuepress/styles/palette.styl: is used to override the default color constant or to set the new stylus color constant.
  • docs/.vuepress/public: Static resource directory.
  • docs/.vuepress/templates: Stores the HTML template file.
  • docs/.vuepress/templates/dev.html: HTML template file for the development environment.
  • docs/.vuepress/templates/ssr.html: HTML template file based on Vue SSR at build time.
  • docs/.vuepress/config.js: Indicates the entry file of the configuration fileYML 或 toml.
  • docs/.vuepress/enhanceApp.js: Client application enhancement.

Default page routing

The relative path of the file Page Routing Address
/README.md /
/guide/README.md /guide/
/guide/config.md /guide/config.html

The topic configuration

Home page

The default theme provides a Homepage layout (for the Homepage of the site). To use it, you need to specify home: true in your root readme.md. Here’s an example of how to use it:

-- home: true heroImage: /hero.png heroText: hero title Tagline: hero subtitle actionText: Quick Start → actionLink: /zh/guide/ features:-Details: A Markdown-centric project structure that helps you focus on writing with minimal configuration.-Vue Driver Details: Enjoy the development experience of Vue + WebPack, using Vue components in Markdown, and can use Vue to develop custom themes.-Title: High performance Details: VuePress generates static HTML for each page pre-render and runs as a SPA when the page is loaded.Footer: MIT Licensed | Copyright © 2018 - present Evan You -
Copy the code

More Configuration Items

The navigation bar

The navigation bar may contain your page title, search box, navigation bar link, multilanguage switch, repository link, all depending on your configuration.

The navigation bar Logo

// .vuepress/config.js
module.exports = {
  themeConfig: {
    logo: '/assets/img/logo.png',}}Copy the code

Navigation link

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [{text: 'Home'.link: '/' },
      { text: 'Guide'.link: '/guide/' },
      { text: 'External'.link: 'https://google.com' },
      { text: 'test'.link: 'test'.target:'_self'.rel:' '}}}]Copy the code

Set up the group

// .vuepress/config.js
module.exports = {
  themeConfig: {
    nav: [{text: 'Languages'.items: [{text: 'Chinese'.link: '/language/chinese/' },
          { text: 'Japanese'.link: '/language/japanese/'}}}Copy the code

The sidebar

To make the Sidebar work, you need to configure themeConfig. Sidebar. The basic configuration requires an array containing multiple links:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [
      '/'.'/page-a'['/page-b'.'Explicit link text']]}}Copy the code

Omit the.md extension, and paths ending in/will be treated as */ readme.md, and the text of the link will be automatically retrieved

Nested title links

By default, the sidebar automatically displays links made up of the headers of the current page, nested according to the structure of the page itself, and you can modify its behavior with themeConfig. SidebarDepth. The default depth is 1 and it will extract h2 headers, 0 will disable headers links, and the maximum depth is 2 and it will extract both H2 and H3 headers.

Displays title links for all pages

// .vuepress/config.js
module.exports = {
  themeConfig: {
    displayAllHeaders: true // Default: false}}Copy the code

The title link of the activity

By default, the Hash values in the nested header links and urls are updated in real time as the user scrolls through different parts of the page. This behavior can be disabled with the following configuration:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    activeHeaderLinks: false.// Default: true}}Copy the code

The sidebar groups

// .vuepress/config.js
module.exports = {
  themeConfig: {
    sidebar: [{title: 'Group 1'./ / necessary
        path: '/foo/'.// Optional, the jump link to the title should be absolute and must exist
        collapsable: false.// Optional, default is true,
        sidebarDepth: 1.// Optional, default is 1
        children: [
          '/'] {},title: 'Group 2'.children: [ / *... * /].initialOpenGroupIndex: -1 // Optional, default is 0}}}]Copy the code

Each subgroup in the sidebar is collapsible by default, and you can always collapse the group by setting collapsable: false.

Multiple sidebars

│ ├─ readme.md │ ├─ foo/ │ ├─ readme.md │ ├─ one.md │ ├─ two. Md │ ├─ three └ ─ four. The mdCopy the code

Pay attention to

Make sure the Fallback sidebar is defined last. VuePress iterates through the sidebar configurations in order to find a matching configuration

The search box

The built-in search

You can set themeConfig. Search: false to disable the default search box, or by themeConfig. SearchMaxSuggestions to adjust the default search box shows the number of search results

// .vuepress/config.js
module.exports = {
  themeConfig: {
    search: false.searchMaxSuggestions: 10}}Copy the code

Last updated

You can use the themeConfig. LastUpdated option to get the UNIX timestamp (MS) of the last Git commit for each file, and it will be displayed at the bottom of each page in the appropriate date format:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    lastUpdated: 'Last Updated'.// string | boolean}}Copy the code

Top/next link

Links to previous and next articles are automatically retrieved in the order of the sidebar of the current page.

You can disable them globally with themeConfig. NextLinks and themeConfig. PrevLinks:

// .vuepress/config.js
module.exports = {
  themeConfig: {
    // The default is true. Set to false to disable the next link on all pages
    nextLinks: false.// The default is true. Set to false to disable previous links on all pages
    prevLinks: false}}Copy the code

Git repository and editing links

When you provide the themeConfig. Repo option, it will automatically generate a GitHub link in the navigation bar of each page and an “Edit this Page “link at the bottom of the page.

// .vuepress/config.js
module.exports = {
  themeConfig: {
    // GitHub is assumed. It can also be a full GitLab URL
    repo: 'vuejs/vuepress'.// Custom repository link text. The default is automatically inferred from 'themeconfig. repo'
    // "GitHub"/"GitLab"/"Bitbucket" one of them, or "Source".
    repoLabel: 'View the source code'.// The following is an optional edit link option
    // If your document repository is not in the same repository as the project itself:
    docsRepo: 'vuejs/vuepress'.// If the document is not in the repository root directory:
    docsDir: 'docs'.// If the document is placed under a specific branch:
    docsBranch: 'master'.// The default is false, set to true to enable
    editLinks: true.// Edit this page by default
    editLinkText: 'Help us improve this page! '}}Copy the code

Static resource

Static resources are stored in public files

Use of pictures

<img :src="$withBase('/frontend/prototype-chains.jpg')" alt="prototype-chains">

logo

// .vuepress/config.js
module.exports = {
  themeConfig: {
    logo: '/logo.png',}}Copy the code

Home page logo

// README.md
---
heroImage: /app.png
---
Copy the code

Markdown extension

Emoji

You can find all the emojis available in this list.

Custom container

::: warning this is a warning ::: ::: danger this is a danger warning ::: ::: Details This is a details block that does not work in IE/Edge :::Copy the code

You can also customize the title in the block:

::: Danger STOP ::: danger STOP ::: danger STOP ::: danger STOP :: danger STOP :: danger STOP :: danger STOP :: danger STOP :: danger STOP :: danger STOP :: danger STOPCopy the code

Syntax highlighting in code blocks

VuePress uses Prism to implement syntax highlighting for code blocks in Markdown. Prism supports a large number of programming languages. All you need to do is append a valid language alias to the beginning of the code block:

    ` `` export default { name: 'MyComponent', // ... } `` `
Copy the code

See a list of legitimate languages at Prism’s web site.

Lines in code blocks are highlighted

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

In addition to a single line, you can also specify multiple lines, intervals, or both.

  • Line interval: for example5 {8}.10} {3 -.17} {10 -
  • Multiple single lines: for example,7,9 {4}
  • Row number interval with multiple single lines: for example13,16,23-27, 40} {4, 7 -

The line Numbers

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

Import code snippet

<<< @/docs/.vuepress/code/test.js
Copy the code

Use the VUE component

All *. Vue files found in.vuepress/components are automatically registered as global asynchronous components, such as:

..vuepress ├─ Components ├─ demos -1. Vue ├─ OtherComponent. Vue ├─ Foo ├─ BarCopy the code

You can use these components directly in any Markdown file (the component name is given by the file name) :

<demo-1/>
<OtherComponent/>
<Foo-Bar/>
Copy the code

The plug-in

@vuepress/plugin-back-to-top

The installation

yarn add -D @vuepress/plugin-back-to-top
# OR npm install -D @vuepress/plugin-back-to-top
Copy the code

use

module.exports = {
  plugins: ['@vuepress/back-to-top']
}
Copy the code

Build and deploy

Github Pages is a public static page hosting service for users, organizations, and projects. Sites can be hosted for free on Github. You can choose to publish your site using the domain Github. Not only does it eliminate the hassle of renting a server, but it’s also very easy to deploy. In short, blogging on GitHub Pages is a great option.

Create two repositories

1. Amjanney.github. IO, site repository for storing packaged files.

2. Docs, for storing documents written by Vuepress.

By default, github. IO reads index.html from the root directory as the home page. So what we need to do is upload the packaged Vuepress document to the repository we created named

.github. IO.

The warehouse address

Github.com/amjanney/am…

Github.com/amjanney/do…

release

Under docs is the deploy.sh file with the following code:

#! /usr/bin/env sh

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

#Generating static files
npm run docs:build

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

#If it is published to a custom domain name
# echo 'www.example.com' > CNAME

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

#If published to the https://amjanney.github.io
git push -f https://github.com/amjanney/amjanney.github.io.git master
Copy the code

Configure the command in the package.json file

"deploy": "bash deploy.sh"
Copy the code

run

npm run deploy
Copy the code

The vuepress file will be packaged under docs/.vuepress/dist, CD to this file, and upload to amjanney.github. IO. Git repository using git. At this point, access amjanney.github. IO/and the document is in effect.

Each time you change a file, you need to run the NPM run deploy command to update the document.

Of course, this process can be integrated. Each time the code is pushed to the master, the NPM run deploy process is automatically started.

Step by step for more deployment modes.

The last

Click “like” before you go!!

Individuals making

Personal blog