温故知新，遇见静态文档解决方案VuePress之搭建文档中心项目 - 零基础开始写作指南

前言

之前写过一篇《关于开箱即用的文档静态网站生成器VuePress》，过去很久，也不适宜了，现在与时俱进，重新梳理一次。

一、前置准备

1.1 准备Github账号(可选)

https://github.com

Github是当前全球最流行的代码托管平台，我们可以把VuePress代码托管到Github上，然后通过它静态站点功能进行发布和预览。

image

所以，需要先拥有一个github的账号，没有的话可以注册一个，另外Github还有一系列工具：Github CLI、Github Desktop、Github CodeSpace、Electron。

1.2 安装Git For Windows(可选)

https://git-scm.com

如果你电脑中还没有安装Git程序，那么需要先安装Git For Windows版本。

下载Git

官方下载链接：Git-2.34.0-64-bit.exe

或者通过Winget安装：

winget install 'Git.Git'

image

安装过程没啥可说的，保持默认设置一路安装即可。

校验安装

在Windows终端中，输入以下命令行可以试探git是否安装成功，并且查看其版本号。

git --version

image

看到正确的返回和版本号信息就行了。

准备授权(可选)

对新人来说，为了更好的拉取和推送Git，可能你需要准备一个SSH的私人密钥，可以在cmd中用如下命令进行生成一组新的SSH密钥对。

ssh-keygen -t rsa

也有一些会要求EdDSA算法的，可以写成

ssh-keygen -t ed25519 -C 'username'

image

在这个命令流程中，他会停顿等待你回答一些问题，不用处理，一路回车就行，直到完成。

如上图所示，最终生成好的rsa的私人密钥对就存在你当前电脑用户目录的.ssh文件夹下。

image

在.ssh目录中，会生成id_rsa和id_rsa.pub这两个文件。

其中id_rsa是你的SSH私钥，而id_rsa.pub是你的SSH公钥，最好备份下这两个文件。

接下来，我们用记事本打开id_rsa.pub文件，复制全部内容，粘贴到你的github账号的"SSH and GPG keys"这个里面，进行一次Add Key。

image

创建这一个密钥，并且在github中添加之后，以后它就会替代你的github账号密码，去进行项目的授权处理，这样会更加方便一点，省掉了git管理时重复输入账号密码的麻烦。

1.3 安装NodeJs环境(可选)

https://nodejs.org/zh-cn/

文档中心项目由由VuePress驱动写作，依赖NodeJS和NPM运行环境，所以我们需要安装好NodeJs才行。

下载NodeJs

官方下载链接：node-v16.13.0-x64.msi

或者通过Winget安装：

winget install 'OpenJS.NodeJS.LTS'

image

安装过程没啥可说的，保持默认设置一路安装即可。

校验安装

在Windows终端中，输入以下命令行可以试探NodeJs是否安装成功，并且查看其版本号。

npm --version

image

看到正确的返回和版本号信息就行了。

1.4 安装Visual Studio Code(可选)

https://code.visualstudio.com

推荐通过Visual Studio Code进行编写文档，后续我们会讲到通过VSC的一些插件可以快速帮助我们完成文档编写。

下载Visual Studio Code

官方下载链接：VSCodeUserSetup-x64-1.62.3.exe

或者通过Winget安装：

winget install 'Microsoft.VisualStudioCode'

image

安装过程没啥可说的，一路安装即可，建议将资源管理器上下文菜单关联勾选上，方便后面直接在资源管理器中右键打开。

1.5 安装Visual Studio Code插件(可选)

有了前面的Visual Studio Code之后，打开它，安装一些我们可能需要用到的插件，这样插件将帮助我们完成文档编写，处理各种特殊情况，提升编写效率。

image

推荐安装的插件清单包括：

  • Chinese (Simplified) Language Pack for Visual Studio Code(VSC中文语言包)
  • Excel to Markdown table(能直接把Excel表格复制粘贴成Markdown的插件)
  • GitLens — Git supercharged(用于项目拉取和提交的可视化Git管理插件)
  • Paste Image To Markdown(用于把剪贴板图片复制到项目本地并形成Markdown图片标记的插件)
  • vuepress-img-format(用于把Markdown图片设置成可弹窗放大查看的插件)
  • learn-markdown(用于提高Markdown语言编写效率的插件)
  • Markdown PDF(用于将Markdown导出成PDF、HTML、PNG等格式)

