Vuepress2.X从0-1保姆级入门教程

Vuepress2.X从0-1保姆级入门教程

前言

本文使用默认主题帮助大家从0-1搭建自己的文档站。如果不想使用默认主题，我推荐vuepress-theme-hope

开始教程前，请新建文件夹存放项目文件，备好文档素材

环境与工具

工具

• Windows Terminal（终端）
• Visual Studio Code
• Typora或者其他Markdown书写软件
• Git

环境安装

Node

访问官网下载，推荐长期维护版

Yarn

npm config set registry http://registry.npmmirror.com //国内淘宝镜像
npm install yarn -g

Vuepress

选择目标文件夹，并右键打开终端输入(●ˇ∀ˇ●)

yarn init -y
git init
yarn add -D vuepress@next

目录结构

敲黑板，这一步非常重要！请先阅览一遍，再继续下面操作

├── dist				yarn docs:build后自动生成，不用管
├── node_modules		 
├── docs                 存放文章，可以改名
|  ├── .vuepress		 
|  |  ├── config.ts      配置
|  |  ├── public        【静态资源】
|  |  └── styles        【自定义样式】		 
|  ├── Guide            【子版块】文件夹，名字任意
|  |  └── README.md     【子版块】首页
|  ├── README.md        【主页】
|  └── zh				 配置多语言，名字任意，可选
|     └── README.md      对应语言首页
├── package.json
├── deploy.sh		     Github【部署方式1】
├── .github				 Github【部署方式2】
|  └── workflows	     
|     └── main.yml       
├── .gitignore           git忽略目录
└── yarn.lock

框架搭建

1.package.json

文件夹根目录打开package.json，添加

"scripts": {									
    "docs:dev": "vuepress dev docs",           
    "docs:build": "vuepress build docs"         
},	
    
/* 以下内容可选 */
//作者
"author": "[email protected]",
//关键词
"keywords": [
    "foresee",
    "igloo",
    "vuepress"
],
//添加个人仓库    
"homepage": "https://github.com/passwordgloo/passwordgloo.github.io",
"repository": {
    "type": "git",
    "url": "https://github.com/passwordgloo/passwordgloo.github.io.git"
},

2.README.md（文档首页）

在docs文件夹内，新建README.md。

---
home: true
heroImage: /favicon.png
heroText: igloo's document
actions:
  - text: 快速上手
    link: /Guide/
    type: primary
  - text: 项目简介
    link: /guide/
    type: secondary
features:
- title: Note
  details: Markdown-centered notes that record every moment succinctly and efficiently
- title: Blog
  details: Clean and tidy blog, easy to archive files
- title: Document
  details: Online personal documentation, make the desired documentation
footer: MIT Licensed | Copyright © 2016-present Passwordgloo
---
请在此书写你的内容

名称	含义
home	判断是否是首页
heroImage	首页logo图
hexoText	首页标题
actions	按钮，text和link可以多个
features	文档分栏，title和details数量自定
footer	文档底部板块

3.测试

文件夹根目录打开终端，输入yarn docs:dev

配置

YAML Frontmatter

Markdown文件开头可以设置YAML Frontmatter。代码两端使用---隔开
使用sidebar:auto自动显示侧边栏标题

---
lang: zh-CN
title: 页面的标题
description: 页面的描述
sidebar: auto
---

Config.ts

.vuepress文件夹内新建config.ts，官方推荐使用typescript编写

//引入默认主题
import { defaultTheme } from 'vuepress'
export default {
	theme: defaultTheme({
	// favicon.ico网站收藏夹图标，图片本地地址在public文件夹内，图片地址也可选填网络地址
	head: [['link', { rel: 'icon', href: '/favicon.ico' }]],
	
	logo: 'favicon.png', //文件在public文件夹内
	repo: 'username/repoName',  //默认识别为GitHub仓库

	//设置多语言，默认页面为en-US，新建`zh`文件夹存放中文页面
	locales: {
	  '/': {
	      selectLanguageName: 'English',
	      title: 'Foresee the future',
	      description: 'igloo\'s bookshop',
		  navbar: [
			  {
			        text: '首页',
			        link: '/',
			        // 该元素将一直处于激活状态
			        activeMatch: '/',
			    },
			    //两层嵌套
			    {
			        text: '语言学习',
			        children: [
			            {
			                text: '编程语言',
			                children: ['C', 'Java', 'Js', 'PHP', 'Python'],
			            },
			            {
			                text: '标记美化',
			                children: ['HTML', 'Markdown', 'CSS'],
			            },
			        ],
			    },
			    //多个条目
			    {
			        text: '课程',
			        children: ['Politics', 'English'],
			    },
			    // 字符串 - 页面文件路径
			    '/Guide/README.md',
				]
	        },
	        //可单独设置文章sidebar:auto
		 	sidebar: {
			   '/guide/': [
			        {
			            text: '指导',
			            children: ['env', 'grammer'],
			        }
			    ],
			    '/reference/': [
			        {
			            text: '算法',
			            //可折叠侧边栏
			            collapsible: true,
			            children: ['/C/算法学习.md', '/C/算法学习2.md', '/C/算法学习3.md'],
			        },
			        {
			            text: '指针',
			            collapsible: true,
			            children: ['/C/指针.md', '/C/指针2.md', '/C/指针3.md'],
			        },
			    ],
			}
	    '/zh/': {
	    	selectLanguageName: '简体中文',
	        title: '预见·未来',
	        description: 'igloo文档库',
	        }
		},
	notFound:['Not Found','没找到','网页走丢了'],
	backToHome:'返回首页' //404 页面中 返回首页链接的文字。
	})
}

