【教程】使用vuepress构建静态文档网站，并部署到github上

桃扇骨 2024-02-22 09:49 103阅读 0赞

### 官网 ###

*  [快速上手 | VuePress (vuejs.org)][_ VuePress _vuejs.org]

### 构建项目 ###

我们跟着官网的教程先构建一个demo

> 这里我把 vuepress-starter 这个项目名称换成了 howtolive

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

mkdir howtolive && cd howtolive

1.  使用你喜欢的包管理器进行初始化

yarn init

![image.png][]  
这里的问题可以一路回车

1.  将 VuePress 安装为本地依赖

> 我们已经不再推荐全局安装 VuePress

yarn add -D vuepress

> 注意:如果你的现有项目依赖了 webpack 3.x，我们推荐使用 [Yarn (opens new window)][Yarn _opens new window]而不是 npm 来安装 VuePress。因为在这种情形下，npm 会生成错误的依赖树。  
> 注意： 不要在后面添加：\# npm install -D vuepress

1.  创建你的第一篇文档

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

1.  在 `package.json` 中添加一些 [scripts(opens new window)][scripts_opens new window]

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

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

如下图所示  
![image.png][image.png 1]

1.  在本地启动服务器

yarn docs:dev

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

项目启动之后就是这样  
![image.png][image.png 2]

### 目录结构 ###

VuePress 遵循 **“约定优于配置”** 的原则，推荐的目录结构如下：

.
    ├── docs
    │   ├── .vuepress (可选的)
    │   │   ├── public (存放网站图标等信息)
    │   │   ├── styles 
    │   │   │   └── palette.styl （网站自定义样式）
    │   │   └── config.js (路由，图标等的配置文件)
    │   │ 
    │   ├── README.md
    │   ├── guide 
    │   │   └── README.md (具体文章博客)
    │ 
    └── package.json

如下图所示  
![image.png][image.png 3]

### 配置网站标题和图标 ###

#### 配置文件 ####

如果没有任何配置，这个网站将会是非常局限的，用户也无法在你的网站上自由导航。为了更好地自定义你的网站，让我们首先在你的文档目录下创建一个 `.vuepress` 目录，所有 VuePress 相关的文件都将会被放在这里。你的项目结构可能是这样：

.
    ├─ docs
    │  ├─ README.md
    │  └─ .vuepress
    │     └─ config.js
    └─ package.json

一个 VuePress 网站必要的配置文件是 `.vuepress/config.js`，它应该导出一个 JavaScript 对象：

module.exports = {
        
    
        title: 'How to live',
        description: '让我们一起学习如何生活',
        head: [['link', {
         rel: 'icon', href: `favicon.ico` }]],
    
    }

把ico放在public下面  
![image.png][image.png 4]

项目启动之后，如下之后：

![image.png][image.png 5]

### 默认主题配置 ###

*  [默认主题配置 | VuePress (vuejs.org)][_ VuePress _vuejs.org 1]

#### 首页 ####

---
    
    home: true
    
    heroText: How to live
    
    tagline: 让我们一起学习如何生活吧
    
    actionText: 开始 →
    
    actionLink: /
    
    features:
    
    - title: 生理健康
    
      details: 了解自己的身体，养成良好的作息生活习惯
    
    - title: 心理健康
    
      details: 了解不同的文化，形成完善的认知观念
    
    ---

![image.png][image.png 6]

> 注意需要重新编译后，才会看到效果

![image.png][image.png 7]

#### 导航栏 ####

在config.js中配置

themeConfig: {
        // 主题设置
            logo: '/logo.png',
            nav: [{
        // 右上导航航条 docs/.vuepress 文件夹下
                text: '首页',
                link: '/',
            }, {
        
                text: '生理健康',
                items: [
                    {
         text: '了解身体结构', link: '/' }, // 可不写后缀 .md
                    {
         text: '养成良好生活习惯', link: 'https://www.baidu.com/' }// 外部链接
                ]
            }, {
        
                text: '心理健康',
                link: '/'
            }],
        }

![image.png][image.png 8]

![image.png][image.png 9]

#### 侧边栏 ####