只需要搜索插件关键词，搜索找到后，安装即可。

image

二、创建项目

https://github.com/TaylorShi/HelloVuePress

2.1 创建vuePress项目

我们先为文档中心项目准备一个项目文件夹HelloVuePress，然后通过Windows终端命令进入这个目录。

mkdir HelloVuePress

cd .\HelloVuePress\

image

先做好Git的初始化。

git init

image

在当前项目添加VuePress的支持

npm install -D vuepress

image

它会在当前项目文件夹中新建一个叫node_modules的文件夹，并且创建包依赖清单文件package.json、package-lock.json。

image

安装过程中看到它提示NPM有安全更新，我们也根据提示来操作下

npm install -g npm@8.1.4

image

2.2 项目依赖初始化(可选)

如果你是第一次创建可能没有必要这个了，但是如果不是第一次创建VuePress，而是从已有的VuePress项目上直接开始，那么需要先做一次项目依赖初始化。

执行如下命令，它会根据项目包依赖清单文件package.json描述的依赖项进行初始化，如果没有会补充安装。

npm install

image

2.3 启动项目调试(可选)

通过调试模式，它会为我们新建一个HTTP服务，然后我们可以通过浏览器访问指定网页来查看当前实时的静态站点效果。

我们需要先编辑package.json文件，往其中添加scripts节点来支持一些调式命令

{
  "scripts": {
    "dev": "vuepress dev .",
    "build": "vuepress build ."
  },
  "devDependencies": {
    "vuepress": "^1.8.2"
  }
}

然后我们可以使用Run命令来运行了

npm run dev

image

image

这个意味着，你打开本地的http://localhost:8080/即可查看最新页面效果。

image

2.4 编译项目发布(可选)

当我们准备好了项目内的Markdown文件之后，我们需要通过编译功能，将Markdown变成HTML+CSS+JS的静态站点。

npm run build

image

默认情况下，静态文件会输出在.\vuepress\dist目录

image

为了git管理不至于吧生成后的dist目录包含进入，我们可以借助.gitignore文件进行排除。

# VuePress 自身目录
node_modules
.vuepress/dist

image

如需发布这个静态网站，我们只需要把整个dist目录下内容进行静态发布就好了。

三、完善内容

VuePress是一个强调约定大于配置的静态文档解决方案，所以很多时候需要知道已经约定的目录和文件是什么，跟着指南去配置就行了。

3.1 完善首页

刚创建完项目，其实一切都是空的，连首页都没有，我们先从首页开始，在项目根目录下面创建一个README.md

按如下格式填写一些内容：

---
home: true
heroImage: /assets/img/logo.svg
heroText: 静态文档中心
tagline: 邂逅文档中心，面向文档协作，开启新的篇章！
actionText: 立即开始 →
actionLink: /zh-cn/home/
features:
- title: 业务板块A
  details: 关于业务板块A的说明。
- title: 业务板块B
  details: 关于业务板块B的说明。
- title: 业务板块C
  details: 关于业务板块C的说明。
footer: Copyright @ 2021 Taylorshi
---

这里面有个静态资源哈，位于/assets/img，这个路径是怎么来的呢，我们需要在.vuepress底下先建立public文件夹，这是vuepress自身的约定哈，然后再建立assets文件夹，然后再创建下级文件夹img，这里约定img用来存放网站静态文件。

image

再次运行npm run dev看看效果，很好首页就出来了。

image

3.2 完善导航

在.vuepress文件夹下有一个约定的配置文件config.js，网站的导航、各种设置都是通过它来控制的，一开始没有的，我们需要新建一个，内容我举个例子：