效果

终端输入yarn docs:dev,显示效果

• 英文界面
  

• 中文界面
  

• 自定义侧边栏
  

• 设置sidebar:auto
  

插件与自定义

插件

vuepress-plugin-md-enhance

提供更强的Markdown支持，诸如段落对齐、Tex语法、上下角标、代码块分组等新功能

• 安装

yarn add -D vuepress-plugin-md-enhance@next

• 使用

import { mdEnhancePlugin } from "vuepress-plugin-md-enhance";

export default {
  plugins: [
    mdEnhancePlugin({
      // 你的选项
    }),
  ],
};

search

search会根据你的页面，在本地生成搜索索引，页面多的话，加载速度会慢

• 安装

yarn add -D @vuepress/plugin-search@next

• 配置

import { searchPlugin } from '@vuepress/plugin-search'

export default {
    plugins: [
        searchPlugin({
            locales: {
                '/': {
                    placeholder: 'Search',
                },
                '/zh/': {
                    placeholder: '搜索',
                },
            },
        }),
    ],
}

docsearch

• 安装

yarn add -D @vuepress/plugin-docsearch@next

• 使用

import { docsearchPlugin } from '@vuepress/plugin-docsearch'

export default {
  plugins: [
    docsearchPlugin({
      // 配置项
    }),
  ],
}

访问DocsSearch提交网站URL，审核通过后DocSearch 团队会将 apiKey 和 indexName 发送到你的邮箱

自定义

在styles文件夹下新建index.scss文件,书写自定义样式

效果展示

终端输入yarn docs:dev

部署

方案1 deploy.sh

根目录新建deploy.sh，名字任取

#空项目预置环境

# 确保脚本抛出遇到的错误
set -e

# 生成静态文件
npm run docs:build

# 进入生成的文件夹
cd dist


# 如果是发布到自定义域名
# echo 'www.example.com' > CNAME

git init
git add -A

git commit -m "initial commit"
# 如果发布到 https://.github.io
git push -f [email protected]:<USERNAME>/<USERNAME>.github.io.git master

# 如果发布到 https://.github.io/
# git push -f [email protected]:/.git master:gh-pages

cd -

终端打开Git，输入./deploy.sh

方案2 Github Action

Token

登录Github，点击右上角头像选择Settings

依次选择Developer setttings>Personal access tokens，点击Generate new token创建Token

Token只会显示一次，请记得保存

仓库设置

新建仓库

仓库点击Settings>Secerts>Actions，输入刚刚保存好的Token

Github Action

workflows文件下下新建docs.yml文件，名字任意

name: docs

on:
  # 每当 push 到 main 分支时触发部署
  push:
    branches: [main]
  # 手动触发部署
  workflow_dispatch:

jobs:
  docs:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v2
        with:
          # “最近更新时间” 等 git 日志相关信息，需要拉取全部提交记录
          fetch-depth: 0

      - name: Setup Node.js
        uses: actions/setup-node@v1
        with:
          # 选择要使用的 node 版本
          node-version: '14'

      # 缓存 node_modules
      - name: Cache dependencies
        uses: actions/cache@v2
        id: yarn-cache
        with:
          path: |
            **/node_modules
          key: ${{ runner.os }}-yarn-${{ hashFiles('**/yarn.lock') }}
          restore-keys: |
            ${{ runner.os }}-yarn-

      # 如果缓存没有命中，安装依赖
      - name: Install dependencies
        if: steps.yarn-cache.outputs.cache-hit != 'true'
        run: yarn --frozen-lockfile

      # 运行构建脚本
      - name: Build VuePress site
        run: yarn docs:build

      # 查看 workflow 的文档来获取更多信息
      # @see https://github.com/crazy-max/ghaction-github-pages
      - name: Deploy to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v2
        with:
          # 部署到 gh-pages 分支
          target_branch: gh-pages
          # 部署目录为 VuePress 的默认输出目录
          build_dir: docs/.vuepress/dist
        env:
          # Token名称必须与仓库Token名称相同
          GITHUB_TOKEN: ${{ secrets.Vuepress_Token }}

根目录创建.gitignore文件，输入

#ide
*.DS_Store
.idea
.vscode

#npm
package-lock.json
yarn.lock

#build result
dist
lib
.vuepress/temp
.vuepress/cache

# Logs
logs
*.log
npm-debug.log*
yarn-debug.log*
yarn-error.log*
lerna-debug.log*

# Runtime config
pids
*.pid
*.seed
*.pid.lock

# Directory for instrumented libs generated by jscoverage/JSCover
lib-cov

# Coverage directory used by tools like istanbul
coverage

# Compiled binary addons (https://nodejs.org/api/addons.html)
build/Release

# Dependency directories
node_modules

# Optional npm cache directory
.npm

# Optional eslint cache
.eslintcache

# Optional REPL History
.node_repl_history

# Output of 'npm pack'
*.tgz

# Yarn Integrity file
.yarn-integrity

# dotenv environment variables file
.env

#lerna-changelog
.changelog

#vscode history extension
.history