A0. VuePress快速上手

0. 环境准备

0.1 安装Node.js

$ sudo apt install nodejs
$ node -v #查看版本，要求>= 8.6

0.2 安装yarn

Yarn 是一个 JavaScript 包管理器，它兼容于 npm，可以帮助你自动处理安装，升级，配置，和移除 npm 包。

$ sudo apt install cmdtest #这样的安装有点问题
$ yarn --version #查看版本

本文会帮助你从头搭建一个简单的 VuePress 文档。如果你想在一个现有项目中使用 VuePress 管理文档，从步骤 3 开始。

1. 创建并进入一个新目录

$ mkdir vuepress-starter && cd vuepress-starter

2. 使用你喜欢的包管理器进行初始化，推荐使用yarn

$ yarn init # npm init

3. 将 VuePress 安装为本地依赖

已经不再推荐全局安装 VuePress

$ yarn add -D vuepress # npm install -D vuepress

注意

如果你的现有项目依赖了 webpack 3.x，我们推荐使用 Yarn (opens new window)而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。

4. 创建你的第一篇文档

$ mkdir docs && echo '# Hello VuePress' > docs/README.md

5. 在 package.json 中添加一些 scripts(opens new window)

这一步骤是可选的，但我们推荐你完成它。在下文中，我们会默认这些 scripts 已经被添加。

{
  "scripts": {
    "docs:dev": "vuepress dev docs",
    "docs:build": "vuepress build docs"
  }
}

6. 在本地启动服务器

yarn docs:dev # npm run docs:dev

VuePress 会在 http://localhost:8080 (opens new window)启动一个热重载的开发服务器。

现在，你应该已经有了一个简单可用的 VuePress 文档。接下来，了解一下推荐的 目录结构 和 VuePress 中的 基本配置。

二、 基本配置

2.1 目录结构

vuepress-starter
├─── docs
│   ├── README.md
│   └── .vuepress
│   |   └── config.js
|   └── public
│       └── img
│       └── pdf
└── package.json

2.2 简单设置

修改 config.js 文件，设置配置网站标题、描述、主题等信息：

module.exports = {
  title: '教学文档',
  description: '蔡远利的教学文档',
  markdown: {
    lineNumbers: false // 代码块显示行号
  },
  themeConfig: {
    logo: '/img/xjtulogo.jpg', //图标设置
    nav:[ // 导航栏配置
      {text: '本科教学', link: '/graduate/' },
      {text: '研究生教学', link: '/master/'},
      {text: '技术资料', link: '/technology/'},
      {text: 'XJTU', link: 'https://www.xjtu.edu.cn'}      
    ],
    sidebar: 'auto', // 侧边栏配置
    sidebarDepth: 2, // 侧边栏显示2级
  }
};

2.3 MD增强功能

2.3.1 自定义容器

在markdown文档中有如下自定义容器：

::: tip 提示
this is a tip
:::

::: warning 注意
this is a tip
:::

::: danger 警告
this is a tip
:::

2.3.2 表情符号

可以在Markdown文档中添加需要的表情符号。 例如：

:tada: :100: :bamboo: :gift_heart: :fire:

这里有一份 Emoji 大全 Emoji (opens new window)

2.4 首页设置

vuepress内置了一个主页样式，是Front-matter格式的。要放md文件的顶部，否则不会生效。 首页的文件是根级README.md文件，例如：

---
home: true
heroImage: 
actionText: 快速上手 →
actionLink: /technology/
features:
- title: 本科生课程
  details: 面向大学低年级学生的《自动化专业概论》课程，目前改为考核，包括平时作业和期末大作业。自动化专业核心必修课，1学分，16学时。
- title: 研究生课程
  details: 面向硕士研究生和博士研究生的《随机系统的滤波与控制》。专业学位课，3学分，60学时。
- title: 科技资料
  details: 定期更新一些学术论文或技术报告。
footer: XJTU Licensed | Copyright © 2024 Yuan-Li Cai
---
# Let's start !
:tada: ➡ 💯

::: tip 提示
最好的学习方法是兴趣 !
:::

::: warning 注意
科学研究的第一步是**Reading !**
:::