module.exports = {
    title: `静态文档中心`,
    description: `关于静态文档中心的说明`,
    head: [

        ['link', { rel: 'shortcut icon', type: "image/x-icon", href: "/assets/img/favicon.ico" }],
        ['link', { rel: 'apple-touch-icon', sizes: "180x180", href: "/assets/img/apple-touch-icon.png" }],
        ['link', { rel: 'icon', type: "image/png", sizes: "32x32", href: "/assets/img/favicon-32x32.png" }],
        ['link', { rel: 'icon', type: "image/png", sizes: "16x16", href: "/assets/img/favicon-16x16.png" }],
        ['link', { rel: 'manifest', href: '/assets/config/manifest.webmanifest' }],
        ['link', { rel: 'mask-icon', href: '/assets/img/safari-pinned-tab.svg', rel:'#17214c' }],
        ['script', { src: '/assets/js/jquery/3.3.1/jquery.slim.min.js' }],
        ['script', { src: '/assets/js/fancybox/3.5.2/jquery.fancybox.min.js' }],
        ['link', { rel: 'stylesheet', type: 'text/css', href: '/assets/css/fancybox/3.5.2/jquery.fancybox.min.css' }]
    ],
    serviceWorker: true,
    themeConfig: {
        logo: '/assets/img/logo.svg',
        lastUpdated: '上次更新',
        smoothScroll: true,
        nav:
            [
                { text: '主页', link: '/zh-cn/home/' },
                {
                    text: '导航组一',
                    ariaLabel: 'Navi One',
                    items:
                        [
                            { text: '子导航一', link: '/zh-cn/navi01/subnavi01/' },
                            { text: '子导航二', link: '/zh-cn/navi01/subnavi02/' },
                            { text: '子导航三', link: '/zh-cn/navi01/subnavi03/' },
                        ]
                },
                {
                    text: '导航组二',
                    ariaLabel: 'JiezTech Product',
                    items:
                        [
                            { text: '子导航一', link: '/zh-cn/navi02/subnavi01/' },
                            { text: '子导航二', link: '/zh-cn/navi02/subnavi02/' },
                            { text: '子导航三', link: '/zh-cn/navi02/subnavi03/' },
                        ]
                },
                { text: '单导航', link: 'http://www.baidu.com' },
            ],
        sidebar: 'auto'
    },
    markdown: {
        lineNumbers: true, // 显示代码行号
    },
    plugins: [
        ['robots', {
            host: "http://wiki.taylorshi.com",
            disallowAll: true,
            sitemap: "/assets/xml/sitemap.xml",
        }],
        ['@vuepress/pwa', {
            skipWaiting: true,
            serviceWorkerFilename: 'service-worker.js'
        }]
    ]
}

虽然你可能还看不懂这是啥意思，但是我们先看看最终效果。

image

对照着效果看，我相信聪明的你总会看懂的，接下来就是举一反三了。

3.3 完善样式

其实样式怎么改，我研究的比较少，但是有一点是可以控制的，就是每个文档会有个显示宽度，如果你要改是可以的。

在.vuepress文件夹下，我们新建一个约定的目录styles，在底下新建一个文件叫palette.styl，里面丢这些内容：

$contentWidth = 1000

这个是控制内容显示宽度为1000px的意思，这个你看自己的需要来控制即可。

3.4 完善多语言

我个人是建议所有的Markdown都根据语言来做顶级目录的划分，就是说，先新建语言目录，比如zh-cn、en-us，再根据文档分类等等去建立Markdown文档。

image

在导航设置中，添加语言的切换其实很简单。

{
    text: '语言',
    ariaLabel: 'Language Menu',
    items: [
        { text: '中文', link: '/zh-cn/' },
        { text: 'English', link: '/en-us/' }
    ]
}

image

3.5 优化性能

  • 转移附件，减低体积

一方面我们应该尽量降低整个项目的体积，如果你把所有的图片等附件全部丢在Public里面，写着写着这个项目就会体积爆炸，每次编译也受不了这么折腾。

所以建议尽量把图片等附件传到云服务的网盘里面去，再通过链接链进来。

  • 定制参数，提高内存

另外一方面，随着文件增多，到了后面可能会遇到NPM编译的内存不足问题，导致失败，这里还是有办法可以来调整内存的上限的，在package.json文件的scripts中，我们可以定义Build动作的一些参数，举个例子：

{
    "scripts": {
      "dev": "vuepress dev .",
      "build": "node --max_old_space_size=7096 ./node_modules/vuepress/cli.js build ."
    }
}

这里的7096就是内存大小了，如果你的硬件足够好，可以继续往上走，直到编译成功。

参考

posted @ 2021-11-26 11:44  TaylorShi  阅读(193)  评论(0)  编辑  收藏  举报