themeConfig: {
        // 主题设置
            logo: '/logo.png',
            nav: [{
        // 右上导航航条 docs/.vuepress 文件夹下
                text: '首页',
                link: '/',
            }, {
        
                text: '生理健康',
                items: [
                    {
         text: '人体构造', link: '/生理健康/人体构造/通用/1肌肉' }, // 可不写后缀 .md
                    {
         text: '生活习惯', link: 'https://www.baidu.com/' }// 外部链接
                ]
            }, {
        
                text: '心理健康',
                link: '/'
            }],
            sidebar: {
        //左侧列表
                    '/生理健康/人体构造/': [{
        
                        title: '人体构造',
                        collapsable: true,
                        children: [{
        
                            title: '肌肉',
                            path: '通用/1肌肉'
                        },{
        
                            title: '眼睛',
                            path: '通用/2眼睛'
                        }]
                    },{
        
                        title: '男性',
                        collapsable: true,
                        children: [{
        
                            title: '喉结',
                            path: '/男性/3喉结'
                        }]
                    }],
                    '/': [''], //不能放在数组第一个，否则会导致右侧栏无法使用 
            },
                // 左侧列表展开级数，默认是 1
            sidebarDepth: 2,
                
        }

![image.png][image.png 10]

![image.png][image.png 11]

![image.png][image.png 12]

### 自定义样式 ###

![image.png][image.png 13]

#### 改变主题颜色 ####

$accentColor = #378ae2

#### 改变文章两侧空白宽度 ####

.page .theme-default-content:not(.custom){
        
        max-width: none;
    }

### 部署到github ###

[部署 | VuePress (vuejs.org)][_ VuePress _vuejs.org 2]

在根目录下建一个depoy.sh  
![image.png][image.png 14]

#!/usr/bin/env sh
    
    # 确保脚本抛出遇到的错误
    set -e
    
    # 生成静态文件
    npm run docs:build
    
    # 进入生成的文件夹
    cd docs/.vuepress/dist
    
    # 如果是发布到自定义域名
    # echo 'www.example.com' > CNAME
    
    git init
    git branch -m master main
    git add -A
    git commit -m 'deploy'
    
    # 如果发布到 https://<USERNAME>.github.io
    # git push -f git@github.com:<USERNAME>/<USERNAME>.github.io.git main
    
    # 如果发布到 https://<USERNAME>.github.io/<REPO>
    
    git push -f git@github.com:ni'de.git main
    
    cd -

config.js也要修改  
![image.png][image.png 15]

然后双击deploy.sh运行  
![image.png][image.png 16]

> 或者在gitbash中打开

然后dist目录下生成打包好的项目，并同步到gihub  
![image.png][image.png 17]

![image.png][image.png 18]

#### 配置github ####

![image.png][image.png 19]

然后就可以通过github来访问静态网站了

![image.png][image.png 20]

[_ VuePress _vuejs.org]: https://vuepress.vuejs.org/zh/guide/getting-started.html
[image.png]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/47e587a21cb5414b89b1d1dbd7cf0fe6.png
[Yarn _opens new window]: https://classic.yarnpkg.com/zh-Hans/
[scripts_opens new window]: https://classic.yarnpkg.com/zh-Hans/docs/package-json#toc-scripts
[image.png 1]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/3d89e108b456497f93d1ce1ea6552772.png
[http_localhost_8080 _opens new window]: http://localhost:8080/
[image.png 2]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/f0b6c26cf6dc47d2901c1ffc66e77337.png
[image.png 3]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/b7f7dfeb12a34229b68769fa11a3f997.png
[image.png 4]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/e492e6d19ed44630b11f7bdda2f62910.png
[image.png 5]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/8f7349413c1b42438a6d9bc2fbbc5956.png
[_ VuePress _vuejs.org 1]: https://vuepress.vuejs.org/zh/theme/default-theme-config.html
[image.png 6]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/ede4cb60aebd40e3be4321e80a39d066.png
[image.png 7]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/4fab7f5ae390469a859883940244ed6b.png
[image.png 8]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/150f709637344846b868435a87e282ce.png
[image.png 9]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/958c3c0b2a4b4fec8306d116a9473c42.png
[image.png 10]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/5941a835aceb4368a83adf38831a1635.png
[image.png 11]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/02b5a4960a234c81aca0bf15167942b8.png
[image.png 12]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/58f900579a6e4a0d8bb8ca42ec9d526f.png
[image.png 13]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/da2f8ba3573d4e8dbd27bb94e001eb54.png
[_ VuePress _vuejs.org 2]: https://vuepress.vuejs.org/zh/guide/deploy.html#github-pages
[image.png 14]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/c03229d3c80240b5af7dd8b8f882e92c.png
[image.png 15]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/5bba772614e8466c9d494cc528b171cb.png
[image.png 16]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/db78462baac44520ac19f41cef701f23.png
[image.png 17]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/a92f09f3246043a09b3549ac416a1fe0.png
[image.png 18]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/f53bb33f44db486fb4254a9d2c24d7ca.png
[image.png 19]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/60d35e02217c4c50b250ca7b44fd8ad5.png
[image.png 20]: https://image.dandelioncloud.cn/pgy_files/images/2024/02/22/ad5e4982d8e84321be2e408f61c899a7.png