VuePress-快速启动指南-全-

VuePress 快速启动指南（全）

原文：zh.annas-archive.org/md5/986b9a64ec5b7230ac6d991c3d740203

译者：飞龙

协议：CC BY-NC-SA 4.0

前言

VuePress 自称为“Vue 动力的静态站点生成器”。换句话说，VuePress 是一个简单的工具，可以让您在几分钟内创建静态站点和单页应用（SPA）。

在 VuePress 中构建的任何内容都是搜索引擎友好的，完全优化的，并且也是移动友好的，由于没有数据库驱动的操作或外部引擎的工作，因此速度非常快。您只需在 Markdown 中输入内容，VuePress 将解析 Markdown 文件为有效的 HTML。

但 VuePress 不仅仅是静态站点生成！您可以自定义其外观，调整默认的最小主题，并利用 Vue.js 专业知识来扩展站点的功能。考虑到 Vue.js 的受欢迎程度在稳步上升，VuePress 已经站在了一个巨人的肩膀上，并且有很大的增长潜力！

这本快速入门指南将帮助您在短时间内开始使用 VuePress！

本书适合的读者

本书适用于希望学习如何在 VuePress 中构建静态站点的任何人。所有内容都由 VuePress 呈现为 HTML，然后作为 SPA 执行。这意味着一切都可以快速运行并在瞬间加载。

如果您是 JavaScript 开发人员或希望专门研究 Vue.js，VuePress 对您来说可能是一个方便的工具。本书将帮助您了解 VuePress 的功能和方法，以帮助您适应 Vue.js 的操作方式。此外，如果您希望使用 Markdown 创建一个简单的站点，比如为现有或即将推出的项目创建一个文档站点，VuePress 可能是完美的解决方案。在这种情况下，这本快速入门指南就是您掌握 VuePress 所需的全部。

此外，如果您只是想学习一些关于静态站点和静态站点生成器的知识，那么这本书也适合您！

本书涵盖的内容

第一章《静态站点生成器和 VuePress 简介》向读者介绍了静态站点生成器，如 Jekyll、Hugo 和 Hexo。在特别讨论 VuePress 之前，本章还将讨论与静态站点生成器相关的各种优势和可能的缺点。

第二章《开始使用 VuePress》介绍了 VuePress 的大致情况。本章将涵盖诸如对 Vue.js 的基本理解、VuePress 是什么、它能做什么（以及不能做什么），以及如何在 VuePress 中开始的概念。此外，本章还介绍了 VuePress 的全局级别和依赖项安装。

第三章《VuePress 开发-初步步骤》包括了与 VuePres 配置数值相关的笔记，包括基本级别和构建流水线。除此之外，本章还包括了 VuePress 中的资源处理和 URL 结构。

第四章《在 VuePress 中创建网站》是我们开始实际网站开发的地方！本章包括了关于如何在 VuePress 中构建关于咖啡的静态网站的逐步教程。该网站的代码（Markdown 和渲染的 HTML）可以在本书的 GitHub 存储库中找到。

第五章《在 VuePress 中使用 Markdown》涵盖了 VuePress 中的 Markdown 使用。如果您对 Markdown 不熟悉，本章还包括了对其语法和格式的简要介绍，以及如何在 VuePress 中使用 Markdown。

第六章《在 VuePress 中进行主题开发》涉及 VuePress 中的主题开发。本章讨论了默认主题定制、导航栏和侧边栏设置、Git 集成以及自定义主题开发等主题。

第七章《在 VuePress 中做更多》以讨论 VuePress 中的国际化开始。它还教你如何在 VuePress 中本地化你的网站，然后讨论了 VuePress 的增长潜力、未来路线图以及与 VuePress 相关的其他因素。

第八章《将 VuePress 部署到网络上》涵盖了将 VuePress 部署到 Heroku、Netlify 和 Surge.sh 等托管提供商的远程服务器上。本章采用了详细的逐步方法，以帮助您轻松部署 VuePress 网站。

为了充分利用本书

以下技能、工具和实用程序可能会对您有所帮助，并帮助您充分利用本书：

• 工作站：显然，为了真正学习 VuePress 开发，您需要一台计算机，无论是笔记本还是台式机。如果您的计算机内存不多，也不用担心；VuePress 对资源使用并不是很大。

• 基本编码技能：您需要对 JavaScript 和 Vue 有基本的了解。如果没有，您可能仍然能够使用 VuePress，尽管需要额外的时间。然而，为了在 VuePress 中构建合法的网站，肯定需要对 Markdown 有一定的了解。

• 代码编辑器：建议使用一个好的代码编辑器来更好地格式化您的代码和文件。作者通常使用 Visual Studio Code，但您可以选择任何您喜欢的免费或付费编辑器。

• Node.js 和 npm：运行 VuePress 需要 Node.js 8+。安装方法在本书的第二章中有介绍。

• 互联网连接和网络浏览器：这个显而易见！没有浏览器和互联网，您无法构建和部署网站。

下载示例代码文件

您可以从您在www.packt.com的账户中下载本书的示例代码文件。如果您在其他地方购买了本书，您可以访问www.packt.com/support注册并直接将文件发送到您的邮箱。

您可以按照以下步骤下载代码文件：

1. 在www.packt.com上登录或注册。

2. 选择“支持”选项卡。

3. 点击“代码下载和勘误”。

4. 在搜索框中输入书名，并按照屏幕上的说明进行操作。

下载文件后，请确保使用最新版本的解压软件解压文件夹：

• WinRAR/7-Zip 适用于 Windows

• Zipeg/iZip/UnRarX 适用于 Mac

• 7-Zip/PeaZip 适用于 Linux

该书的代码捆绑包也托管在 GitHub 上，网址为github.com/PacktPublishing/VuePress-Quick-Start-Guide。如果代码有更新，将在现有的 GitHub 存储库上进行更新。

我们还有来自我们丰富的图书和视频目录的其他代码捆绑包，可在github.com/PacktPublishing/上找到。去看看吧！

下载彩色图片

我们还提供了一个 PDF 文件，其中包含本书中使用的屏幕截图/图表的彩色图像。您可以在这里下载：www.packtpub.com/sites/default/files/downloads/9781789535754_ColorImages.pdf。

使用的约定

本书中使用了许多文本约定。

CodeInText：表示文本中的代码单词，数据库表名，文件夹名，文件名，文件扩展名，路径名，虚拟 URL，用户输入和 Twitter 句柄。这是一个例子：“将下载的WebStorm-10*.dmg磁盘映像文件挂载为系统中的另一个磁盘。”

代码块设置如下：

module
    .exports = {
        head: [
            [ ... ]
        ]
    }

任何命令行输入或输出都是这样写的：

**git add --all**
**git commit -m "initial commit"**
**git push -u origin master** 

粗体：表示一个新术语，一个重要单词，或者您在屏幕上看到的单词。例如，菜单或对话框中的单词会在文本中出现。这是一个例子：“从管理面板中选择系统信息。”

警告或重要提示会出现在这样的地方。提示和技巧会出现在这样的地方。

第一章：介绍静态网站生成器和 VuePress

在网页开发的早期，所有网页都是基于 HTML 和 CSS 的。一切都是静态的，内容管理系统等概念是闻所未闻的。动态数据库驱动的应用程序也是相当晚期才出现的。

然而，随着 WordPress 和 Drupal 等内容管理系统的出现，网站开发开始加快了步伐。静态网站和页面被动态查询驱动的页面所取代，这些页面从后端数据库获取数据，并将数据写入后端数据库。当然，这样做可以更好地控制和更好地组织内容。

与这种动态数据库驱动的内容管理系统相关的优势是很多的。首先，你可以按自己的喜好呈现和存储你的内容！你可以拥有多个用户帐户，每个帐户都有自己的设置，自定义后端和前端，等等。

此外，对于最终用户来说，基于数据库驱动的动态网站管理程序可以提供更容易访问和用户友好的界面。

说到这一点，静态网站生成器又是什么呢？最近，许多新的静态网站生成器正在崭露头角并获得动力。它们有特定的用途吗？更重要的是，当我们说“静态网站生成器”时，我们到底是什么意思？

在本书的过程中，我们将学习 VuePress，这是一个令人兴奋和有用的工具，可以帮助您在几分钟内生成快速易操作的网页。我们将探讨它的各种功能、能力、限制和依赖，以及我们如何充分利用它，比如通过自定义主题、扩展、配置等等！

VuePress 在静态网站生成器的世界中仍然可以说是相对较新的，尽管它已经存在了一段时间。对于任何熟悉 JavaScript（JS）的人来说，Vue.js 肯定不是一个陌生的名字。这是一个 JS 框架，每天都在吸引着忠实的追随者。以下是 Vue.js 的简要概述。

以下是本章我们将涵盖的一些主题：

• 什么是 Vue.js？

• 什么是静态网站生成器？

• 静态网站生成器的优缺点

• 一些主要的静态网站生成器及其与 VuePress 的比较

• 什么是 VuePress？

• 为什么要使用 VuePress？

Vue.js 到底是什么？

Vue.js 是一个 JS 框架，可以让你构建用户界面。与许多其他庞大的 JS 框架不同，Vue 可以用来创建特定内容的单页面 Web 应用程序。它可以与其他库和项目集成，以满足你的需求。

详细讨论 Vue.js 显然超出了本书的范围。值得一提的是，Vue.js 是一个更专注于视图方面的 JS 框架——它是渐进式的，开源的，并且得到了忠实的社区支持。它可以被适应为以你希望的方式呈现你的网页和数据！

正如我们所看到的，Vue.js 在 JS 框架的世界中并不是一个小角色。因此，VuePress 有一个非常坚实的基础。但即使你不熟悉 VuePress，你也可以在阅读本书的过程中掌握它。

然而，对于那些仍然在想为什么像 VuePress 这样的东西值得麻烦，以及与 VuePress 等静态站点生成器相关的交易是什么，我们应该首先了解一些与这类站点生成器相关的基本信息。

什么是静态站点生成器？

因此，在继续之前，让我们首先简要了解静态站点生成器的概念。当我们说VuePress 是一个静态站点生成器时，我们是什么意思呢？

简而言之，静态站点生成器做的就是其名字所暗示的——它生成一组静态的网页。因此，一旦部署，静态站点生成器可以快速地动态生成网页。

大多数静态站点生成器通过一种非常简化的文件结构来工作。你会得到一组 HTML 文件，再加上一些 CSS 样式表来更好地呈现内容，就是这样。除此之外，我们只需要一组 JS 文件。没有复杂的插件、数据库或额外的内容管理选项。

为了更好地理解静态站点生成器（如 VuePress）的运作方式，我们可以将它们与基于数据库驱动的动态内容管理系统进行比较，比如 WordPress。

将静态站点生成器与动态站点生成器进行比较——方法论上的差异

WordPress，或者任何其他基于动态数据库的 CMS，究竟是如何工作的呢？

当用户访问特定的 WordPress 网站时，浏览器会向托管该站点的服务器发送请求。然后，WordPress 分析请求，并根据此准备数据。这可能意味着加载给定的帖子以及其媒体元素，显示评论，查询帖子的元数据等。为了获取此类信息，WordPress 需要查询并从其数据库服务器中提取数据。

因此，实际上，我们在这里采用了三步方法：

1. 用户或客户端向 WordPress 服务器发出请求

2. WordPress 查询并从其数据库中提取所需数据以完成请求

3. 所请求的信息呈现给用户

现在，如果我们去除对数据库的依赖呢？如果我们绕过所有不需要的代码和方法，只是以静态形式生成页面呢？当然，我们可能无法展示复杂的操作，例如自定义插件功能，电子商务集成等。但我们将完全克服上一个示例中的第二步，如下所示：

1. 用户向服务器发出请求

2. CMS 根据请求向用户呈现静态页面

通过这样做，我们在某种程度上加快了整个网站的性能。此外，由于没有对数据库的重复查询，我们还减轻了服务器负载。

这是动态内容管理系统和静态站点生成器之间的主要区别。虽然支持者可以就双方进行辩论，但基本区别在于工作方式。

静态站点生成器的优势

现在我们已经看到了像 VuePress 这样的工具与 WordPress 之类的工具有何不同，使用静态站点生成器工作流程有什么好处？简而言之，静态站点生成器（如 VuePress）有什么好处？

首先，这种静态站点生成器在运行时消耗的资源要少得多。您可以在具有比动态内容管理系统驱动的网站所需内存更少的服务器上运行使用生成器构建的博客或网站，例如 VuePress。此外，由于没有数据库或自定义数据查询需要处理，因此磁盘空间和带宽消耗也相对较少。

事实上，众所周知，您甚至可以在几兆字节的空间中部署和运行个人博客使用静态站点生成器！其他所有条件不变（视频、图片和博客文章），缺少数据库确实在这里创造了一个非常轻盈的氛围，操作速度更快。

静态站点生成器几乎总是比动态内容管理系统更快。事实上，像 VuePress 这样的静态站点生成器一旦调用，就可以作为单页面应用运行。这意味着不会有重复的查询或调用来加载页面。一切都可以立即加载！正如您可能已经意识到的那样，在互联网上，速度和页面加载时间非常重要，因为人们往往注意力不集中，耐心也不足。

此外，由于谷歌和其他搜索引擎通常将页面加载时间视为排名因素，静态站点生成器默认情况下对搜索引擎友好。当然，您仍然需要处理元数据、站点地图等，但基本的担忧“我的网站加载慢”将被解除。通常，像 VuePress 这样的单页面应用甚至不需要单独的缓存机制。

静态网站往往比动态网站更安全是一个常见的观念。原因在这里非常明显——静态网站没有数百行 PHP（或任何其他语言）代码、数据库和其他可能被黑客攻击的内容。您不必担心 WordPress 或 Drupal 版本过时。

同样，几乎没有糟糕编码或恶意插件或主题破坏您的辛勤工作的威胁。静态站点生成器大部分数据以 HTML、CSS 和偶尔的 JS 文件的形式存储。除了暴力破解密码，糟糕的代码几乎没有可能导致任何恶意软件或安全威胁。代码注入、隐藏在服务器端文件中的恶意代码、损坏的数据库条目等等，在这里都是过去的事情。

对于高级用户，静态站点生成器提供了更大的定制和个性化空间。不喜欢某个功能？希望调整一些东西以符合您的喜好？代码完全由您自定义，而且由于没有绝对要求拥有数据库或插件，您可以按照自己的意愿构建您的网站或博客！这是为什么许多高级用户倾向于静态站点生成器，特别是对于他们的个人项目和网站。

另一方面，这种高度定制化可能并不是每个人的菜。对于不太喜欢定制化的人来说，静态站点生成器可能会显得令人望而却步。但对于开发人员来说，这简直是天堂！

好吧，既然我们已经看到了这些优点，可以肯定的是，像 VuePress 这样的静态站点生成器是相当有能力的工具。加上速度和安全性的优势，你可以按照自己的喜好创建网站和页面，而不必担心动态数据库需求、安全插件、代码注入等等。

静态站点生成器的缺点

每件事都有好坏两面，静态站点生成器也不例外。

这种站点生成器最大的缺点是学习曲线陡峭。通常情况下，你需要调整工作环境才能安装站点生成器。正如我们将在接下来的章节中看到的，安装通常会很顺利，但你需要确保所有依赖和变量都得到充分满足。

对于初学者来说，这种方法通常太复杂了。如果你无法安装所有必需的框架和库，那么你很可能无法让静态站点生成器正常运行。

虽然静态站点生成器非常适合创建博客和基本网站，但并不是所有网站都适合使用它们。对于电子商务、复杂的数据库驱动内容网站和其他内容感知项目，静态站点生成器通常不是最佳选择。

值得一提的是，与 WordPress 或 Drupal 相比，大多数静态站点生成器相对较不为人知。这对于像 VuePress 这样的实体尤其如此。这意味着从另一个 CMS 迁移现有的博客或站点可能需要一些时间。

另一方面，将 VuePress 博客或站点迁移到另一个 CMS 可能会更加耗时。在成功迁移之前，你几乎肯定需要处理一些代码并调整一些设置。但是，从 WordPress 迁移到 Drupal，或者反之，通常非常容易，因为有各种免费和付费插件可供使用。

这表明静态站点生成器有其优缺点。但对于这些生成器的用途——博客和简单静态网站项目的创建，它们几乎可以说是完美的。此外，由于目标受众包括了知道自己在做什么的开发人员和爱好者，而不是需要拖放解决方案的最终用户，静态站点生成器不需要迎合所有人。这使得未来的开发路线图更加精简和集中。

但现在我们已经谈了很多关于静态站点生成器，我们有哪些选择呢？与其他任何事物一样，你可以选择很多生成器。在本书中，我们将完全专注于 VuePress。

然而，我们必须牢记 VuePress 是一个相对较新的平台，仍在积极开发中。因此，为了充分了解 VuePress 的重要性和用法，我们至少需要了解一些其他静态站点生成器。这将帮助我们更好地理解 VuePress 的重要性，并展示 VuePress 的特殊之处。我们不会详细介绍各种静态站点生成器，只会简单提及一些最流行的生成器。

此外，虽然本书的范围实际上超出了对多个静态站点生成器进行详细比较的范围，但我们仍将说明 VuePress 与某些其他静态站点生成器相比的情况，以便已经熟悉某个静态站点生成器（比如 Jekyll）的开发人员或读者更好地评估 VuePress 可以期待什么。

一些主要的静态站点生成器

现在是时候看一下一些主要的静态站点生成器了。

我们将主要关注那些没有外部数据库并且在性质或功能上类似于 VuePress 的生成器。

Jekyll

我们名单上的第一个生成器已经存在了相当长的时间。事实上，Jekyll 在静态站点生成器的世界中已经成为一个常见的名字。它是一个简单易用的工具，可以直接使用，并实现一个简单的想法——将您的纯文本文件转换为作为静态站点运行的博客或网站。

Jekyll 不依赖于数据库，并消除了大多数不需要的动态内容管理系统的功能。您可以使用 Markdown、Liquid 或其他格式编写内容。由于所有内容都以静态页面的形式呈现，速度提升也是相当可观的。

与 VuePress 相比，Jekyll 有一个非常明显的优势：它具有博客意识，并允许您轻松地从其他平台迁移您的博客。通过博客意识，我们指的是 Jekyll 能够很好地识别类别、标签和其他博客特定的实体或元数据。正如我们将在本书的第四章中学到的，VuePress 默认情况下并不完全具有博客意识，因此您需要额外工作才能在 VuePress 中获得与 Jekyll 开箱即用相同的结果。

也就是说，Jekyll 不依赖于 Vue.js，实际上主要基于 Ruby。对于 JS 程序员来说，调整 Jekyll 有时是一个挑战。

Jekyll 的主页可以在jekyllrb.com找到。

Hugo

Hugo 是另一个非常受欢迎且完全开源的静态网站生成器。它使用 Apache 许可证，并基于 Go 语言。因此，对于使用或熟悉 Go 编程语言的程序员来说，Hugo 通常是静态网站生成器领域的事实选择。

但这并不是 Hugo 的最终卖点。与许多其他静态网站生成器不同，Hugo 还可以很好地与大多数动态 API（自定义内容、分类、菜单等）配合使用。在这方面，Hugo 更像是静态网站生成器和动态 CMS 之间的混合体。此外，Hugo 还配备了用于 SEO 和网站分析的模板。此外，Hugo 还有各种自定义短代码和大量的主题可供选择，以便充分利用您的网站或博客。

然而，对于一些寻求极简主义并且不想使用无数短代码或 API 的人来说，Hugo 可能会显得过于复杂。它更像是初学者友好的 CMS 和开发者友好的网站生成器之间的妥协。学习曲线也不是很困难。

Hugo 的主页可以在gohugo.io找到。

Gatsby

现在，最后，让我们来看一些基于 JS 的网站生成器！

Gatsby 是一个基于 JS 的静态网站生成器，使用 React 作为其模板引擎。显而易见的部分？由于 React 的流行，Gatsby 在其社区中自然拥有大量忠实用户。这里的工作方式很简单：Gatsby 可以从大量来源获取数据，然后处理数据以生成静态网页，这些网页可以托管在您选择的平台上。

因此，如果您的数据以无头 CMS、数据库、自定义动态 API、JSON 甚至动态内容管理系统（如 WordPress 或 Drupal）的形式存在，您可以使用 Gatsby 处理这些数据，然后将其导出为静态页面。换句话说，如果您希望创建设备感知型渐进式 Web 应用程序，并且正在使用 React，Gatsby 是理想的工具。Gatsby 就像一个 JS 框架，可以根据项目的需求进行扩展。但是，与 VuePress 相比，Gatsby 在某种程度上受限于依赖 GraphQL 和 React。

Gatsby 主页可在www.gatsbyjs.org找到。

Hexo

Hexo 是一个静态网站生成器，主要以其创建博客、文档网站和其他需要频繁更新内容的项目的能力而自豪。它有自己的插件系统，甚至可以使用具有类似渊源的其他项目的插件。

Hexo 也基于 JS，在遗传学上与 VuePress 非常接近。但是，它并不完全依赖于 Vue.js。事实上，Hexo 与 VuePress 最大最明显的区别在于前者的主题架构是基于字符串的，而不是源自 Vue。

Hexo 主页可在hexo.io找到。

Nuxt.js

我们列表中的最后一个条目 Nuxt.js 与 VuePress 有很多共同之处。与 VuePress 一样，Nuxt.js 也基于 JS，并使用 Vue.js 作为其模板引擎。事实上，Nuxt.js 本身就是一个非常强大的工具包，几乎可以完成 VuePress 所宣称的大部分功能。

因此，如果 Nuxt 是我们问题的答案，那么为什么还需要 VuePress 呢？原因很简单——Nuxt.js 主要用于基于 Vue.js 创建应用程序，但对于生成静态网站和博客，VuePress 是更好的选择！因此，VuePress 非常适合创建以内容为中心的网站和实体，如博客、文档网站等。Nuxt.js 通常处理基于 Vue.js 的应用程序，而不是以内容为中心的网站。

Nuxt.js 的主页可以在nuxtjs.org找到。

好了，我们现在已经讨论了一些主要的静态站点生成器。那么，VuePress 有何特别之处呢？

为什么要使用 VuePress？

根据我们对其他静态站点生成器的简要讨论，很明显 VuePress 可以在其他静态站点生成器可能不够的情况下证明其有用。例如，请考虑以下情况。

如果您正在使用 JS，VuePress 是一个不错的选择。现在越来越多的开发人员转向 JS，因为它非常灵活、可扩展，并且可以轻松完成大型项目。此外，如果您不喜欢将 React 或 AngularJS 作为默认框架，Vue.js 在实力和功能方面是一个自然的选择。

如果您不需要创建仅应用程序项目，但需要用于构建内容为中心的网站的东西，VuePress 是一个值得选择的选项。

由于 VuePress 的主题引擎基于 Vue 本身，如果您刚开始使用 Vue.js 框架，它可能会成为一个很好的学习工具。

好了，现在我们已经了解了 VuePress 是什么，静态站点生成器可以做什么，以及为什么我们应该使用它。现在是为即将到来的事情做好准备的绝佳时机——VuePress 开发、定制、部署等等！

开始使用 VuePress 的入门

在接下来的章节中，我们将深入讨论与 VuePress 相关的概念。首先，我们将从安装开始，然后转向基本定制、调整、开始博客或网站、自定义主题等。

但是正如您所看到的，安装显然是第一步。VuePress 在磁盘空间、带宽或内存方面并没有巨大的需求。事实上，您甚至可以在共享托管环境中运行它，假设您的网络托管提供商支持所需的 JS 脚本（尽管在实际情况下，目前并没有多少共享主机可以这样做）。

如果您熟悉 JS 开发，您可能已经知道您需要什么以及如何获得它。很有可能您已经设置了这样的环境。为了帮助您为即将到来的事情做好准备，这里是运行 VuePress 所需的基本概述：

这里最大的先决条件是您需要 Node.js 版本 8 或更高版本。它将与 npm 捆绑在一起，所以请确保您的环境具有正确版本的 Node.js。

除此之外，要求很简单。对于生产网站，使用一些服务器端缓存总是一个好主意。正如前面所指出的，静态站点生成器如 VuePress 在其自身速度上相当快，因此不需要自定义编码的缓存系统。

服务器端缓存机制可以进一步提高网站的性能。

目前就是这些了。我们将把编码细节和其他输入留到接下来的章节。

摘要

在本章中，我们讨论了很多内容。我们了解了静态站点生成器，它们是什么，为什么我们应该使用它们，以及它们提供的优缺点。虽然我们不能在每种情况下都使用静态站点生成器，但在各种类型的网站、博客和其他项目中，这些生成器都可以证明是有用的。

现在，在静态站点生成器的世界中，我们有很多选择。然而，VuePress 对于希望创建内容依赖型网站并将其呈现为单页面应用以实现更快页面加载的人来说是一个不错的选择。VuePress 依赖于 Vue.js，因此，对 JS 及其框架方法论的一些了解对于帮助你充分利用 VuePress 是必不可少的。

随着我们在本书中的进展，我们将更详细地了解 VuePress。在接下来的章节中，我们将花一些时间熟悉 Vue.js 及其功能。这将帮助那些不是专家的读者来使用 Vue.js。

此后，我们将继续学习 VuePress，从安装、操作环境、设置、配置等方面开始。更重要的是，我们还将介绍安全步骤，以确保我们的生产网站安全无虞。在下一章中见到你，我们将开始学习 VuePress 开发的旅程！

第二章：开始使用 VuePress

在[第一章]（4e1526aa-d994-42d8-9a18-12374ba932a0.xhtml）中，介绍静态站点生成器和 VuePress，我们了解了静态站点生成器是什么，以及它们可能的优势，以及为什么我们应该使用它们。此外，我们还介绍了一些主要的静态站点生成器，以及 Vue.js。

在这一章中，是时候把我们所有的注意力转向 Vue.js 和 VuePress 了。当然，如果您对 VuePress 的工作方式不熟悉，您可能目前感到有些畏惧。但不用担心，VuePress 的设置相当容易，甚至更容易掌握。很快您就会看到，VuePress 的设置绝对不是什么难事。

然而，为了正确设置和安装 VuePress 并确保满足所有依赖关系，我们首先需要花一些时间熟悉 Vue.js。这将帮助我们更好地理解为什么 VuePress 需要特定的系统设置才能工作，以及如何才能充分利用这个简单而迅速的站点生成器。

因此，是时候把我们的注意力转向 Vue.js 了。

在本章中，我们将讨论以下主题：

• 开始使用 VuePress

• 基本的 Vue.js 术语

• 将 Vue.js 与其他 JavaScript（JS）框架（如 React 或 Angular）进行比较

• 理解 VuePress 的方法论

• VuePress 的安装和基本配置

开始使用 Vue.js 和 VuePress

在我们转向 VuePress 及其与 Vue.js 的关联之前，让我们看看 Vue.js 是什么，以及它对我们有什么用处。

什么是 Vue.js？

简而言之，Vue.js 是一个主要用于构建用户界面的开源 JS 框架。它使用 MIT 许可证，这意味着您可以扩展其源代码并使用它构建新项目。

Vue.js 最大最明显的目标是成为固有可采用的。因此，如果您的项目使用其他 JS 库或框架，您不必放弃它们来使用 Vue.js——相反，您可以选择将其与您可能已经在使用的其他 JS 库或框架一起使用。

Vue.js 可以轻松驱动单页面应用程序，也可以作为 Web 应用程序框架。

那么，Vue.js 背后的重要之处是什么，使它与其他框架不同？Vue.js 的主要动机或灵感是简化 Web 开发。此外，它大多是非主观的，因此为开发提供了统一的一套方案。

因此，Vue.js 更多地面向用户界面（UI）开发。你可以将其核心组件嵌入到任何现有项目中，甚至可以利用构建工具和支持库来设置单页面应用程序。

所有 Vue 模板都是有效的 HTML，可以被任何现代 Web 浏览器读取和解析。这意味着你使用 Vue 构建的任何内容都可以轻松地在所有设备和浏览器上呈现。随着 VuePress 的进展，你会注意到 Vue 的这一特性是一个巨大的优势，可以帮助你避免许多兼容性问题。

现在，Vue 是如何工作的？实际上很简单。每当你更新 JS 对象时，Vue 都会更新视图。这种反应性的特性意味着输出会在进行更改时被渲染或重新渲染，而不是强制进行完全刷新。

一些基本的 Vue.js 术语

我们将在这里跳过有关 Vue.js 功能的详细学习，因为这超出了我们书籍的范围。要更好地了解 Vue.js 本身（而不是 VuePress），你可以查看有关该主题的任何出色的 Packt 图书。现在，我们只需要熟悉一些定义，这样当我们在 VuePress 中使用它们时，就会更容易记住。

我们已经了解到 Vue 模板遵循基于 HTML 的语法。现在，每个模板都可以附带组件。简单来说，组件是可重用代码块，用于扩展现有 HTML 元素的功能。

同样，Vue.js 有自己的应用过渡效果的方法。这可以以 CSS 过渡或 JS 挂钩的形式进行。在高级的 VuePress 项目中，你可能会发现自己集成自定义 JS 动画库以实现过渡效果。当然，这取决于你的项目性质，并不总是需要单页面应用程序或博客。

为什么不选择其他 JS 框架呢？

这一部分主要适用于那些已经具有 JS 背景并可能熟悉一两个 JS 框架的人。如果你是一个 JS 框架的初学者，而 Vue.js 是你第一个熟悉的框架，你可以跳过这部分。

然而，如果你已经了解了其他框架，你可能会想知道 Vue.js 能够提供什么其他框架不能提供的东西？

一些最流行的 JS 框架是 Angular 和 React，将在下一节中讨论。

Angular/AngularJS

与 Angular 相比，Vue 似乎并不那么受欢迎。在实际应用中，Angular 是这两者中更大的名字——它得到了 Google 的支持，非常容易上手，并且非常受欢迎，这意味着与之相关的文献丰富。

然而，Vue 也有自己的一些好处。首先，Angular 对应用程序结构有很强的看法——这对于初学者和希望遵循特定应用程序开发模式的开发人员来说是理想的。然而，Vue 提供了更大的灵活性和对项目的完全控制。这意味着您有更多的实验空间，因为 Vue 非常适用于各种用例。

Angular 使用双向数据绑定，而 Vue 依赖其组件之间的单向数据流。在实际应用中，AngularJS（不是 Angular）在应用程序规模和重要性增长时往往变得较慢。这是因为事务之间存在多个观察者。但是 Vue 和 Angular 都没有这个缺点。

有趣的是，在 Vue 中，没有一种正确的应用程序结构方式。这意味着您有更大的灵活性和控制。但是，作为缺点，这也意味着从 Vue 到其他框架（或反之）的移植有时可能会受到严重阻碍。另一方面，Angular 具有一套良好的结构规则，可以强制执行标准，但对于一些用户来说也可能显得非常限制。

这就是为什么 AngularJS 的学习曲线非常陡峭。开发人员必须牢记各种 API 标准。对于 Vue 编码者来说，这些要求数量较少。

React

React 和 Vue 有很多共同之处。很容易就可以为这些框架中的任何一个进行辩论——虽然 React 旨在扩展，并且从各个标准来看都是一个很好的框架，但对于许多用户来说，Vue 的学习曲线较为平缓。

话虽如此，Vue 目前在某些方面落后于 React。React 允许您为 iOS 和 Android 编写本机渲染的应用程序。这意味着您的应用程序可以在多个平台上无缝运行。Vue 目前正试图通过 Weex 来实现相同的功能，Weex 是 Apache 基金会目前正在孵化的项目。在weex.apache.org/了解更多信息。

Weex 仍处于测试阶段，并没有像 React 那样被广泛采用。这使得 React 在 Vue 方面具有明显优势。

其他方面

Ember，另一个声誉良好的 JS 框架，与 Vue 的不同之处在于在 Ember 中，您需要为所有内容手动声明依赖项，并将其全部包装在对象中。在 Vue 中，您也可以利用普通的 JS 对象。与 Ember 相比，Vue 在性能方面显著更快更好，简单地因为 Vue 可以自动运行批量更新。

由 Google 支持的另一个 JS 框架 Polymer 与 Vue 的不同之处在于前者需要基本的 polyfills 才能工作，而 Vue 不需要任何依赖项或 polyfills（除非您的目标是较旧的 Web 浏览器）。

因此，我们可以看到与其他 JS 框架相比，Vue 有自己的几个优势和好处。如果您是 React 或 Angular 用户，您可能已经评估了 Vue 与其他框架的不同之处。它简单，允许组件的重复使用，并且消耗更少的资源。

Vue.js 与 VuePress 有什么关系？

VuePress 自称为“Vue 动力”，这正是两者之间的关系。Vue.js 驱动 VuePress，换句话说，VuePress 基于 Vue.js。

这意味着您所读到的关于 Vue.js 的所有上述功能都可以被 VuePress 用户使用。因此，VuePress 可以用来快速生成单页面应用程序，这些应用程序在 Web 浏览器中渲染非常快，并且不会对服务器资源造成压力。Vue.js 是 VuePress 的支柱意味着以下几点：

• VuePress 操作起来快速而敏捷。

• 它可以快速加载页面和单页面应用程序（SPA）。

• 它不需要大量的内存来运行。

了解 VuePress 的特殊之处

VuePress 在运行后会生成静态形式的预渲染 HTML，之后它可以作为 SPA 运行，因此对于每个简单的查询都不需要重复调用服务器。

这就是 VuePress 的特殊之处。与其他网站创建工具和平台不同，VuePress 不会占用大量资源。它是一个简单的站点生成器，设置最少。正如我们将在本章后面看到的那样，设置 VuePress 不需要复杂的火箭科学或服务器管理知识。您可以在几分钟内完成设置，即使是 JS 的基本学习者也可以开始使用。

此外，如果你是 Markdown 用户，VuePress 对你来说可能会有特殊用途，因为它的整个项目结构都是基于 Markdown 的。事实上，我们将在本书的后面章节中介绍 VuePress 中的 Markdown 扩展，以帮助你更好地了解它。

总的来说，如果你希望利用 Vue 所提供的优势，VuePress 就是你应该使用的。通过合理使用 Vue 组件，以及与 Markdown 扩展和自定义模板的结合，VuePress 可以作为完美的、高度可定制的、多功能的静态站点生成器，适用于各种用户。

VuePress 是如何工作的？

在最基本的层面上，每个 VuePress 网站都有两个主要部分：

• 一个具有基于 Vue 的主题系统的静态站点生成器

• 一个默认的 VuePress 主题，理想情况下适用于文档站点，但也可以轻松定制为其他用途

现在，VuePress 生成的每个页面都是静态 HTML，并且完全优化了搜索引擎。然而，在页面加载时，静态内容会被转换成 SPA，以实现更快的性能。

现在，正如我们所看到的，每个 SPA 都由 Vue 驱动。Vue 使用 Vue 路由器，它与 Vue.js 核心无缝集成，有助于使 HTML5 友好的 SPA 成为一项简单的任务。有关 vue-router 的更多信息，请访问github.com/vuejs/vue-router。

最终，为了打包脚本并组合代码结构，VuePress 依赖于 webpack。这是一个流行的工具，可以用来将脚本、代码、图像和其他媒体捆绑成一个统一的单元，以在现代 Web 浏览器中显示，如下所示：

你可以在webpack.js.org了解更多关于 webpack 的信息。

由于 VuePress 使用 Markdown，它依赖于 Markdown——也就是说，它将 Markdown 文件编译成 HTML。你也可以在你的内容中嵌入动态内容，并使用 Markdown 作为代码——它可以处理两者。有关更多信息，请访问markdown-it.github.io。

因此，我们可以看到 VuePress 使用了所有免费可用的标准工具和服务。换句话说，你不必依赖复杂的专有软件来学习 VuePress 并使用它构建你的项目。

VuePress 能做什么？

然而，一个重要的问题是，VuePress 能实现什么？

VuePress 带有内置的 Markdown 扩展和在 Markdown 中利用 Vue 的能力。这意味着它非常适合想要快速生成网站并将内容上线的人。此外，由于其主题系统是基于 Vue 的，它对于想要使用 Vue.js 开发网站的人来说是一个很好的起点。

VuePress 提供多种语言支持，并且还具有 Google Analytics 集成。默认的 VuePress 主题非常适合文档网站和项目。它完全响应式和移动友好，具有原生的基于标题的搜索，甚至还有导航菜单和侧边栏。这意味着 VuePress 非常适合基本的网站开发、Web 应用程序和文档项目。

然而，不足之处在于，VuePress 仍然没有完美的博客支持。您可以用它来写博客，但它没有开箱即用的博客功能。同样，虽然您可以调用和使用任何您喜欢的 Vue.js 扩展，但 VuePress 本身没有任何插件。

这意味着 VuePress 是一个轻量级的站点生成器，适用于普通的网页开发项目，而不一定适用于更庞大和高度专业的项目。

那么其他选择呢？

你可能会想：为什么我们要使用 VuePress，而不是其他东西呢？

首先，VuePress 是一个基于 Vue 的令人兴奋的新项目，可以提供很好的学习和开发体验。

与许多其他类似工具不同，VuePress 完全专注于静态网站和单页应用程序。例如，虽然 Nuxt 与 VuePress 非常相似，但前者完全专注于构建应用程序。另一方面，VuePress 具有使其成为在线文档项目和其他静态站点的完美工具的功能。

说到文档，像 Docsify 和 Docute 这样的解决方案也是不错的选择，因为它们都基于 Vue，并且具有帮助您轻松编写技术文档的功能。然而，Docsify 和 Docute 都是运行时驱动的。现在已经普遍知道，运行时驱动的应用在搜索引擎优化方面往往表现不佳。而 VuePress 在 SEO 方面也做得很好。

同样，VuePress 也比 Hexo 更具优势。许多人使用 Hexo（甚至许多 Vue.js 用户倾向于依赖 Hexo）。但是 Hexo 对 Markdown 的渲染不如 VuePress 灵活多变，这是 VuePress 胜过 Hexo 的明显优势。

正如我们所看到的，尽管 VuePress 相对较新且相对不太为人所知，但它具有一套很好的功能，可以成为许多用户的不错选择。

现在我们已经阅读并了解了 VuePress 的工作原理以及它所提供的功能，我们可以将注意力转向实际使用 VuePress 进行设置。

开始使用 VuePress

现在是时候开始了。我们现在已经了解了 Vue.js 是什么以及它所提供的主要功能。此外，我们还了解了 VuePress 的作用，它与 Vue.js 的关系以及它的主要用途和功能。在这一点上，我们已经准备好开始使用 VuePress，并朝着使用它创建令人惊叹的网络项目的方向前进。

自然而然的，第一步将是安装和设置 VuePress，使其可以运行，并准备好供使用。

安装

必须注意的是，VuePress 需要 Node.js 版本 8（或更高版本）才能运行，因此您必须在服务器上安装 Node.js 才能运行 VuePress。

VuePress 在服务器端需要 Node.js 8 或更高版本。

有两种流行的安装 VuePress 的方式。如果 VuePress 是您唯一或主要使用的工具，您可以选择全局安装它。或者，如果您在更大的工作流中使用 VuePress，您可以选择将其作为现有项目的依赖项进行安装。

考虑到这是一个快速入门指南，旨在帮助您快速了解 VuePress，将 VuePress 用于更大更复杂的现有项目技术上超出了本书的范围。尽管如此，我们将介绍两种安装类型的命令，以帮助您了解两者之间的主要区别。

全局安装 VuePress

有两种方式可以安装 VuePress：

• 使用 npm

• 使用 Yarn

npm 是 Node.js 默认的工具，大多数 Node.js 开发人员对其能力非常熟悉。Yarn 也是 JS 开发人员非常流行的依赖管理系统。它可以与各种 JS 框架和库一起使用，并且非常快速，因为它可以缓存您下载的每个软件包，这样就不需要重新下载任何内容。

如果您一直在关注 JS 开发，您可能已经了解 npm 和 Yarn。就全局安装 VuePress 而言，使用其中一个并没有明显的优势——在很大程度上，这是个人偏好的问题。然而，建议在现有项目中安装 VuePress 时避免使用 npm。

全局安装 VuePress 的方法如下：

# installing vuepress globally
 yarn global add vuepress
 # creating our readme file
 echo '# My VuePress Site' > README.md
 # ready to develop
 vuepress dev
 # building it
 vuepress build

这个例子有四个简单的步骤，您可以用它们来安装 VuePress。没有别的。现在让我们更详细地分析每个步骤，从第一个命令开始：

yarn global add vuepress

上述命令将全局安装 VuePress。请注意，它使用 Yarn。对于 npm 用户，语法看起来会像下面这样：

npm install -g vuepress

第二个命令如下，将为我们创建一个 Markdown 文件：

echo '# My VuePress Site' > README.md

第三个命令是最终启动 VuePress，如下所示：

vuepress dev

最后，构建命令如下所示：

vuepress build

就这样。您已成功在服务器或本地主机上全局安装了 VuePress，并可以开始使用它构建下一个 Web 项目。当然，可能需要一些基本配置来进一步完善您的网站，但我们可以稍后再谈。

在现有项目中安装 VuePress

在现有项目中将 VuePress 安装为依赖项是个好主意。请记住，VuePress 是一个相对较新的实体，需要对 JS 开发有相当的了解，您可能已经在运行各种自己的 JS 项目。在这种情况下，在现有项目中将 VuePress 作为本地依赖项意味着您可以利用其无数的功能和能力来为您的项目服务——比如，为您的项目渲染单页面应用，或者维护内容等。

VuePress 作为本地依赖项的安装非常简单。您只需要输入相关的 Yarn 命令，如下所示：

yarn add -D vuepress

或者，对于 npm 用户，命令将如下所示：

npm install -D vuepress

记得我之前提到过在现有项目中安装 VuePress 时要避免使用 npm 吗？这是因为如果您的项目已经将 Webpack 3.x 作为依赖项，npm 将无法生成 VuePress 的正确依赖树或结构。值得注意的是，Webpack 非常流行，被多个 JS 项目使用。因此，在实际应用中，当将 VuePress 作为本地依赖项添加时，您应该考虑使用 Yarn。

当将 VuePress 作为 webpack 3.x 所需的本地依赖项添加时，您应该考虑使用 Yarn。

在此之后，您需要创建一个 docs 目录，如下所示：

mkdir docs

然后，就像以前一样，我们将为我们的项目创建 Markdown 文件：

echo '# My VuePress Site' > README.md

就是这样！

在这个阶段，您可能希望向您的package.json文件中添加一些脚本。值得注意的是，脚本的要求显然取决于您的项目目的和工作流程。以下是一些示例：

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

现在，要编写脚本，请使用以下命令：

yarn docs:dev

或者，对于 npm 用户，命令将如下所示：

npm run docs:dev

要为您的项目生成静态资产，请输入此命令：

yarn docs:build

对于 npm 用户，请使用以下命令：

npm run docs:build

生成的资产和构建的静态文件可以部署到任何服务器。这个话题需要单独讨论，我们将在后面的章节中随着 VuePress 部署的进展而重新讨论它。

现在，您应该能够做到以下几点：

• 使用 Yarn 或 npm 安装 VuePress

• 全局安装 VuePress 或将其作为现有包的依赖项安装

理解 VuePress 配置

到目前为止，我们已经学会了如何安装 VuePress。然而，为了有效地使用 VuePress（或者任何 JS 项目），首先要理解配置结构是很重要的。

VuePress 配置非常简单和直观。安装后，您会注意到 VuePress 项目中有一个 docs 目录，该目录将包含您在安装过程中创建的readme.md Markdown 文件。除此之外，您可能还会注意到一个 package.json 文件。

现在，您应该在 docs 目录内创建一个.vuepress目录。这个.vuepress目录是您的config.js文件所在的地方——正如任何 JS 开发人员所能告诉您的那样，这个文件应该导出一个 JS 对象。

例如，要向您的 VuePress 站点添加标题和描述，您的config.js文件将导出以下内容：

module.exports = {
    title: 'My Fancy Title',
    description: 'my fancy vuepress site'
    }

上述代码将为由您的 VuePress 安装呈现的最终页面导出一个标题和描述。

以下图表显示了默认 VuePress 目录结构的样子：

值得注意的是，您也可以使用其他配置格式，而不仅仅使用config.js。例如，您可以使用 YAML（然后会有一个config.yml文件）或 TOML（使用config.tml文件）。

然而，考虑到大多数 VuePress 用户对 Vue.js 都有相当熟悉的经验，并且更习惯使用config.js作为默认格式，我们将在本书的整个过程中坚持使用它。

其他配置

VuePress 还允许您编辑主题配置以个性化您的网站。VuePress 自带了默认主题，可以进行调整和定制以满足您的需求。然而，我们将只在第六章 VuePress 中的主题开发 中专门讨论自定义主题开发时，才会转向主题配置和调整。

正如我们在本章前面讨论的那样，VuePress 可以用来生成单页面 Web 应用程序。这意味着您可以使用自定义钩子将应用程序级配置添加到您的 VuePress 项目中。如果您之前有 Vue.js 的经验，并希望从现有项目中导入或利用现有的 Vue.js 插件和组件，这将非常有用。

在这种情况下，您需要在.vuepress目录中添加一个额外的enhanceApp.js文件。在该文件中，您可以指定用于添加插件和注册组件的自定义钩子。.vuepress/enhanceApp.js文件的一般语法如下：

export default ({
Vue, 
options,
router,
siteData
}) => {
 // enhancements come here
}

请注意前面代码中每个元素所扮演的角色：

• Vue提到了您的VuePress应用程序使用的 Vue 版本

• options指定了 Vue 实例的选项

• router指定了路由器实例的选项

• siteData包含您的应用程序的元数据

请注意，如果您的应用程序不需要应用程序级增强，则不需要应用程序级增强。

您可以在官方文档中找到 VuePress 的所有配置引用的详细列表本身vuepress.vuejs.org/config/#basic-config。

总结

这就是本章的结束。到目前为止，我们已经涵盖了与 Vue.js 和 VuePress 相关的所有基本信息。我们还了解了 VuePress 是什么，它能做什么，它可以处理什么类型的项目、应用程序或网站，以及与同类产品相比如何表现。同样，我们还熟悉了一些关于 Vue.js 的基本知识，以及它的用途、能做什么等等。

除此之外，我们还介绍了如何安装和设置 VuePress。我们学习了如何在全局范围内安装 VuePress，以及在现有项目中安装为依赖项。我们涵盖了与基本 VuePress 配置文件相关的主题。

在下一章中，我们将把注意力转向 VuePress 开发。然而，与大规模的定制开发不同，我们首先将专注于资产处理和其他定制调用。这将使您能够了解和更好地理解 VuePress 的工作原理，以及您可以使用的一些编码技巧来充分利用它。之后，我们将开始使用 VuePress 创建一个实时网站，然后进行主题开发。

第三章：VuePress 开发 - 初步步骤

在第二章 开始使用 VuePress 中，我们介绍了 VuePress 的安装和设置。在这一点上，你已经学会了如何安装 VuePress，它的系统要求是什么，以及如何设置好 VuePress 以准备实际工作。

然而，安装 VuePress 只是第一步。为了构建一个功能完善的项目，并充分利用它，你需要学会如何更多地使用 VuePress。

这一章将帮助你实现这一点。

在这一章中，你将学习以下内容：

• VuePress 开发基础

• VuePress 的基本配置值

• VuePress 的浏览器配置值

• VuePress 的构建流程配置值

• VuePress 中的资产处理

• 处理图片、公共文件和 URL

VuePress 开发 - 入门

在这一章中，你将学习关于在 VuePress 中处理资产和处理文件和 URL 的概念。现在，由于 VuePress 是一个静态网站生成器，事情往往与你在 WordPress 等数据库驱动的内容管理系统中找到的有些不同。

考虑到在第四章 在 VuePress 中创建网站 中，我们将实际上使用 VuePress 设置一个演示网站，因此你需要对 VuePress 中如何处理文件和 URL 有一个很好的理解。第四章 在 VuePress 中创建网站 将帮助你规划网站或博客的完美结构。

VuePress 配置值

在继续之前，我们需要花一些时间确保我们理解 VuePress 通常支持的配置的性质。

VuePress 的基本配置值

首先，我们需要熟悉 VuePress 中使用的基本配置值。这个列表并不完整，你应该参考 VuePress 文档获取完整的列表，可能会跨越多个页面。

为了清晰起见，避免混淆，我们将在讨论自定义主题的章节中讨论与主题相关的配置。同样，我们将在有关 VuePress 中的 Markdown 的章节中讨论与 Markdown 相关的配置值。

标题

此值显示 VuePress 站点的标题。默认情况下，它被添加到站点上的所有页面，并显示在导航栏中，但您可以更改此功能：

Type: string
Default: undefined

描述

这显示了站点的元描述。因此，在页面 HTML 中，它在<meta>标签内呈现：

Type: string
Default: undefined

头部

这包括在 HTML 中呈现页面时在<head>标签内呈现的附加数据。通常，它采用在[和]方括号内封装的内容的合并形式。

基本语法如下：

module
    .exports = {
        head: [
            [ ... ]
        ]
    }

自然，头部配置是数组类型，其一般默认形式为[ ]（空数组）。

ga

此配置实体帮助您将 VuePress 站点与 Google Analytics 集成。如果您在 Web 开发领域活跃，您可能已经意识到 Google Analytics 可以为您的站点提供大量资源。因此，您只需将您的 Google Analytics ID 传递给此配置值，就可以了。

ga是数组类型，默认值为未定义，因为您需要将您的 Google Analytics ID 传递给它。

区域设置

此特定配置变量支持国际化和本地化；也就是说，与将站点翻译成其他语言的兼容性。由于我们已经有了一个专门讨论 VuePress 中国际化和本地化处理的章节，我们很快将详细讨论这个配置值。

默认值为未定义，接受的类型是此处所示格式的字符串对象：

{ [path: string]: Object }

shouldPrefetch

有时，一些文件倾向于附有预加载资源提示。shouldPrefetch函数处理这些限制和提示。

shouldPrefetch是函数类型，默认值为( ) => true格式。

对于我们所说的限制和提示感到困惑？嗯，Vue.js 有一种称为<link rel="preload">的资源提示。默认情况下，几乎所有要异步加载的资产都会被预取，以加快页面加载时间和性能。但是，如果您在带宽有限的较弱服务器上呢？预取所有内容肯定会消耗大量带宽。

在这种情况下，您可以使用shouldPrefetch函数来控制哪些文件具有预取提示，哪些文件没有。通过这种选择性选项，您可以避免在服务器上消耗大量带宽。

serviceWorker

这个相当有趣。在继续之前，你需要确保满足一定的条件才能使用serviceWorker配置实体：

• serviceWorker只能通过 HTTPS 注册，所以你需要确保你的网站使用 SSL 证书

• serviceWorker仅在生产模式下工作；也就是说，在实际的网站上

现在，serviceWorker 是一个默认为 false 的布尔类型。但是当你将它设置为 true 时，VuePress 将自动生成并注册一个 service worker 脚本。这可以用来帮助缓存内容以供离线使用。

什么是 service worker？在JavaScript（JS）中，service worker 是一种特殊类型的脚本，它是在后台由 Web 浏览器动态生成并运行的。它的运行方式与实际的网页加载不同。这里的目标是执行一些非常重要的后台功能，但不需要实际的网页或用户配置。

现在使用 service worker 脚本的情况的例子包括浏览器中的推送通知，浏览器中的离线缓存，后台数据同步以便在连接失败时更容易恢复等。

当使用自定义主题时，正如你将在后面的章节中看到的，serviceWorker配置值有时也会发出以下事件：

• sw-ready

• sw-cached

• sw-updated

• sw-offline

• sw-error

这里的serviceWorker选项只会处理 JS serviceWorker脚本。这意味着它不会自行生成单页面 Web 应用程序；它取决于你是否利用serviceWorker脚本来满足项目的需求。

再次强调，确保只有在 SSL 激活时将serviceWorker设置为 true，因为serviceWorker脚本在非 HTTPS URL 上不起作用。

dest

这个配置变量指定了 VuePress 最终构建过程的输出目录。默认路径是.vuepress/dist，但你可以通过指定任何其他字符串类型的路径来更改它。

端口

这是用来指定连接到开发服务器的端口值。除了 localhost，你的网络托管提供商应该能够更准确地告诉你可能希望在这里使用哪个端口。

默认值是8080，你只能使用整数类型的值，因为端口值只能指定为整数。

主机

此术语指定了您可以用来连接服务器的主机地址。再次强调，您的网络托管提供商或服务器管理员应该有关于此字段的准确细节。

它接受字符串类型的值，默认设置为'0.0.0.0'。

与浏览器兼容性相关的配置值

VuePress 目前只有一个与主要浏览器兼容性相关的配置值，您应该知道。

常青

此配置值是boolean类型，默认设置为 false。

但是，如果您希望您的 VuePress 网站仅针对常青网页浏览器，可以将其设置为 true。设置为 true 时，它将禁用对 ES5 转译和 polyfill 的支持。这意味着您的网站将无法与较旧版本的Internet Explorer（IE）很好地配合。

优势是什么？构建时间将大大缩短，事情将更快地运行。此外，您的网站的最终构建大小将更小。

什么是常青网页浏览器？常青网页浏览器是指自动更新到未来版本的浏览器。因此，用户无需下载新版本并从头安装。例如，如果您正在运行 IE 8 并希望安装 IE 9，则需要下载可安装文件然后运行它。另一方面，现代浏览器的版本，如 Chrome 或 Firefox，可以在发布新更新时自动更新，而无需再次运行安装程序。

这种滚动式的网页浏览器更新模式被称为“常青网页浏览器”。大多数较新的网页浏览器是常青的，而较旧的版本则不是。

与构建流水线相关的配置值

现在，让我们把注意力转向与构建流水线相关的配置值。在静态内容管理系统中，如 VuePress 和 Jekyll 中，构建流水线指的是生产线；也就是说，代码从开发到生产的流程。

在这一点上，您对 JS 和 CSS 的知识将会派上用场。这些与构建流水线相关的配置值大多围绕着 webpack。由于深入研究 JS 和 CSS 加载器超出了这个快速入门指南的范围，我们将只引用相关项目的 GitHub 页面，以便您可以根据需要学习更多。

postcss

postcss 可以用来指定 webpack 中 PostCSS loader 的自定义选项。有关该加载程序的详细信息，请参阅：github.com/postcss/postcss-loader。

一旦您指定了 postcss 值，您将覆盖其中的任何其他 autoprefix 值。它只接受对象类型的值，其默认语法如下：

{ plugins: [require('autoprefixer')] }

scss

scss 提供了用于将 SASS 转换为 CSS 的 SCSS loader 的选项。您可以在github.com/webpack-contrib/sass-loader了解更多关于此加载程序的信息。

此配置实体接受对象类型的值，其默认格式为 { }。

stylus

stylus 配置实体提供了调整 webpack 中 Stylus loader 的选项。默认情况下，它接受对象类型的值，语法如下：

{ preferPathResolver: 'webpack' }

您可以在github.com/shama/stylus-loader了解更多关于 stylus loader 的信息。

less

此术语指定了可以用于将 LESS 编译为 CSS 的 LESS loader 的选项。有关详细指南，请参阅github.com/webpack-contrib/less-loader。

它接受对象类型的值，其默认格式为 { }。

sass

这提供了可以将 SASS 编译为 CSS 并加载 *.sass 文件的 SASS loader 的选项。有关此加载程序的其他详细信息，请参阅github.com/webpack-contrib/sass-loader。

它接受对象类型的值，其默认格式如下：

{ indentedSyntax: true }

chainWebpack

chainWebpack 是一个具有未定义默认值的函数。

它可以帮助您通过使用 Mozilla 的 Webpack Chain API 修改内部的 webpack 配置。这个特定的 API 可以生成并简化 webpack 的定制和配置过程。您可以在 GitHub 上了解更多信息：github.com/mozilla-neutrino/webpack-chain。

以下是一些示例代码，显示了在 VuePress 中使用 chainWebpack 的语法：

module.exports = {
    chainWebpack: (config, isServer) => {
    // provide instance and config details here
    }
}

configureWebpack

正如其名称所示，这个特定的配置实体允许您修改 webpack 的内部配置。因此，它主要适用于已经熟悉 webpack 及其用法的人。

它使用了webpack-merge，详细信息可以在github.com/survivejs/webpack-merge找到。

通常，webpack-merge为你提供了一个合并函数，它简单地连接数组并合并对象。这将导致创建新的对象，你可以使用它们。

在 VuePress 中，configureWebpack的默认值为 undefined。但是，你应该注意它可以是对象类型或函数类型之一：

• 当值为对象类型时，该值通过使用webpack-merge合并到最终配置中，如前所述。

• 当值为函数类型时，它接收与第一个参数相同的配置细节（第二个参数通常是一个isServer标志）。然后，你可以选择直接修改作为参数传递的配置，或者将其详细信息作为一个可以合并的对象返回。

当使用configureWebpack作为函数类型时，语法如下：

module.exports = {
    configureWebpack: (configArgs, isServer) => {
    if (!isServer) {
        // modify or work with the configArgs here
        }
    }
}

所以，你现在已经了解了 VuePress 中所有必需的配置实体的基本细节。再次强调，我们已经省略了与主题配置相关的配置术语，以及 Markdown，这些将在后续章节中讨论。

然而，现在你知道可以期待什么术语以及在哪里——例如，当处理要用作站点图标的图像资产时，你应该在头部配置中调用或引用它，依此类推。

现在是时候学习一些关于 VuePress 中 URL 和资产处理的理论了。然后，你将准备好开发你的第一个 VuePress 站点。

资产处理是什么？

当我们说资产处理时，我们指的是什么？

在开发领域，特别是在网络开发中，资产是指项目使用或处理的任何内容。这可能包括但不限于以下内容：

• 图片

• 视频

• 其他媒体文件

• 文件，比如 PDF

自然地，为了处理这些数据文件和资产，CMS 需要实施专门的措施和协议。换句话说，你不能把 JPG 文件当作代码文件来处理——它并不能被内容管理系统完全读取，但系统必须意识到它是图像类型的媒体资产，并应该相应地处理。

在 VuePress 中，方法论相当简单。首先，我们必须了解 VuePress 中 URL 的配置方式。然后，我们可以将注意力转向公开可见的文件，如图片和图形。

VuePress 中的 URL

通常，您希望将实时的 VuePress 站点保留在以下两个位置之一：

• 在根 URL

• 在非根 URL

对于非根 URL，您需要在您的config.js中指定base选项-是的，就是我们在第二章中讨论的同一个config.js文件，它位于.vuepress目录中。

假设我们在mysite.example.com上有一个项目，并希望在名为vuep的目录中部署 VuePress。因此，我们的 VuePress 实例将在mysite.example.com/vuep/上运行。

在这种情况下，base值应设置为/vuep/。

请注意，base应以斜杠开头和结尾；即/。

现在，一旦您指定了base选项，它将自动添加到所有资产 URL 之前。这意味着您在.vuepress/config.js文件中指定的任何资产 URL 都将在其前面添加base值。

目前，理论部分就是您需要了解的全部内容。此方面的实际用法将在第四章中进行，即使用 VuePress 创建站点，在那里我们将使用 VuePress 设置站点。

在 VuePress 中处理公共文件

有多种方式可以访问 VuePress 中的文件。重申一下，我们指的是媒体元素和其他资产。

您可以通过以下方式来做：

• 在您的 Markdown 组件中引用文件

• 引用主题组件中的文件

• 将文件视为公共文件

我们将在随后的章节中介绍前两个步骤。

假设您有一个需要公开查看的图像文件。通过公开查看，我们指的是它应该对站点的所有访问者可见，而不仅仅是管理员，例如站点的 favicon。

您只需要将所述图像文件放在.vuepress/public目录中。此后，该文件将位于生成目录的根目录，并且可以公开访问。

然后，您可以参考或指定如下示例中的内容：

mysite.example.com/vuep/favfile.png

在这里，favfile.png是您放置在/public/目录中的文件。

简单，不是吗？

那么，如果您希望重新定位 VuePress 站点怎么办？比如，更改/vuep位置？您可能需要更改以这种方式制作的所有 URL 的引用。

为了防止这种情况发生，VuePress 提供了一个相当简单的解决方案。

您可以使用内置的$withBase助手（在 VuePress 中原生构建，无需扩展），它将自动生成正确的路径，您无需担心指定的绝对路径可能会在以后更改。

以下是如何使用它的示例：

<img :src="$withBase('/favfile.png')" alt="My Fancy Image File">

这段代码将确保引用保持在指定的文件上，而不管您在 VuePress 中使用的基本 URL 是什么。您可以使用它来处理您的公共文件，甚至在主题组件和 Markdown 文件中使用它。

相对 URL 呢？

在 VuePress 中，与现代网络上的任何其他内容管理系统一样，最好和建议通过相对 URL 引用所有资产元素。例如，./sample.jpg可以在任何文件模板中使用。在这种情况下，目标图像将首先使用 URL-loader 和 file-loader 进行处理，然后复制到最终静态构建所需的位置。

在使用webpack模块（以及在本章前面提到的构建管道配置部分中提到的配置实体）时，您可以使用~前缀。这在许多 JS 框架中都是标准的，如果您有任何这些 JS 框架的经验，您可能已经知道它。例如，~some-directory/sample.jpg是使用webpack别名引用文件的一种好方法。

在本章的前面，我们谈到了用于配置的configureWebpack选项。您可以在.vuepress/config.js文件中使用此选项轻松配置您的webpack别名。

这是一个这样的示例：

module.exports = {
    configureWebpack: {
        resolve: {
          alias: {
            '@alias': 'custom/path/to/directory/relative-url'
          }
        }
      }
    }

在前面的例子中，您只是利用configureWebpack来确保所说的别名指向您为项目中要使用的所需资产或元素指定的自定义路径。与其他配置工具一起使用时，它可以帮助您轻松获取资产。

这就是 VuePress 中的资产处理。在这一点上，您已经准备好进行实际的站点开发了。

摘要

在本章中，您已经了解了 VuePress 中大多数基本和高级配置实体。您了解了基本术语，以及在哪里可能调用值，以及哪个函数可能返回哪个值。

显然，这将假定您熟悉基本的 JS 对象、函数和调用。

此外，您还了解了 VuePress 中的资产处理基础知识，URL 是如何相对处理的，媒体元素如何被引用等等。

然而，目前看起来可能会有信息过载，因为你已经学到了相当多的理论，但到目前为止还没有将其编译成生产或开发。但就像任何其他建立在现有语言之上并提供丰富可配置选项框架的软件或产品一样，VuePress 也需要被视为这样的产品。

在《第四章》在 VuePress 中创建站点中，我们将构建一个实时的 VuePress 网站。您可以使用任何您选择的代码编辑器或 IDE，以及任何平台。请注意，我们将在后面的章节中专注于部署，因此建议为下一章设置一个本地站点。您已经在上一章中学习了如何安装 VuePress。

因此，在阅读《第四章》在 VuePress 中创建站点时，有必要在需要时参考本章。这将帮助你了解哪些配置选项可以在哪里使用，以及如何避免一些常见的问题。因此，当我们在下一章中构建 VuePress 站点时遇到特定的配置时，我们将会实际学习它。

重点将放在处理媒体文件（如图像）上，因为没有图像，你实际上无法构建一个真正的实时站点！此外，我们还将涵盖一些真实世界的概念，比如与 Google Analytics 等服务的集成（请注意，我们已经在本章的基本配置部分中学习了配置引用的语法；请参见本章前面的ga）。这将帮助您构建一个真正可用而不仅仅是花哨示例的 VuePress 站点。

因此，确保您已经掌握并对本章涵盖的术语有了相当好的理解。在那之后，让我们继续前进，构建一个 VuePress 站点！

第四章：在 VuePress 中创建站点

在第三章中，VuePress 开发-初步步骤，我们学习了与 VuePress 配置相关的基础知识，以及如何使用变量和函数。我们了解了可以调整的各种值，以个性化和设置我们的 VuePress 站点。

除此之外，在第二章中，使用 VuePress 入门，我们已经在系统上安装了 VuePress。根据我们可能面临的要求，我们可以选择在全局安装 VuePress，或者将其作为现有包的依赖项进行安装。

无论安装方法如何，目前最重要的是我们应该有一个可用的 VuePress 安装。而且，现在我们已经掌握了 VuePress 等静态站点生成器的能力，以及如何配置它们，是时候开始看到实际效果了。

因此，在本章中，我们将把注意力转向 VuePress 的实际实现。换句话说，我们将使用 VuePress 构建一个实际的网站。这将帮助我们更好地理解 VuePress 的工作流程，也会让我们更全面地了解其基本概念。

因此，不要浪费任何时间，让我们开始吧！

在本章中，您将学习以下内容：

• 在 VuePress 中构建站点

• 如何创建 Markdown 文件并运行 VuePress 开发引擎

• 如何在 VuePress 中构建和呈现静态站点

• 介绍.vuepress/config.js文件

在 VuePress 中构建站点

值得注意的是，在这个阶段，您应该已经有一个正在运行的 VuePress 实例。如果您还没有安装 VuePress，请参考本书的第二章，使用 VuePress 入门。

此外，您需要使用基本的 Markdown 文件来输入内容。大多数 Web 开发人员都很熟悉 Markdown，并且大多数人都经常使用它。如果您不知道 Markdown 是什么，或者不习惯使用它，请参考本书的第五章，在 VuePress 中使用 Markdown。也就是说，在本章中，我们只会涉及 Markdown 元素的表面，比如段落、标题和链接。因此，对 Markdown 的基本了解现在已经足够了。

最后，虽然我们在本章实际上会建立一个网站，但我们不会将其部署到网络上的实时服务器。关于部署的细节，我们已经单独设置了一个章节。如果您希望在建立网站后立即部署项目文件，请参阅本书的第八章，将 VuePress 部署到网络。

既然我们已经介绍完了，现在是时候开始在 VuePress 中进行网站开发了！

我们将要建立什么？

大问题是：我们究竟要建立什么？

我们将使用 VuePress 创建一个简单的网站。举例来说，让我们假设这个给定的网站是关于咖啡的。

这是我们打算如何构建它的方式：

• 一个主页，详细介绍网站内容（并有一个呼吁行动的按钮）

• 一个关于页面

• 一个关于咖啡本身的示例页面

此外，我们的网站还将有一个导航菜单，链接到我们所有的页面，以及一个外部链接。实质上，我们希望在 VuePress 中构建一个多页面静态网站，具有自定义的主页视图。

以下是最终主页应该看起来的示例：

创建一个 VuePress 网站

既然我们已经明白了我们要做什么，让我们开始建立我们的网站吧。

README.md 文件

在 VuePress 中，README.md文件充当我们的主页。自然而然，这就是 index.html 文件中的所有内容应该放置的地方。

我们可以在 Markdown 中编辑此文件，以包含我们需要的一切。除此之外，我们还可以使用 YAML Front Matter 语法来指定主页的自定义选项，比如区域设置、与 SEO 相关的元数据和自定义布局。

安装了 VuePress 之后，我们可以立即使用以下命令创建一个README.md文件：

echo ‘Hello World!' > README.md

这个命令将创建一个包含“Hello World!”一行的简单的 Markdown 文件。输出将如下所示：

显然，这对我们的主页来说是不够的，对吧？我们很快将建立一个自定义的主页。

启动开发引擎

此时，打开终端（或命令行）并运行以下命令是一个好主意：

vuepress dev

这将启动 VuePress 的开发引擎，看起来是这样的：

现在我们可以在网页浏览器中打开上面截图中显示的 URL，并且当我们对文件结构进行更改时，页面将自动刷新以展示实时更改，只要开发引擎正在运行（也就是说，终端是打开的），那么我们就可以在保存内容时查看实时更改。

确保在安装 VuePress 的确切目录中运行vuepress dev命令。所有文件都将放置和创建在其中，包括 Markdown 文件，任何媒体元素，以及任何 JS 配置文件。

构建首页

还记得我们刚刚创建的README.md文件吗？让我们打开它并稍作编辑。

任何编辑器都可以用来编辑 Markdown 文件。我个人只是在 Linux 中使用默认的 xed 或 gedit 文本编辑器。你也可以选择使用流行的代码编辑器来编辑 Markdown 文件。

我们将添加我们的前置内容，以生成一个自定义的首页。我们将使用 YAML 前置内容。如果你对此不熟悉，不用担心——我们将在下一章中更详细地讨论 Markdown 时进行介绍。

我们的首页应该有一个标题，后面跟着一个呼吁行动的按钮，鼓励我们的访客了解更多关于产品的信息。然后，我们还将添加三个单独的部分，向世界介绍更多关于我们的产品。最后，我们将添加页脚布局。

现在，让我们构建首页。

非常重要的是要知道，VuePress 默认主题附带了自己的首页布局。我们所要做的就是在前置内容中指定我们希望使用首页布局。为了做到这一点，我们只需要输入以下内容：

---
home: true
---

然后，我们将添加额外的条目，比如我们的呼吁行动按钮文本和链接，如下所示：

---
home: true
navbar: true
actionText: Learn More →
actionLink: /about
---

现在我们可以保存文件以预览更改。再次提醒，我们正在对刚刚创建的README.md文件进行更改。

如我们在下面的截图中所看到的，已经添加了一个呼吁行动的按钮，链接到一个关于页面（尚未创建，因此点击按钮将显示 404 错误）。

接下来，我们可以将剩余的内容添加到我们的前置内容中。以下是前置内容现在应该看起来的样子：

---
home: true
navbar: true
actionText: Learn More →
actionLink: /about
features:
    - title: Caffeinated
    details: It is obvious that coffee is surely the greatest beverage known to humans.
    - title: Keeps You Awake
    details: Grab some strong coffee and stay awake forever... probably not a healthy idea though.
    - title: Good for Coding
    details: Nobody accepts this but programming is definitely impossible without coffee.
---

我们在首页添加了一个特性部分。我们添加了三个特性，每个都有自己的标题和正文内容。

因此，我们的首页应该变成以下样子：

接下来，我们只需要添加页脚。我们只需要在我们的前置内容中指定一个页脚条款，如下所示：

---
footer: MIT Licensed | A sample VuePress site built by Sufyan bin Uzayr
---

我们选择了 MIT 许可证，因为 VuePress 也使用这个许可证。当然，这完全取决于您如何希望对您的内容进行许可。

添加了页脚之后，我们的首页应该看起来像这样：

添加元数据

一旦我们建立了首页，我们也可以在前置内容中添加一些元数据，如下所示：

---
meta:
    - name: description
    content: Just a simple VuePress site about coffee.
    - name: keywords
    content: vuepress coffee
lang: en-US
---

在上面的片段中，我们为我们的网站添加了一个元描述，并指定了一些关键词。此外，我们告诉引擎和爬虫我们的网站使用的是美式英语。

到这一点，我们的README.md文件应该看起来像下面这样：

显而易见，整个文件仅由前置内容组成。我们将在第五章中详细学习有关 YAML 前置内容，在 VuePress 中使用 Markdown，以及在第六章中，VuePress 主题开发时，我们将讨论主题开发。

目前，我们的首页已经准备好了。我们可以选择在 Markdown 中向这个文件添加任何其他内容。这些内容需要在前置内容之后添加，尽管它将显示在页脚之上和首页英雄内容之下。

添加其他内容页面

现在我们的网站需要额外的页面来展示更多的内容。考虑到 VuePress 是一个静态网站生成器，我们只需要相应地添加内容，VuePress 会处理其余的工作。

是的，就是这么简单！：

1. 我们将我们的内容添加为 Markdown 文件

2. VuePress 从这些 Markdown 文件中生成 HTML 文件，只要这些文件是有效的格式

就是这样。因为 VuePress 仍然不是一个博客或电子商务引擎，所以没有需要添加的自定义分类，或类似的东西。

对于我们的网站，我们将添加两个页面。第一个将是一个关于页面，第二个将是一个关于咖啡的页面。

对于我们的关于页面，我们在与README.md文件相同的目录中创建一个about.md文件。然后，我们可以用任何我们喜欢的内容填充我们的网站。这是我们在网站上使用的示例：

输出应该显示如下（确保在添加此文件后再次运行vuepress dev命令）：

要查看输出，只需将 Web 浏览器导航到/about.html，根据开发引擎显示的本地主机地址。

值得注意的是，VuePress 自己处理了一些事情：

• 表情符号基于 GitHub 表情符号服务显示。

• 更重要的是，Markdown 中的每个 H1、H2、H3 和其他类似的标题标签在 HTML 中都被视为锚链接。您可以将光标悬停在任何标题上，注意到自动生成了一个锚链接。

同样，我们也可以添加coffee.md文件。实际上，我们可以添加任意数量的页面。我们只需要添加 Markdown 文件，并告诉 VuePress 正确的位置。

添加导航菜单

在这个阶段，我们已经向网站添加了所有页面和内容。我们还建立了一个主页，可以在 Web 浏览器中浏览和预览所有内容。

但显然，我们只是输入每个页面的 URL 以预览它们。现实世界的用户无法猜测文件名。因此，在没有导航菜单的情况下，我们的网站无法正常运行。

对于我们来说，考虑为我们的网站添加导航栏是合乎逻辑的。当我们在第六章中更详细地学习 VuePress 的主题开发时，VuePress 中的主题开发，我们将触及导航栏定制的每一个方面（包括永久禁用导航栏）。但是，现在，我们的首要任务是展示一个功能齐全且有用的导航栏，以便我们的用户可以轻松浏览网站。

好消息是，VuePress 默认支持导航栏功能。也就是说，除非我们明确向其中添加项目，否则它不会显示。

为了创建导航菜单，我们需要使用以下代码：

module.exports = {
 themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'About', link: '/about' },
      { text: 'Coffee', link: '/coffee' },
      { text: 'GitHub', link: 'https://github.com/packtpublishing/vuepress-quick-start-guide' },
    ]
  }
 }

前面的代码为我们的主题配置导出了一个导航栏数组。在这里，我们为以下页面添加了四个链接：

• 主页，位于/

• 关于页面，位于/about

• 咖啡页面，位于/coffee

• 指向我们 GitHub 仓库的外部链接

值得注意的是，所有外部链接都需要完整输入，URL 开头需要带有 HTTP/HTTPS 协议，就像在这个截图中看到的那样：

我们需要将这段代码添加到我们的config.js文件中。这个特定的文件位于我们的 VuePress 站点的.vuepress目录中（如果偶然间这个文件不存在，可以随意创建一个名为config.js的空文件，然后在其中输入前面的代码）。如果我们将这个文件放在.vuepress目录之外，可能会导致事情不按预期工作。

config.js文件是什么？

在 VuePress 中，config.js文件包含了所有与配置相关的代码，正如其名称所示。这意味着任何调整 VuePress 配置的函数或代码都应该添加到这个文件中。如果没有这个文件，VuePress 将退回到默认配置值。

一旦保存了 config.js 的条目，我们可以刷新输出，导航栏将被添加，就像下面截图顶部所示的那样：

您可能会注意到搜索栏也已经添加了。但是等等，我们实际上并没有在任何地方添加搜索栏，是吗？

是的，没错——VuePress 自带搜索栏功能，无需进行调整。它就位于导航菜单旁边。然而，我们可以通过外部搜索索引服务扩展或替换默认搜索方法。

搜索栏在我们输入时就会显示结果；无需刷新页面。这就是 JavaScript 的美妙之处；其他几种网页开发语言只有在强制进行完整页面重新加载后才会显示结果。

与 WordPress 和其他软件不同，VuePress 原生搜索不会在内容主体内进行搜索。相反，它只会搜索输入的标题。这就是为什么在前面的截图中，我们只看到了Coffee is awesome页面作为结果，而coffee这个词也出现在首页和关于页面中。

因此，为了获得更强大的搜索体验，通常建议使用外部服务。我们将在本书的第六章中学习如何集成这一点，VuePress 主题开发。

最终构建

现在我们已经成功构建了我们的完整站点。我们已经添加了内容，还创建了单独的页面，甚至创建了一个导航菜单。

到目前为止，我们使用vuepress dev命令来运行开发引擎并预览站点。一旦确定我们已经构建了站点，我们可以安全（字面上）地构建它。

为此，我们需要输入以下命令：

vuepress build

此命令将提取我们站点的元数据并编译信息。然后，它将根据 Markdown 内容呈现静态 HTML 页面，如下所示：

生成的内容默认放置在.vuepress目录中的 dist 目录中。因此，我们的 VuePress 站点的一般目录结构如下：

值得指出的是，VuePress 根据我们创建的 Markdown 文件生成 HTML 文件。它进一步将所有媒体元素、JS 文件和 CSS 文件放置在.vuepress/dist路径下的 assets 子目录中。/img目录包含图像，而/js子目录包含 JS 文件。

除此之外，VuePress 还创建了一个404文件，以便在出现页面未找到错误时显示。我们可以根据需要自定义此文件，或者保持原样。

有趣的事实：这个示例站点的最终构建，全部压缩在一起，大约是 68 KB。而在动态数据库驱动的 CMS 中，比如 WordPress 或 Drupal，三个页面的类似站点很容易就会超过 50 MB。

就是这样！我们已经成功构建了一个 VuePress 站点！很简单，不是吗？

摘要

在本章中，我们学习了如何使用 VuePress 构建静态站点。我们学习了自定义主页布局，添加呼吁行动按钮以及其他内容，以及其他页面。

不仅如此，我们甚至为我们的站点添加了导航菜单。此外，我们还了解了config.js文件的作用。在接下来的章节中，我们将学习更多与定制相关的调整。这些调整中的大部分将放置在config.js文件中。

最后，我们学习了如何使用vuepress build命令构建VuePress 站点。到目前为止，我们已经使用我们自己的内容生成了一个静态站点。

您可以在该书的 GitHub 存储库中找到此站点的原始代码，包括所有 Markdown 文件，以压缩文件的形式。您还可以下载导出的build文件，包括静态内容，作为另一个压缩文件。GitHub 存储库位于github.com/packtpublishing/vuepress-quick-start-guide。

这个特定的网站现在可以轻松部署到我们选择的任何云托管服务上。然而，在本书的最后一章中，我们将转向部署，学习如何将我们的网站部署到各种托管服务，如 Heroku、Netlify 和 Google Firebase！

目前，我们将深入研究 Markdown，以便更好地掌握内容格式和演示。然后，我们将学习一些关于主题开发的知识，以便我们可以定制我们的网站，使其成为我们想要的样子。

在下一章中，我们将把注意力转向 Markdown 中的内容编辑，以及 VuePress 如何与 Markdown 配合工作。

第五章：在 VuePress 中使用 Markdown

在[第四章]中，我们学习了如何使用 VuePress 创建站点或博客。如果您迄今为止一直在跟进本书，您应该在本地服务器或计算机上安装了 VuePress，并且所有变量都已就位。此外，您还应该了解可以调整的各种配置值，以充分利用 VuePress。

除此之外，您还知道如何处理页面，如何设置站点结构和导航，应用默认样式等等。

换句话说，您知道如何启动和运行 VuePress 网站，以及如何填充内容。

但说到内容，如何在 VuePress 中管理和添加内容？在这种情况下，完成这些工作的最简单和首选方法是使用 Markdown。

Markdown 是一种简单且轻量级的标记语言，具有自己的格式和语法。由于其简单性和易用性，自诞生以来，Markdown 已经变得非常流行。

在本章中，我们将学习不仅 Markdown 是什么，还要学习如何在 VuePress 中使用它。我们将学习 Markdown 语法，以及 VuePress 的 Markdown 扩展和 Markdown 的各种配置变量。

通过本章的学习，您应该能够在 VuePress 中输入内容，也可以在任何其他内容管理系统中使用 Markdown。

在本章中，您将学习以下主题：

• 什么是 Markdown？

• Markdown 如何使用？

• VuePress 中的 Markdown 配置

• VuePress 的 Markdown 扩展

• 在 VuePress 中格式化 Markdown 内容

学习在 VuePress 中使用 Markdown

强烈建议您获得一些 Markdown 格式化的基本技能，因为它很快将成为技术文档世界的事实标准，例如在 VuePress 项目的 README 文件中，甚至是 Vue.js 中。

什么是 Markdown？

如果您在 Web 开发领域活跃，您可能已经接触过 Markdown，并且很可能在项目中使用它。由于其流行，Markdown 不需要大量介绍。

话虽如此，值得一提的是，可能值得一提 Markdown 及其优点，以便即使是对这个主题新手的读者也可能会发现它有一些价值。

简而言之，Markdown 是一种注重易用性和可读性的内容格式化解决方案。它是由 John Gruber 于 2004 年与 Aaron Swartz 合作创建的。这里的目标是以更具表现力的格式提供纯文本内容，并在必要时可选择将其转换为有效的 HTML。

由于其高度简化和非常具有表现力的特性，Markdown 在技术上有能力的人群中获得了良好的追随者。

Markdown 带有 BSD 风格的许可证，目前可用于各种内容管理系统的专门插件形式。甚至 WordPress 也有几个 Markdown 插件可用。

此外，许多网站和项目都实现了它们自己定制的 Markdown 变体。这些用户包括 SourceForge、GitHub、reddit、Stack Exchange 等等。

一个例子

注意我们在前面的部分谈到了可读性吗？嗯，Markdown 非常注重可读性，即使在原始格式中也是如此。

考虑下面这段简单的 HTML 代码：

<h1>VuePress Quick Start Guide</h1>
<h2>By: Sufyan bin Uzayr</h2>
<p>VuePress is a static site generator.</p>
<p>It is powered by Vue.js which is an amazing JS framework.</p>
<hr />
<p>Major features:</p>
<ul>
    <li>Easy to use</li>
    <li>Simple and powerful</li>
    <li>Supports Markdown</li>
</ul>
<p>Features again:</p>
<ol>
    <li>Easy to use</li>
    <li>Simple and powerful</li>
    <li>Supports Markdown</li>
</ol>
<p><a href="https://vuepress.vuejs.org/">VuePress Homepage</a></p>
<blockquote>
<p>This is a blockquote.</p>
</blockquote>

现在，将前面的示例与以下 Markdown 代码进行比较：

# VuePress Quick Start Guide
## By: Sufyan bin Uzayr
VuePress is a static site generator.
It is powered by Vue.js which is an amazing JS framework.
* * *
Major features:
* Easy to use
* Simple and powerful
* Supports Markdown
Features again:
1\. Easy to use
2\. Simple and powerful
3\. Supports Markdown
[VuePress Homepage](https://vuepress.vuejs.org/)
> This is a blockquote.

前面两个代码示例将产生相同的输出。结果如下：

但是，正如你所看到的，Markdown 代码比 HTML 更清晰易读。它没有被繁琐的标签和其他元素所淹没。简单的格式化辅助意味着即使在原始格式中（即没有输出的情况下），你也可以阅读文本。这就是 Markdown 的简单和美丽之处！它非常易读，易于理解，也很容易输入。

您可以在官方网站上阅读有关 Markdown 的功能和设置的更多信息，网址为daringfireball.net/projects/markdown。

自然地，许多静态站点内容管理系统，如 VuePress，出于这些原因倾向于使用 Markdown。因此，尝试掌握 Markdown 中的一些基本格式化辅助是很有必要的，以便充分利用 VuePress。

markdown-it 解析器

现在我们已经了解了 Markdown 是什么，以及它可以为我们提供什么优势，是时候开始学习 VuePress 中 Markdown 的用法和变化了。然而，在进入 VuePress 环境之前，我们必须先了解一个名为 markdown-it 的 Markdown 解析器。

Markdown 解析器是做什么的？

它最简单的任务是分析并将 Markdown 语句分解为易于处理的句法组件。

markdown-it 的工作相当出色，而且非常容易使用。它带有自己一套自定义扩展，多个插件，并且不会减慢你的环境。VuePress 中的大多数 Markdown 扩展和配置变量都与 markdown-it 很好地配合，有些甚至只能通过 markdown-it 来使用。

要使用 markdown-it，你首先需要安装它。可以通过 npm 来完成，就像 VuePress 一样（你已经在第一章 介绍静态站点生成器和 VuePress中学习了 npm 安装）：

npm install markdown-it --save

接下来，你可以加载它的插件并根据需要使用它。要了解更多关于 markdown-it 解析器的信息，你可以查看其 GitHub 存储库github.com/markdown-it/markdown-it。

另外，还有一个可用的演示可以在markdown-it.github.io/中查看，如下截图所示：

VuePress 使用 markdown-it 作为默认的 Markdown 解析器或渲染器。当然，你不仅可以使用 markdown-it，还可以在 VuePress 中使用它的自定义扩展和插件。

为了在 VuePress 中进一步自定义 markdown-it，修改.vuepress/config.js文件以添加 Markdown 实例并在其中修改可能是个好主意。我们已经在之前的章节中介绍了.vuepress/config.js文件的内容和细节。请注意，你可以参考 markdown-it 文档以获取有关各种插件的更多详细信息，以及如何引用它们以供我们使用。

当添加到config.js文件时，你的示例代码应该如下所示：

module.exports = {
    markdown: {
    // the markdown-it-anchor
        anchor: { permalink: false },
    // the markdown-it-toc extension
        toc: { includeLevel: [1, 2] },
    config: md => {
    // this is where you add more markdown-it extensions
        md.use(require('markdown-it-name-of-extension'))
        }
    }
}

在代码的最后部分，请确保添加你希望使用的 markdown-it 扩展的相关名称。请注意，我们将在本章中介绍 markdown-it-anchor 和 markdown-it-toc 扩展，以帮助你更好地理解如何引用它们以及预期的输出是什么。

现在你已经了解了 Markdown 是什么，markdown-it 解析器是什么，以及 VuePress 如何将其作为 Markdown 的默认渲染器，现在可以安全地转向 VuePress 中的 Markdown 配置变量和值。之后，我们将关注 VuePress 对 Markdown 的使用和处理。

Markdown 配置参考

在这一点上，我们首先将关注 VuePress 中与 Markdown 相关的各种配置实体。请注意，这些是 VuePress 特定的，可能不适用于其他静态站点生成器。

我们已经在第三章中涵盖了基本的配置值，VuePress 开发-初步步骤。除此之外，我们将转向特定主题配置值及其在处理自定义主题的后续章节中的用途。

目前，我们只会关注 VuePress 配置中与 Markdown 相关的值和变量。随着在项目中使用 VuePress 的进展，你可以利用这些配置参考实体更好地管理 Markdown 中的内容，并确保它被格式化和呈现成你想要的样子。

markdown.slugify

这是一个非常重要的功能，你应该尽一切可能了解它。在 VuePress 中，markdown.slugify 可以用来将标题文本转换为 slug。

因此，你可以在 Markdown 中输入标题文本，然后使用这个函数来生成一个 slug（即 URL 或永久链接）。当然，这意味着它主要用于锚链接、目录和其他相关材料。

由于markdown.slugify是函数类型，因此在数据类型方面没有值定义。相反，它有一个函数定义。让我们更仔细地看一下它的一般语法，以进一步理解它的功能：

// string.js slugify drops non ascii chars so we have to 
// use a custom implementation here
const removeDiacritics = require('diacritics').remove
    // eslint-disable-next-line no-control-regex
    const rControl = /[\u0000-\u001f]/g
    const rSpecial = /[\s~`!@#$%^&*()\-_+=[\]{}|\\;:"'<>,.?/]+/g
module.exports = function slugify (str) {
    return removeDiacritics(str)
    // Remove control characters
    .replace(rControl, ' ')
    // Replace special characters
    .replace(rSpecial, '-')
    // Remove continous separators
    .replace(/\-{2,}/g, '-')
    // Remove prefixing and trailing separators
    .replace(/^\-+|\-+$/g, '')
    // ensure it doesn't start with a number (#121)
    .replace(/^(\d)/, '_$1')
    // lowercase
    .toLowerCase()

你也可以在github.com/vuejs/vuepress/blob/master/lib/markdown/slugify.js浏览相同的源代码。

现在，你注意到这个函数在做什么了吗？它获取标题文本，移除其中的空格字符，然后用连字符（-）替换，接着移除任何前缀和尾随字符，最后将标题文本转换为小写。

例如，如果我们的标题文本是Header SamPLE，它会将其转换为header-sample作为 slug。当然，因为 slug 是 URL 的一部分，它不能包含特定字符和空格。markdown.slugify确保了这一点。

markdown.externalLinks

markdown.externalLinks用于向内容添加外部链接（从名称上就很明显）。默认情况下，它将其值配对在<a>标签中，并在新窗口中打开外部链接。

markdown.externalLinks是对象类型，其默认语法如下：

{ target: '_blank', rel: 'noopener noreferrer' }

如果您希望不在新窗口中打开外部链接（出于 SEO 原因或类似原因），您可以删除target:'_blank'部分，就像您在任何其他 HTML 文档中所做的那样。

markdown.config

markdown.config 是函数类型，其默认值因此为未定义。

它用于修改默认配置，并向我们在上一节中讨论的 markdown-it Markdown 解析器添加附加功能或外部插件。

以下是一个演示其用法的示例：

module.exports = {
    markdown: {
        config: md => {
            md.set({ breaks: true })
            md.use(require('markdown-it-something'))
        }
    }
}

在上面的示例中，markdown.config 添加了对名为 markdown-it-something 的外部实体的要求，然后可以用于实现相同外部实体的附加功能。

markdown.toc

markdown.toc提供了向我们的网站添加目录的选项。如果您计划创建一个需要这样的目录的网站，比如知识库网站或在线小说或书籍的章节布局，它尤其有用。

这是对象类型，其默认语法如下：

{ includeLevel: [2, 3] }

值得注意的是，markdown.toc实际上与 markdown-it-table-of-contents 插件一起使用。这个特定的插件为 markdown-it 插件提供了一个目录布局。您可以在github.com/Oktavilla/markdown-it-table-of-contents上了解更多信息。

markdown.anchor

markdown.anchor是对象类型，其一般语法如下：

{ permalink: true, permalinkBefore: true, permalinkSymbol: '#' }

它提供了向您的内容添加标题锚的选项。

请注意，这不应与markdown.slugify添加的标题标识符或 ID 混淆，如前所讨论的那样。相反，markdown.anchor 允许您在内容中添加锚链接。

它与 markdown-it-anchor 插件协同工作，该插件为 markdown-it 添加了标题锚功能。您可以在其 GitHub 页面上了解有关此插件的更多信息github.com/valeriangalliat/markdown-it-anchor。

markdown.lineNumbers

每当您向 VuePress 网站添加诸如代码块之类的内容时，您可以选择是否在代码块旁边显示行号。为此，您可以使用markdown.lineNumbers配置实体。

markdown.lineNumbers是boolean类型，它接受简单的true或false值来显示（或不显示）行号。

例如，当markdown.lineNumbers配置值设置为 true 时，代码输入将具有行号。

以下是如何做到的：

module.exports = {
    markdown: {
    lineNumbers: true
    }
}

通过设置配置值，任何代码输入都将附加行号。例如，如果我们在页面中显示相同的代码作为预格式化内容，它将如何显示：

现在我们已经涵盖了几乎所有相关的 Markdown 配置术语，是时候把注意力转向 VuePress 中使用的 Markdown 扩展了。

VuePress 中的 Markdown 扩展

当我们谈论 VuePress 中的 Markdown 扩展时，我们指的是那些可以立即在 VuePress 中使用的 Markdown 扩展。您已经看到了 Markdown 格式如何在 VuePress 的日常使用中使用，在第四章中，在 VuePress 中创建站点。

标题锚点

VuePress 中的所有标题都会自动应用锚链接，以便更轻松地浏览站点内容。这主要是为了方便浏览站点内容，因为 VuePress 主要是一个文档管理工具，而不是一个商业站点解决方案。在这种情况下，通过标题导航是管理内容的最简单方式。

如果您希望配置或修改锚点设置，可以使用markdown.anchor配置选项，如本章的前一节所讨论的那样。

链接

在 VuePress 中，链接可以是内部的或外部的。

顾名思义，内部链接指向本地内容，而外部链接指向其他网站和项目的内容。

让我们在下一节中分别讨论每一个。

外部链接

所有指向第三方网站的外部和出站链接都会自动附加target="_blank" rel="noopener noreferrer"标签。这意味着所有外部链接都会在新窗口（或浏览器标签）中打开。您可以使用markdown.externalLinks配置选项来修改此设置，如本章的前一节所讨论的那样。

内部链接

在这一点上，值得记住的是 VuePress 生成单页面应用程序（SPA）以便更轻松、更快速地浏览站点内容。现在，为了实现 SPA 导航，所有本地或入站链接都需要转换为路由链接。

VuePress 通过将所有以 Markdown 或 HTML 格式结尾的内部链接转换为<router-link>来实现这一点。

我们在上一章中学到，VuePress 中的每个子目录，除非不是公开访问的，必须有一个README.md文件，然后 VuePress 会将其转换为index.html文件，然后在浏览器中提供服务。

当在内容中添加内部链接时，您需要在文件路径中指定正确的文件扩展名，否则将会得到 404 错误。因此，在 VuePress 中添加内部或本地链接时，必须牢记以下考虑事项：

• 必须附加.html或.md——正确的文件扩展名。

• 在编写文件或资源的相对路径时，必须添加尾随斜杠/。如果没有尾随斜杠，VuePress 将无法遵循相对路径，并将给出 404 错误。因此，/mypath是不正确的，而/mypath/是正确的。

• 所有路径规范都是区分大小写的。

现在，为了更好地理解这些要求，让我们举个例子。考虑以下目录结构：

以下表格显示了此结构的链接语法应如何工作：

相对路径	Markdown	解释
/	[首页]	位于根文件夹中的README文件
/testx/	[testx]	位于testx子目录中的README文件。
/testx/filea.md	[testx - filea]	testx子目录中的filea.md文件；注意.md扩展名。
/testx/fileb.html	[testx - fileb]

| fileb.md文件位于testx子目录中；注意.html扩展名，它仍然指向.md文件。 |

| |

|

在这个例子中，我们可以清楚地看到，当渲染页面时，VuePress 会自动将.md扩展名转换为解析的 HTML。

表情符号

考虑到表情符号已经变得相当流行，应该有一种方法来正确格式化并在您的内容中包含它们，如果您愿意的话。WordPress 甚至已经集成了自己的自定义 WordPress 表情符号，您可以在您的内容中使用，或者直接删除并依赖浏览器表情符号。

然而，与 WordPress 不同，VuePress 更注重轻量和迅速。因此，在 VuePress 的核心中配备自定义表情符号集是没有意义的。

但是，您可以轻松地使用 markdown-it-emoji 插件，该插件预装了超过 1,000 个表情符号供您选择。这是一个示例：

您可以选择使用提供所有 GitHub 支持表情符号的完整版本，或者只提供 Unicode 表情符号的轻量级版本。此特定插件还支持基于字符的表情符号，例如:-)等。它与 markdown-it 解析器一起工作，并可以通过 npm 安装，如下所示：

npm install markdown-it-emoji --save

当然，我们这里的主要重点是如何在 VuePress 中使用 markdown-it-emoji。要了解有关插件本身的更多信息，您可以在其 GitHub 页面上找到：github.com/markdown-it/markdown-it-emoji。

在 VuePress 中，您只需在两个冒号内键入所需的表情符号名称即可。例如，要在每个连续行上添加一个头骨、一个外星人、一个尖叫的脸和一个太阳镜表情符号，请尝试以下代码：

:skull:
:alien:
:scream:
:sunglasses:

在浏览器中的最终输出将如下所示：

当然，表情符号的最终实际外观也可能会因您的操作系统和浏览器版本而有所不同。有时，某些网络浏览器倾向于用自己的变体替换默认的网络表情符号。

添加表格

VuePress 在 Markdown 中原生支持两种主要类型的表格。

第一个显然是目录。这不是一个纯粹的表格，因为几乎没有行或列，但无论如何都被称为表格，所以让我们保持这样。语法很简单，如下所示：

[[toc]]

这将根据内容中的标题自动生成目录。您可以进一步通过使用markdown.toc配置选项进行自定义，如本章前面所述。

VuePress 中的第二种表格类型类似于 GitHub 上的表格布局。实际上，它被称为 GitHub 风格表格。

假设我们正在创建一个简单的表格，概述每个国家的首都、旅游景点、流行运动和货币。您可以按照以下 Markdown 格式和详细信息输入：

输出将如下所示：

这就是 VuePress 中的表格。表格会自动格式化，并且交替行也会高亮显示，以使表格看起来更加整洁。

前置内容

通过 YAML 数据序列化的前置内容概念首先由 Jekyll 引入，Jekyll 是另一个非常流行和多功能的静态站点生成器，我们在第一章中简要讨论过，介绍静态站点生成器和 VuePress。

简而言之，前置内容被放置在文件的开头和三虚线之间。在该内容中，您可以指定自定义和预定义变量，以提供有关您的项目的更多信息。这些变量将随后可供您在所有页面和自定义组件中使用。

讨论与前置内容相关的所有变量远远超出了这个快速入门指南的范围。但是，您可以在 Jekyll 项目的网站上查看有关此主题的更多信息：jekyllrb.com/docs/frontmatter/。

现在，让我们回到 VuePress。

在 VuePress 中，YAML 前置内容得到了原生支持，无需使用任何自定义导入或额外扩展。因此，您在三虚线之间指定的任何内容将在整个页面中都可用。

让我们通过一个例子来理解它。考虑以下前置内容代码：

---
title: My Fancy VuePress Site
lang: en-US
meta:
    - name: site description
    content: hey, this is vuepress!
    - name: keywords
    content: vuepress blogging vuejs
---

现在，在上面的例子中，标题和语言变量已经为整个页面指定了。然后，您可以添加自定义的元标签，例如站点描述和与 SEO 相关的关键字，这些将适用于整个页面。

如果 YAML 不是您首选的脚本解决方案，您也可以选择其他选项。TOML 也得到了支持——要使用它，您只需指定您偏好 TOML，如下所示：

---toml
title: My Fancy VuePress Site
lang: en-US
meta:
    - name: site description
    content: hey, this is vuepress!
    - name: keywords
content: vuepress blogging vuejs
---

然而，很多 JavaScript 程序员更喜欢 JSON。在这种情况下，您需要遵循标准的 JSON 格式来处理前置内容；也就是说，使用花括号和引号，就像下面的例子所示：

---
{
“title”: “My Fancy VuePress Site”,
“lang”: “en-US”,
“meta”:
    - “name”: “site description”,
    “content”: “hey, this is vuepress!”,
    - “name”: “keywords”,
    “content”: “vuepress” “blogging” “vuejs”
}
---

前置内容规范在静态站点生成器的世界中非常常见，任何有过使用这类生成器经验的人几乎肯定已经了解了前置内容的作用。

自定义格式选项

在 Markdown 中，VuePress 原生支持一些其他不太常用的格式选项。这些将在下一节中讨论。

代码中的突出显示

您可以选择在代码中突出显示行，以使输出更具可读性。以下是一些示例代码：

export default {
    data () {
        return {
        msg: 'Highlight me!'
        }
    }
}

输出如下：

自定义容器

有时，您可能希望强调内容中的某些部分，比如警告、通知和提示。您可以在 VuePress 中轻松突出它们，以便用户的注意力直接被吸引到手头的内容上。

这意味着您首先需要将给定的内容指定为提示、警告或类似内容。之后，VuePress 将生成所需的通知或提示，并带有给定的彩色容器。

最终的实际外观可能会有所不同，取决于您自己的配置，但这个呈现方式与 GitHub 风格的 Markdown 相当类似，如果您在 GitHub 中有一些关于格式化README和其他 Markdown 文件的经验，您可能已经遇到过这样的自定义内容容器。

以下是您可以这样做的方法：

::: tip
Hello World!
:::

::: warning
Hello World! You have been warned!
:::

::: danger
Hello World! This is a really serious warning.
:::

输出如下所示：

您也可以选择调整每个容器的标题，就像这里所示：

::: tip HOWDY
Hello World!
:::

::: warning STOP
Hello World! You have been warned!
:::

::: danger NOOO
Hello World! This is a really serious warning.
:::

再次，输出将显示如下：

导入代码片段

如果您有包含代码的现有文件，您可以将代码片段从中导入到您的 VuePress 项目中。这样做的语法如下：

<<< @/filepath

但是，您需要记住，您不能在 webpack 中使用路径别名，因为所有代码片段的导入通常必须在 webpack 编译之前执行。

请记住，代码片段的导入是一个实验性功能，仍处于测试阶段。它有时可能不按预期工作。

代码片段导入函数支持行高亮，正如本章前面讨论的那样。在这种情况下，语法将变成以下形式：

<<< @/filepath{highlightLines}

@的默认值将是process.cwd()。

摘要

这就是本章的结束。

在本章中，我们了解了 Markdown 是什么，以及它为什么如此受欢迎，比如它的简单性和可读性，以及易用性。除此之外，我们还介绍了 markdown-it 解析器，这是在静态站点生成工具中渲染 Markdown 的非常常见和流行的实体，比如 VuePress。

我们还介绍了用于 Markdown 的 VuePress 配置值。此外，我们了解了在 VuePress 中可用的几种 Markdown 扩展。当然，这并不是一个详尽的列表。考虑到 VuePress 正在积极开发中，您可以预期最终会添加新的值和扩展。

话虽如此，在完成本章后，您现在应该对 VuePress 中的 Markdown 使用有足够的理解，并且应该能够添加.md文件，按照您希望呈现内容的方式对其进行格式化，并保存它们，以便 VuePress 可以将它们呈现为 HTML 并组合成单页应用程序。

说到单页应用程序（SPAs），我们现在需要涵盖网页开发中一个非常重要的方面——模板和主题！

在上一章中，我们了解了默认的 VuePress 主题以及它对我们的作用，它提供的布局以及我们如何使用它来呈现我们的内容。但是，自定义主题呢？在今天的世界中，通常更喜欢，有时甚至需要网站拥有自己独特的外观和感觉。自定义主题可以帮助您实现这一目标，并使您的网站脱颖而出！

因此，在下一章中，我们将把注意力转向 VuePress 中的自定义主题，并涵盖相关主题。

第六章：VuePress 中的主题开发

在上一章中，我们学习了如何使用 Markdown 格式化我们的内容。在那之前，我们已经建立了一个基本的 VuePress 网站。此外，我们还了解了 VuePress 提供的大部分配置设置。

然而，网站开发的一个关键方面仍然缺失。

是的，我们正在谈论主题开发。正如您可能知道的，一个好的主题或模板是任何网站或博客的无形部分。

VuePress 自带默认主题。在第四章 在 VuePress 中创建网站中，当您设置您的第一个 VuePress 网站时，您已经了解了默认主题以及如何使用它来展示您的内容。

然而，在本章中，我们将重新审视与 VuePress 主题开发和配置相关的一切。这意味着我们不仅将涵盖配置实体和变量，还将重新审视默认的 VuePress 主题以及它的工作原理，它的代码的具体部分可以用于什么等等。

但除此之外，我们还将把注意力转向 VuePress 主题的定制。我们将在本章的后半部分详细讨论自定义主题配置。

在这一章中，您将学习以下内容：

• VuePress 的主题开发

• 主题开发的配置实体和值

• 在 VuePress 中使用默认主题配置进行工作

• 在 VuePress 中的自定义主题开发

• 在 VuePress 中使用 CSS 自定义

• 与 Git 存储库同步

VuePress 中的主题开发

所以现在，不再浪费时间，让我们开始吧！

在 VuePress 中使用主题

VuePress 作为一个静态网站生成器，专注于简单和敏捷。这意味着，与 WordPress 不同，您不会找到大量的主题和插件可供使用。虽然这可能会对一些人构成障碍，因为在某些情况下，易于安装的主题是真正节省时间的，但这种功能性和开发者导向的方法对许多其他人非常有用。

它可以帮助您按照您想要的方式编写主题。此外，您还可以仅使用默认主题，并在几分钟内快速搭建一个现场网站。在第四章 在 VuePress 中创建网站中，我们看到在 VuePress 中设置默认主页就像编辑一个简单的 Markdown 文件一样容易！

是什么以及如何？

当前章节的布局非常简单，因为我们只涉及 VuePress 的一个特定概念——主题。话虽如此，值得记住的是，主题开发本身是一个相当广泛的主题。随着 VuePress 的规模和受欢迎程度的增长，以及随着时间的推移出现新版本，您可能需要复习和修订您的主题开发技能，以确保您遵守 VuePress 和 Vue.js 提出的最新编码标准。

在这一点上，我们将讨论或者说解剖 VuePress 的默认主题结构。这意味着我们将涵盖主页、导航、侧边栏和所有其他相关实体。你可能已经在第四章中学习了基础知识，但现在，我们更感兴趣的是理解这里的代码是如何工作的。你已经在第四章中看到了默认主题的实际应用。

在此之后，我们将把注意力转向定制。在 VuePress 中定制主题需要对默认结构进行一些更改，我们很快就会看到。

但在继续之前，让我们花一点时间来了解一些 VuePress 中基本主题配置值。与我们在之前章节中介绍的 Markdown 配置实体或基本配置实体不同，主题配置并不那么复杂。

主题的配置实体

在这一点上，让我们首先了解一些与 VuePress 主题开发相关的基本配置实体。我们已经在之前的章节中学习了其他配置实体。

主题

主题配置值用于指定自定义主题。这意味着如果您在项目中使用自定义主题，您需要调用主题配置来指定它。

它是字符串类型，默认情况下未定义，因为 VuePress 使用自己的默认主题，除非另有规定。

themeConfig

顾名思义，themeConfig为当前主题提供配置选项。

它是对象类型，默认情况下写作{}。

请注意，themeConfig的内容和选项将根据您的主题结构方式而有所不同。随着您在主题定制中的进展，您将经常使用themeConfig实体。

这里有一个方便的例子。还记得我们在第三章中学到的 Service Worker，VuePress 开发-初步步骤吗？那是一个站点级别的 Service Worker。但是主题级别的呢？

当你使用themeConfig.serviceWorker时，你可以将其定制为仅适用于主题级别的内容。通过themeConfig，你可以定制 VuePress 开发的多个元素，以满足你的主题需求。

这有什么用？

想象一下。你的访问者在多个标签中打开了你的 VuePress 网站，并浏览你的内容。现在，如果你在那个时候更新了你的内容呢？在正常情况下，你的访问者直到关闭并重新打开所有标签，也就是说，硬性的浏览器端刷新或重新加载打开的页面，才能看到新的内容。

当你配置 Service Worker 与themeConfig一起工作时，你也可以用它做一些有趣的事情。其中之一就是弹出窗口的用户界面。

是的，每个人都知道弹出窗口是什么，以及它们有多烦人。但我们不是在谈论类似广告的垃圾弹出窗口。相反，themeConfig.serviceWorker元素将添加一个updatePopup选项，通知用户有新内容可用。

换句话说，当你更新你的网站并且用户打开了标签时，一个弹出窗口将出现，通知用户有新内容，并提供一个刷新按钮，这样新内容就可以立即显示，而不需要关闭客户端。

这个选项在你经常更新的网站上非常有用，比如技术项目的文档等等。

themeConfig.serviceWorker.updatePopup选项的基本语法如下（布尔值）：

module.exports = {
  themeConfig: {
    serviceWorker: {
      updatePopup: true //now popup is set to true and will show up
      // default display for frontend is:  
      // updatePopup: { 
      // message: "New content is available.", 
      // buttonText: "Refresh" 
      // }
    }
  }
}

请注意，截至目前，VuePress 中的弹出功能仍处于测试阶段。

正如你所看到的，themeConfig可以用于各种目的，为你的 VuePress 安装增加更多的功能。

目前就这些了。这是我们需要记住的唯一两个配置值。因此，我们可以把注意力转向默认的 VuePress 主题，以便更好地理解它的功能。

VuePress 中的默认主题配置

这个特定的部分完全只涉及默认的 VuePress 主题。如果你使用自定义主题，大部分或所有这些设置可能不适用。

在这个阶段，强烈建议您转到您在第四章中创建的虚拟站点，在 VuePress 中创建站点。我们涵盖了首页、导航、侧边栏、搜索功能等概念。我们现在将更好地理解这些内容，并了解默认 VuePress 主题提供的其他功能（例如与 GitHub 仓库的集成）。

首页

我们知道默认的 VuePress 主题自带自己的首页布局。为了使用这个布局，我们只需要在根目录的README.md文件中将home:的值设置为true。然后该文件将被 VuePress 解析为index.html，并显示默认的首页。

我们可以通过README.md文件直接向首页添加元数据。在上一章中，我们已经学会了如何以 YAML 格式编写前置内容。因此，现在是分析首页代码的时候了。从第四章中复制相同的首页前置内容，在 VuePress 中创建站点，我们得到以下内容：

---
meta:
  - name: description
    content: Just a simple VuePress site about coffee.
  - name: keywords
    content: vuepress coffee
lang: en-US
home: true
navbar: true
actionText: Learn More →
actionLink: /about
features:
- title: Caffeinated
  details: It is obvious that coffee is surely the greatest beverage known to humans.
- title: Keeps You Awake
  details: Grab some strong coffee and stay awake forever... probably not a healthy idea though. 
- title: Good for Coding
  details: Nobody accepts this but programming is definitely impossible without coffee.
footer: MIT Licensed | A sample VuePress site built by Sufyan bin Uzayr
---

在上面的代码中，我们首先指定了关于我们站点的元数据。然后，我们添加了调用按钮的链接和锚文本详细信息。最后，我们输入要显示的附加信息。

正如我们在第四章中所看到的，在 VuePress 中创建站点，最终结果如下：

在前置内容之后放置的任何内容也会被解析为简化的 Markdown，并显示在首页的前置内容下方。

但是，如果您不想使用默认的首页呢？当然，您可以创建一个自定义主题，但为什么要为添加一个新页面而构建一个新主题呢？

在这种情况下，更好的选择是自定义首页布局。我们可以通过自定义布局来实现这一点。

页面的自定义布局

我们知道每个 Markdown .md文件都是由 VuePress 在 Web 浏览器中呈现为 HTML。一般来说，VuePress 会在 HTML 中的<div class="page">容器中解析 Markdown 文件的内容。

这意味着我们的默认布局——包括主要内容、导航栏和其他链接——都包含在容器内。

因此，这里的任务很简单。如果我们需要添加任何自定义布局或组件，我们只需要确保它包含在我们的默认容器内。

例如，假设我们已经指定了一个名为MyLayout的自定义layout。现在，在 YAML 前置内容中，我们只需要添加以下行：

layout: MyLayout

有了这个，给定页面将呈现新的布局。

通过这种方式，您可以为尽可能多的页面指定自定义布局。

导航栏

VuePress 中的导航栏包括一组通用项目，例如导航菜单、搜索栏、指向您的 GitHub 存储库的链接（如果有的话）等等。

导航栏链接

还记得我们之前讨论过的themeConfig变量吗？您可以使用它向导航栏添加任意数量的链接。

让我们分析以下代码：

// Goes to .vuepress/config.js
 module.exports = {
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'About', link: '/about' },
      { text: 'Coffee', link: '/coffee' },
      { text: 'External', link: 'http://sufyanism.com' },
 ]
 }
 }

在上面的例子中，我们创建了一个简单的导航链接菜单，提供了四个链接：

• 主页

• 关于页面

• 关于咖啡的页面

• 外部链接（GitHub）

相当简单，不是吗？您可以根据需要在这里不断添加链接。在浏览器中的效果如下：

！

那么下拉菜单呢？您只需要将所述链接提供为数组，而不是独立的链接。例如，考虑以下代码：

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Linkz',
        items: [
          { text: 'Home', link: '/' },
          { text: 'About', link: '/about/' }
        ]
      }
    ]
  }
 }

有了这个，链接将显示为下拉菜单。

此外，您还可以拥有非常复杂的菜单，包括下拉条目下的子组和嵌套项目。对于 VuePress 网站，这种类型的菜单结构极不可能被使用，可能也不太有用。尽管如此，这里是这种菜单结构的默认语法，您可以根据自己的需求进行修改：

module.exports = {
  themeConfig: {
    nav: [
      {
        text: 'Label',
        items: [
          { text: 'First', items: [/*  */] },
          { text: 'Second', items: [/*  */] }
        ]
      }
    ]
  }
 }

搜索栏

您可以选择在 VuePress 中使用原生搜索或 Algolia DocSearch。默认搜索栏位置就在导航菜单链接旁边，就像我们在第四章中看到的那样，在 VuePress 中创建站点：

！

原生搜索框

VuePress 自带其自己的原生搜索框，您无需进行调整。但是，如果您愿意，您可以使用themeConfig值完全禁用搜索框，或者限制显示搜索词的建议数量。

以下是如何禁用原生搜索框：

module.exports = {
  themeConfig: {
    search: false,
  }
 }

或者，为了限制建议的数量，尝试以下代码：

module.exports = {
  themeConfig: {
    searchMaxSuggestions: 5
  }
 }

VuePress 中原生搜索的一个很大的缺点是它只从H1、H2和H3标签构建其索引。这意味着它不会扫描实际的正文内容以搜索词。

当然，这样的搜索功能可能不适合每个人，因为通常正确的关键词在内容中而不是标题中。

为了克服这一点，我们可以将外部搜索机制集成到我们的主题中。

使用 Algolia 搜索

如果您对 Algolia DocSearch 不熟悉，可以访问他们的网站并在community.algolia.com/docsearch/上了解更多。

基本上，Algolia DocSearch 是文档搜索引擎的增强版本。它会爬取您的内容，对其进行索引，然后返回更好的搜索结果，涵盖并爬取整个内容，而不仅仅是标题。他们网站的截图如下：

Algolia DocSearch 与各种环境完全兼容，包括 Bootstrap、React，当然还有 Vue.js。此外，它是一种上下文感知的搜索机制，可以随着您的输入而学习。因此，Algolia DocSearch 可以提供一系列功能，这些功能在本机搜索方法中可能缺失，例如：

• 自动完成建议

• 定制分析以查看详细的搜索统计信息

Algolia DocSearch 采用 MIT 许可证，是开源的。因此，为了在您的 VuePress 网站上使用它，您需要在 Algolia 注册一个账户。

Algolia DocSearch 与您的网站集成的详细文档可在github.com/algolia/docsearch#docsearch-options上找到。

一旦您在 Algolia 注册了一个账户，您就可以提交您的网站进行索引和爬取。之后，您只需要告知 VuePress 有关 Algolia DocSearch 引擎。为此，您将再次使用非常方便的themeConfig选项，如下所示：

module.exports = {
 themeConfig: {
 algolia: {
 apiKey: '<API>',
 indexName: '<INDEX>'
 }
 }
 }

请注意，当网站索引完成时，您需要指定自己的 API 密钥和索引名称，这些信息由 Algolia DocSearch 提供。如果缺少 API 密钥或索引名称，或者其中任何一个值不正确，搜索功能将无法正常工作。

如何禁用导航栏？

有时，您可能需要禁用导航栏。在这种情况下，您可以通过themeConfig选项指定如下：

// Goes to .vuepress/config.js
 module.exports = {
  themeConfig: {
    navbar: false
  }
 }

导航栏显示值现在设置为 false，因此它将不会显示在前端。

然而，前面的选项会全局禁用导航栏。要仅针对特定页面禁用它，最好编辑该页面的前置内容，如下所示：

---
 navbar: false
 ---

上一页和下一页的链接

默认情况下，VuePress 会在站点上每个页面的末尾添加上一页和下一页的导航链接。这些链接是根据侧边栏中的标题自动推断的，并从当前页面计算得出。

然而，你也可以覆盖它们的外观和选择。在当前页面的前置内容中，你只需要指定你的选择。例如，对于自定义页面的选择，你可以添加以下内容：

---
 prev: ./another-page
 next: ./yet-another-page
 ---

可选地，你也可以同时禁用两者：

---
 prev: false
 next: false
 ---

或者，只需使用以下代码禁用其中一个：

---
 prev: ./some-fancy-page
 next: false
 ---

或者：

---
 prev: false
 next: ./my-awesome-page
 ---

等等。

这涵盖了关于导航本身的部分。现在，是时候把注意力转向侧边栏了。

侧边栏

VuePress 为你的站点提供了一个基于页面结构和其中的标题链接构建的原生侧边栏。

要为你的站点启用侧边栏，你需要使用themeConfig.sidebar选项通过链接数组进行配置。请注意，以下代码放入你的config.js文件中：

// goes to .vuepress/config.js
 module.exports = {
  themeConfig: {
    sidebar: [
      '/',
      '/page-1',
      ['/page-2', 'optional link text']
    ]
  }
 }

在这个示例中，默认情况下链接会指向README.md文件。这意味着任何以/斜杠结尾的链接都会指向相关的README.md文件。

注意可选的链接文本？如果你在这里指定了某些内容，那么它将显示为侧边栏中的链接文本。或者，如果你在页面的前置内容中指定了标题，那么它将显示为侧边栏中的链接文本。最后，如果在任一位置未指定标题，则 VuePress 将自动从相关页面的第一个标题中选择链接文本。

修改侧边栏中的标题链接

你可以在 VuePress 的侧边栏中玩转标题链接。这里将讨论一些示例。

显示每个页面的标题链接

默认情况下，侧边栏只会显示当前页面的标题链接。你可以将其更改为立即显示所有页面的标题链接。你只需要将相关值设置为true即可，如下所示：

module.exports = {
  themeConfig: {
    displayAllHeaders: true // Default is false
  }
 }

嵌套标题链接

侧边栏，正如你所知，将自动显示当前活动页面的标题链接。因此，当你浏览页面时，相关的标题链接将显示出来，以便更容易导航。

这样的标题是嵌套在活动页面下的，默认深度为1（这意味着所有H2标签都显示为标题，页面标题本身是H1）。

您可以使用themeConfig.sidebarDepth选项修改此行为，以显示更深层次的标题链接嵌套。例如，如果将嵌套深度更改为0，则所有标题链接都将被隐藏，只有H1值（页面标题）会显示。类似地，将深度更改为2将意味着所有嵌套在H2标题链接下的H3标题也会显示，依此类推。

您可以在 front matter 中指定相关深度。例如，要显示H1页面标题，H2标题链接以及H3和H4链接，您将指定深度为3，如下所示：

 ---
 sidebarDepth: 3
 ---

活动标题链接

当用户向下滚动页面时，侧边栏的活动链接会自动更新。这是几乎所有静态站点生成器的默认行为，它们倾向于作为单页面应用程序工作。这样一来，根本不需要刷新或重新加载整个页面。

但是，如果需要的话，您可以通过themeConfig.activeHeaderLinks选项来禁用此行为，如下所示：

module.exports = {
 themeConfig: {
 activeHeaderLinks: false, // Default is true
 }
 }

请注意，这意味着在浏览时不会突出显示活动标题链接，这可能会影响站点的整体用户体验。但是，这也可能会略微提高页面速度，因为相应的脚本将不再加载。

组织侧边栏

您可以选择将侧边栏组织或分成多个组。这是通过对象的帮助实现的。

VuePress 中的侧边栏组默认是可折叠的。但是，您也可以将可折叠选项指定为 false。创建侧边栏组的语法如下：

// goes in .vuepress/config.js
 module.exports = {
  themeConfig: {
    sidebar: [
      {
        title: 'A Group',
        children: [
          '/'
        ]
      },
      {
        title: 'B Group',
        children: [ /* ... */ ]
      }
    ]
  }
 }

这个语法很简单。我们只是用给定的标题创建链接组，然后将页面和链接作为每个组的子项添加。

使用多个侧边栏

确实，您可以为内容的不同部分创建多个侧边栏。

但是，要使其正常工作，您首先需要相应地组织您的内容。一个好主意是将页面组织成目录和子目录。

例如，考虑以下目录结构，其中页面按目录组织：

现在，要创建多个侧边栏，我们需要将以下内容添加到我们的config.js文件中：

// goes in .vuepress/config.js
 module.exports = {
  themeConfig: {
    sidebar: {
      '/testx/': [
        '', /* /testx/readme.md */
        'one', /* /testx/one.md */
        ],

      '/testxy/': [
        '', /* /testxy/readme.md */
       'two' /* /testxy/two.md */
      ],

      // fallback
      '/': [
        '',   /* readme.md at / */
        'about'   /* /about.md */
      ]
    }
  }
 }

上述配置将为每个部分声明侧边栏。请注意，强烈建议仅在最后声明 fallback 选项，因为 VuePress 按照从上到下的顺序读取侧边栏配置；也就是说，按照声明的时间顺序。

为单个页面添加侧边栏

您可以生成包含特定页面的标题链接的自定义迷你侧边栏-通常是当前活动页面。

要实现这一点，您首先需要在相关页面的 front matter 中指定如下：

---
 sidebar: auto
 ---

您也可以在全局范围内重复这个过程。在这种情况下，您可以修改您的config.js文件如下：

// goes in .vuepress/config.js
 module.exports = {
  themeConfig: {
    sidebar: 'auto'
  }
 }

如何禁用侧边栏？

如果您希望在特定页面上禁用侧边栏，可以在 front matter 中指定。这将使页面呈现全宽外观，并且可以按如下方式完成：

---
 sidebar: false
 ---

对于 GitHub 用户

考虑到 VuePress 在其自己的 GitHub 存储库上得到积极维护，并且许多 Vue.js 用户倾向于偏爱 GitHub，VuePress 自然会加载一些对 GitHub 的本地支持。

同步到 GitHub 存储库

您可以通过简单指定存储库名称来轻松地向您的 GitHub 存储库添加编辑链接和更新。

然而，如果您不是 GitHub 用户，依赖于其他服务，如 BitBucket 或 GitLab，您仍然无需担心。在这种情况下，您可以在config.js文件中简单地提供存储库的完整 URL（正如我们将在即将介绍的语法中看到的），您会发现 VuePress 可以从中提取相关信息。

因此，总结一下：

• GitHub 用户只需要告诉 VuePress 要使用哪个存储库

• GitLab 和 BitBucket（或其他基于 Git 的平台用户）需要指定其存储库的完整 URL

要启用此特定功能，您只需要以下代码片段。请特别注意此代码中的注释，因为您需要根据需要更改它以使其正常工作。另外，根据您组织存储库的方式，您可能不需要大部分此代码（例如，如果您的文档不在不同的存储库中，您可以安全地从以下代码中省略该行）：

// goes in .vuepress/config.js
 module.exports = {
  themeConfig: {
    // GitHub by default, provide full URLs for others.
    repo: 'repo-address-here',
    // Customize the header label that is shown in menu
    repoLabel: 'Contribute!',

    // Further options related to “Edit on Git” link

    // if docs are maintained in a separate repo:
    docsRepo: 'docs-repo-here-full-address',
    // if docs are in a sub-directory of main repo:
    docsDir: 'docs-directory-here',
    // if you do not want to use the Master branch on Git:
    docsBranch: 'master-or-branch-name',
    // do you want people to edit your docs? Boolean value
    editLinks: true,
    // modify the “edit this page” link that is shown
    editLinkText: 'Help me edit this page!'
  }
 }

在上面的代码片段中，您需要指定您的存储库地址，以及文档存储库（或您在 VuePress 上托管的任何文学作品）的地址，如果有的话。然后，您可以调整链接的外观，并选择是否希望其他人编辑或为您的存储库做出贡献。

如何在某些页面上隐藏编辑链接？

通常，您希望开源用户为项目或站点上的所有页面做出贡献，但可能有某些页面您希望免受编辑。这在涉及许可、法律条款、版权所有者等页面的情况下尤为重要。

在这种情况下，您只需要使用给定页面的前置内容，并关闭editLink属性，如下所示：

 ---
 editLink: false
 ---

来自 GitHub 的时间戳

在使用 GitHub 存储库时，开发人员通常会展示或显示上次更新时间时间戳，以便跟踪进度，并通知用户所说的项目实际上正在积极开发中。

此时间戳来自 Git 提交，并在给定页面进行第一次提交时显示。之后，每当进行新的提交时，它都会更新。

在 VuePress 中，默认情况下是关闭的。但您可以选择打开它，并将其显示为上次更新的显示。

您可以使用themeConfig.lastUpdated选项，该选项将提取每个页面的最后一个 Git 提交的时间戳，并在页面底部显示它。

语法如下。请注意，时间戳是一个字符串值：

module.exports = {
  themeConfig: {
    lastUpdated: 'Last Updated', // timestamp at bottom of page
  }
 }

这就是在为 VuePress 站点使用 GitHub 存储库时的全部内容。

现在，由于我们正在谈论主题开发，我们需要转向使网页显示其外观的内容。

是的，我们在谈论层叠样式表，或者 CSS。

VuePress 主题开发中的 CSS

此时，我们将看看在 VuePress 中可以使用哪些自定义 CSS 覆盖和更改。

请注意，您需要对 CSS 有一定的了解，以执行本节中建议的任何调整。

页面的自定义类

往往，您可能需要为 VuePress 站点上的特定页面添加自定义 CSS。在这种情况下，您需要添加一个对于给定页面是唯一的自定义类。

到目前为止，您可能已经意识到需要使用 YAML 前置内容声明特定页面的内容。

因此，我们首先需要在 front matter 中的主题容器div中添加唯一的页面类：

 ---
 pageClass: custom-page-class-name
 ---

之后，我们可以安全地为特定页面编写自定义 CSS，如下所示：

/* this will NOT go to .vuepress/config.js */

 .theme-container.custom-page-class-name {
  /* page-specific custom CSS comes here */
 }

但是一个重要的问题是：我们在哪里添加主题容器并编写我们自定义的 CSS 呢？当然不是在 Markdown 文件中。

CSS 覆盖文件结构

第一步是在您的.vuepress/目录中创建一个override.styl文件。这里的一般想法是在这里添加站点范围的常量覆盖，例如颜色，文本颜色等。

例如，要使整个文本颜色为黑色，您可以添加以下内容：

$textColor = #000000

您可以使用普通的 CSS 语法进行编写。但如果您愿意，使用 Stylus 也是一个好主意。

Stylus 是一种 CSS 预处理器，以使在处理 CSS 时更容易阅读和编写而闻名。它支持多次迭代，嵌套运算符，并且不需要冒号，大括号和其他语法装饰。在stylus-lang.com/了解更多关于 Stylus 的信息。

然而，override.styl文件仅适用于 Stylus 常量。那么你自己的额外样式呢？

为此，您需要在.vuepress/目录中添加另一个style.styl文件。在这个文件中，您可以编写任何您希望的 CSS 样式。再次，您可以使用 Stylus 或普通 CSS 语法。

如果您不太喜欢 Stylus，请记住您也可以使用其他 CSS 预处理器，如 LESS 或 SASS。还记得您在第三章中学到的构建流水线配置值，《VuePress 开发-初步步骤》吗？您只需要根据您选择的 CSS 预处理器使用正确的值。

在任何时候，您都可以转到配置值列表（构建流水线）并参考这些内容；这就是为什么本书在第三章中提前很好地涵盖了这一点，《VuePress 开发-初步步骤》。

向后兼容性

这些信息对于较新版本的 VuePress 不再相关。但是，如果您使用的是较旧版本的 VuePress，您甚至可以只使用override.styl文件而不是第二个style.styl文件。考虑以下示例：

// .vuepress/override.styl
 $textColor = black // stylus constants override.

 #my-style {} // extra CSS styles in the same file.

虽然这在实践中对于较旧版本的 VuePress 有效，但即使是这样，它也是双倍的处理。这是因为 Stylus 要求首先编译所有 Stylus 常量覆盖，然后再编译所有用户指定的额外 CSS。

如果你要在override.styl文件中编写你的样式，这意味着同一个文件在被导入一次后会被多次复制。为了避免这种情况，从版本 0.12.0 开始，VuePress 将 CSS 处理分成了override.styl和style.styl文件，如前所述。这是添加自定义 CSS 样式的正确方式。

学习更多关于老版本的 VuePress 是如何处理相同文件的，可以查看这个 GitHub 问题，链接在github.com/vuejs/vuepress/issues/637。

弹出主题

有时，并不需要从头开始创建一个自定义主题。原因有很多：

• 这需要很长时间，特别是在像 VuePress 这样的平台上，它仍处于起步阶段。

• 编写自定义主题需要对 JavaScript 有广泛的了解，而且可能会破坏使用静态网站生成器的初衷，即节省时间和精力。

• 在错误修复、定期更新等方面，维护自定义主题并不总是容易的。

话虽如此，你可能也不喜欢使用默认主题，因为它不能使你的网站脱颖而出。在这种情况下，你可以选择使用自定义 CSS 样式和其他措施，如前所述，即使使用默认主题，也可以使你的网站具有独特的外观。

但如果你希望对默认主题进行重大更改呢？一旦你更新 VuePress，对默认主题源代码所做的任何更改都将丢失。

在这些情况下，你可以复制默认主题，然后编辑复制品，进行更改，就像它是一个自定义主题一样。这就是弹出主题。

要弹出你的主题，你需要输入以下命令：

vuepress eject [target-directory-here]

这个命令将拉取默认主题的源代码，并将其复制到.vuepress/theme子目录中。这个特定的目录将作为你自定义主题的新家，你可以在其中进行更改。

请注意，一旦你弹出你的主题，你将负责它的维护和错误修复。你仍然可以根据需要更新 VuePress，但你将不再获得与默认主题相关的错误修复或功能更新。

确保只有当你知道自己在做什么，并且对 Vue.js 有很好的了解时，才弹出你的 VuePress 主题。当然，这已经超出了这个快速入门指南的范围。

但一旦你确实弹出了你的主题，就是时候转向自定义主题开发了！

VuePress 中的自定义主题开发

为了创建自定义 VuePress 主题，需要使用 Vue 单文件组件。这意味着您需要对 Vue.js 有功能性的了解才能创建 VuePress 主题。如果您发现自己在时间或技能方面缺乏，建议您定制默认的 VuePress 主题，就像本章前面讨论的那样。

说到这里，创建自定义 VuePress 主题的第一步是在 VuePress 的根文件夹中创建一个/theme/目录。

然后，在.vuepress/theme/目录中创建一个layout.vue文件。

然后，您可以像为自定义 Vue.js 应用程序一样进行自定义主题创建。布局选项和设置完全取决于您。

您还可以选择从 npm 依赖项中使用自定义 VuePress 主题。在这种情况下，您需要在config.js文件中使用主题配置选项。只需将以下代码添加到您的.vuepress/config.js文件中：

module.exports = {
  theme: 'your-theme-name'
}

请注意，您需要事先声明并发布主题到 npm，以便将其用作依赖项。

定制默认主题

我们之前讨论过的默认 VuePress 主题可以定制为自定义主题。然而，在这种情况下，您需要弹出默认主题，就像本章前面提到的那样。

在那之后，您可以开始自己调整自定义主题——请注意，一旦您弹出主题，将不会自动复制默认主题的任何未来更新或错误修复。但您可以像往常一样更新 VuePress。

处理元数据

每个 VuePress 主题都需要元数据来正确显示站点详细信息，正如我们已经学到的那样，最好使用布局组件来完成这一点。

在这个阶段，您应该熟悉两个 Vue.js 属性，即$page和$site。这两个属性都被注入到每个组件中。

因此，每次调用布局组件时，$site和$page属性也会被调用。因此，将您站点的元数据放置在this.$site和this.$page中是一个合乎逻辑的想法。

让我们先看看$site。这里是一个示例值：

{
  "title": "Site-Title",
  "description": "Site description comes here",
  "base": "/",
  "pages": [
    {
      "path": "/",
      "title": "Title",
      "frontmatter": { }
    },
    ...
  ]
}

前面的语法非常清楚地显示了$site保存了与整个站点元数据相关的值。

对于$page，我们有以下语法：

{
  "path": "/current/path/to/page",
  "title": "Page Title",
  "headers": [/* ... */],
  "frontmatter": { }
}

可以看到，$page保存了特定页面的元数据。

对于$site 的数值，大部分细节都是从.vuepress/config.js文件中复制而来。但是 pages 数值包含一个数组，其中包括每个页面的元数据对象。这些元数据对象通常是从相关页面的前置内容中提取的，或者是推断出来的，比如页面标题，可以在前置内容中指定，也可以从标题标签中获取。

$page 的数值经常可以用来构建主题的定制行为。您也可以根据需要对页面进行排序。这与定制 Vue.js 应用程序的顺序非常相似。

其他可能的增强

以下是一些其他潜在的指针，您可以在自定义 VuePress 主题时使用。

请注意，您需要对 Vue.js 工作流程有一定的了解，才能实现这些增强。

应用级别的增强

在您的主题根目录中，您可以创建一个enhanceApp.js文件来处理应用级别的增强。

这个特定的文件将导出一个钩子函数。在这个函数中，您应该接收一个包含特定应用程序细节或数据的对象数值。

然后，您可以非常容易地利用这个钩子来注册自定义插件，添加扩展，注册全局组件，定制其他功能等。

这个钩子函数的一般语法如下：

export default ({
  Vue, // the current Vue.js version 
  options, // specify the options for Vue instance
  router, // the router for our app
  siteData // site metadata
}) => {
  // enter custom enhancements here 
}

听起来很混乱？只有当您是经验丰富的 Vue.js 开发人员，并且希望使用 VuePress 构建定制内容时，所有这些才有用。如果您只是想快速建立一个简单的站点，您可以安全地忽略这些细节。

这些都是您开始自定义 VuePress 主题开发所需的所有细节。再次强调，VuePress 中的主题需要对 Vue.js 有相当的了解，最好在进入生产级开发之前先进行一些实验。

总结

这标志着与 VuePress 主题相关的这一特定章节的结束。

在这一章中，我们已经涵盖了相当多的内容。现在我们对默认的 VuePress 主题有了很好的理解，知道如何调整它，如何改变标题链接、导航栏、侧边栏等外观。

此外，对于基于 GitHub 项目构建文档站点的情况，我们还学习了如何将站点与我们的 GitHub 存储库集成。除此之外，我们还学习了如何向我们的主题添加 CSS 样式来改变站点的外观。

不仅如此，我们现在知道如何弹出 VuePress 的默认主题并开始创建我们自己的自定义主题，当然，这也需要 Vue.js 应用程序的知识。

目前，您在本地主机上已经建立了一个活跃的网站，这是您在第四章中创建的在 VuePress 中创建网站。在该网站上尝试主题的更改和调整是一个好主意。本章中有所有的语法和代码示例，但为了清晰起见，我已经避免让它们特定于用例。因此，您可以修改这些通用的代码示例以适应您的生产和网站特定的需求。

结合我们迄今为止的进展，现在您应该能够安装 VuePress，调整config.js文件以修改主题和其他项目，以及在 Markdown 文件中创建内容并上传这些内容。

现在剩下的就是让网站上线，让全世界看到它！

但在此之前，我们需要掌握另一个学习步骤——本地化和国际化。在这方面，我们将讨论 VuePress 对多种语言的支持，以及我们何时以及如何利用这一点。下一章将涉及到这一点，之后我们将把注意力转向让我们的网站在互联网上发布。

第七章：更多 VuePress 的用法！

在之前的章节中，我们学习了如何在 VuePress 中设置和构建网站。我们也知道如何使用 Markdown 格式化我们的内容，以及我们可以如何自定义 VuePress 主题。

总的来说，假设你已经按照上一章的内容进行了学习，现在你应该对 VuePress 有了相当的掌握。

但是，尽管说了这么多，网站开发仍然有一个关键的方面。如今，越来越多的人转向互联网，英语不再是网络上唯一使用的语言。因此，这个特定的关键方面自然涉及到网站的国际化。

在 VuePress 中，国际化并不是什么高深的科学。事实上，为网站内容添加对不同地区和语言的支持非常容易，甚至可以在几分钟内完成。

当然，你仍然需要在你希望添加的语言中输入正确的内容。如果你想到自动翻译，那么你是错误的——国际化并不意味着内容会自动翻译。

那么，你应该如何为 VuePress 添加新的语言？本章将会详细解释。

在本章中，你将学到以下内容：

• 国际化基础知识

• VuePress 的国际化

• 分析 VuePress 作为一款软件的未来增长

VuePress：国际化及其更多用法

但除此之外，你还应该了解关于 VuePress 的其他内容吗？嗯，要记住它正在积极开发中，并不像许多其他内容管理系统那样古老。

因此，我们稍后也会在本章的很大一部分时间来讨论 VuePress 的未来发展，以及现在你已经学会了如何使用它，你应该考虑在什么时候使用它。

现在，让我们从国际化开始。

什么是国际化？

在继续之前，我们首先需要花一点时间来理解国际化是什么意思。

首先要强调的是，国际化实际上并不涵盖内容的机器翻译。

它指的是内容的翻译功能。

国际化本身指的是为了将软件和产品添加支持，以便它们可以轻松地被适应和翻译成其他语言。因此，国际化涉及适当的规划和策略，比如以下内容：

• 理解不同语言的口语和书写方式

• 理解多种语言的文化方面，以及它们的差异

这两点都非常重要。例如，一些语言，比如阿拉伯语，是从右到左书写的，而不是相反。同样，其他一些语言，比如泰米尔语和印地语，有非常复杂的自己的文字，可能对英语使用者来说看起来令人生畏。此外，许多语言，比如日语和中文，通常包含需要特殊符号和键盘布局的字符。

因此，可以说国际化是内容准备好被翻译成用户本地语言的方式和过程。实际上，将内容适应各种本地语言和地区需求的过程称为本地化。

国际化也被缩写为i18n，或者i-18-n，意味着i-eighteen-n；也就是说，从 I 到 N 的 18 个字母。

在软件方面，最大的关注点通常是要确保那些需要单一代码（比如英语）的语言的字符能够轻松转换成需要多于一个字符代码的语言（比如中文）的相应字符。

一旦满足了这个条件和其他一些次要条件，我们可以安全地说给定的软件支持国际化或者是本地化准备就绪的。

VuePress 中的国际化

VuePress 默认支持国际化。这意味着你可以轻松地为你选择的语言添加区域设置，然后将你网站的内容本地化到所需的语言。之后，VuePress 将自动处理繁琐的任务，比如适当的内容结构、菜单切换到其他语言等。

在 VuePress 中，国际化本身是在两个级别实现的：

• 站点级别的配置

• 主题级别的配置

我们将涵盖两者。为了解释起见，我们将在我们的代码中使用任何第二语言，比如法语。然而，为了实际在给定语言中本地化您的站点，您需要正确输入与相关语言有关的详细信息。

VuePress 中的 i18n 配置

让我们首先从主题级别的 i18n 配置开始。

默认主题的 i18n 配置

在默认的 VuePress 主题中，本地化有着原生的支持。这是通过themeConfig.locales选项实现的。

您添加的每个区域理想情况下应该有自己的导航栏和侧边栏选项。侧边栏和导航栏选项已经在第六章中讨论过，VuePress 中的主题开发。此外，您还应该为每个区域单独指定站点特定的元数据和其他字段。

让我们看一下以下代码片段：

module.exports = {
 locales: { /* ... */ },
 themeConfig: {
    locales: {
      '/': {
        // text for the language dropdown in menu
        selectText: 'Languages',
        // label for this language in the language dropdown
        label: 'English',
        // text for the edit-on-github link
        editLinkText: 'Edit this page on GitHub',
        // configuring Service Worker popup UI (optional)
        serviceWorker: {
          updatePopup: {
            message: "New content is available.",
            buttonText: "Refresh"
          }
        },
        // algolia docsearch options (optional)
        algolia: {},
        nav: [
          { text: 'Nested', link: '/nested/' }
        ],
        sidebar: {
          '/': [/* ... */],
          '/nested/': [/* ... */]
        }
      },

     '/fr/': {
        // text for the language dropdown in menu
        selectText: 'Languages-text-in-french',
        // label for this language in the language dropdown
        label: 'French',
        // text for the edit-on-github link
        editLinkText: 'text-in-french',
        // configuring Service Worker popup UI (optional)
        serviceWorker: {
          updatePopup: {
            message: "text-in-french",
            buttonText: "Refresh-text-in-french"
          }
        },
        // algolia docsearch options (optional)
        algolia: {},
        nav: [
          { text: 'Nested', link: '/nested/' }
        ],
        sidebar: {
          '/': [/* ... */],
          '/nested/': [/* ... */]
        } }

    '/es/': {
        // text for the language dropdown in menu
        selectText: 'Languages-text-in-spanish',
        // label for this language in the language dropdown
        label: 'Spanish',
        // text for the edit-on-github link
        editLinkText: 'text-in-spanish',
        // configuring Service Worker popup UI (optional)
        serviceWorker: {
          updatePopup: {
            message: "text-in-spanish",
            buttonText: "Refresh-text-in-spanish"
          }
        },
        // algolia docsearch options (optional)
        algolia: {},
        nav: [
          { text: 'Nested', link: '/nested/' }
        ],
        sidebar: {
          '/': [/* ... */],
          '/nested/': [/* ... */]
        } }
    }
  }
 }

上述代码是做什么的？

好吧，它为我们的主题设置了多个区域设置——英语、法语和西班牙语。

它在菜单中添加了一个下拉框以供选择语言。然后，它以不同语言为 GitHub 的条目，以及 Algolia 搜索和服务工作器弹出 UI 添加了相应的文本。

因此，当用户在我们站点的英语版本上时，他们将看到 Refresh 作为按钮文本。但是当用户在我们站点的法语（位于/fr URL）版本上时，他们将看到法语中的 Refresh 单词，当用户在我们站点的西班牙语版本（位于/es URL）上时，他们将在同一个按钮上看到西班牙语中的 Refresh 单词，这是由我们指定的。

请注意，在上述代码中，您需要输入法语和西班牙语区域的实际对应值。Refresh-text-in-spanish 意味着这是您应该指定相应文本的地方，否则 VuePress 实际上会在前端（字面上）显示短语 Refresh-text-in-spanish。

您可以为任意数量的语言重复此过程。

站点级别的 i18n 配置

现在我们已经看到了如何在 VuePress 的主题级别添加多语言支持。但是，在实际执行之前，我们需要首先在站点级别实现这一点。

因此，在主题中添加对给定区域的支持之前，我们首先需要在我们的config.js文件中指定 locale 选项。

考虑以下站点结构：

请注意，我们创建了三个相同结构的相同文件的副本。/副本显然是用于英文网站。但/fr/和/es/副本分别用于法语和西班牙语版本。fr/about.md文件包含与/about.md文件相同的内容，只是用不同的语言。

现在，一旦我们按照自己的意愿构建了网站，我们就可以在config.js文件中指定 locales 选项，如下所示：

//goes in .vuepress/config.js
module.exports = {
  locales: {
    // The default locale can use '/' as its path
    '/': {
      lang: 'en-US', // this will be set as the lang attribute in HTML
      title: 'Good Morning',
      description: 'English VuePress'
    },
    '/fr/': {
      lang: 'fr-FR',
      title: 'Bon Jour',
      description: 'French VuePress'
    }
     '/es/': {
      lang: 'es-ES',
      title: 'Buenos Dias',
      description: 'Spanish VuePress'
    }
  }
 }

正如你所看到的，我们为每种语言单独指定了标题和描述属性，从而使 VuePress 能够支持多种语言，并根据语言/区域的选择切换到正确的标题、描述和其他信息版本。

如果某个区域恰巧没有自己的标题或描述数值，VuePress 将自动回退到根数值（在我们的情况下是英文）。

在网站级别实施了前述的事情之后，就可以安全地实施主题级别的更改，正如之前讨论的那样。随后，VuePress 将自动在导航栏级别的菜单中添加语言切换器条目。

一个活生生的例子就是官方的 VuePress 网站本身，它已经被本地化为英文和中文。语言切换器出现在菜单中，所有相关的标签也都在必要的位置上。

就 VuePress 而言，这就是我们关于 i18n 讨论的范围。一旦你确定已经添加了正确的目录结构，并为特定主题的区域设置做好了必要的安排，你就可以安全地上线你的网站了。

说到这一点，我们很快将在下一章转向部署。然而，在这个阶段，快速讨论一下关于 VuePress 的其他方面会更明智。

分析 VuePress

现在我们几乎涵盖了与 VuePress 开发相关的所有内容，让我们专注于与这个令人印象深刻的静态网站生成器相关的一些实际方面。

重要的问题是：我们对 VuePress 的了解会带我们去哪里？

或者换个说法：VuePress 在不久的将来会有什么期望，以及长期维护 VuePress 网站会是什么感觉？

VuePress 接下来会怎样？

在这个阶段，这个问题几乎是可以预料的。既然你已经接触了一个全新的静态网站生成工具，接下来会发生什么呢？

VuePress 绝对是一个可能随着时间而受欢迎的解决方案。这主要是因为它提供的一些功能长期以来一直是开发者社区所渴望的。

例如，它直接支持国际化是一个很大的优点。您可以轻松地在多个地区创建网站和项目。

VuePress 的另一个令人印象深刻的地方是，它自带一个完全功能的默认主题。并不是很多静态网站生成器都可以夸耀的事实！更重要的是，正如我们在前一章中所看到的，这个默认主题不仅仅是一个起始或骨架主题。它是一个具有前端显示和令人惊叹的定制范围的完整代码。

此外，VuePress 支持 Markdown 编辑，由于 Markdown 的广泛流行，这也很可能对 VuePress 有利。事实上，即使是流行的工具，如 WordPress，最近也添加了 Markdown 编辑和格式化的插件。基于 Node.js 的常见博客平台 Ghost 也原生支持 Markdown。

既然提到了博客的话题，值得一提的是 VuePress 目前还不完全准备好用于博客。的确，可以使用 VuePress 创建博客，但这样的博客在功能和功能方面将严重缺乏。例如，几乎没有支持博客文章的标记或分类等。

VuePress 仍在积极开发中。这意味着博客支持很可能会在不久的将来被添加，就像 Jekyll 一样。

然而，就目前而言，VuePress 更像是一个文档生成软件，而不是一个博客平台。它可以创建令人惊叹的静态网站，可以作为单页面应用程序动态提供。这正是 VuePress 的独特卖点！

随着时间的推移，随着 VuePress 的势头增加，它也将在受欢迎程度和使用率上升。随着 Vue.js 在 JavaScript 框架世界的不断崛起，VuePress 有着自己坚实的基础和基础。如果 VuePress 继续受欢迎并开始被列为一些顶级静态网站生成器之一，这也不足为奇。

长期使用 VuePress

既然您已经学会了如何使用 VuePress 建立和维护网站，您是否应该考虑长期使用这个工具来进行项目？

你可能已经在使用其他静态网站生成器或类似的服务。在这种情况下，转向 VuePress 对你是否会有额外的好处？

如果你打算为你的项目创建文档站点，那么 VuePress 绝对是你长期应该认真考虑的东西。显然，VuePress 似乎是专门为创建和维护文档而量身定制的。它原生支持国际化、多个标题链接结构、简单的导航机制，并且可以与 GitHub 或 GitLab 集成，以便更轻松地推送更新。

此外，当你考虑其他常用于文档目的的项目时，你会注意到 VuePress 比其他项目具有明显的优势。以 Nuxt.js 为例，它可以创建令人印象深刻和出色的文档站点，但它也是为应用级开发而设计的。

另一方面，VuePress 并不是“样样精通，样样稀松”。你可以使用它构建单页面应用，但几乎无法完全基于 VuePress 构建事件或电子商务注册系统。但是文档呢？完美！

也许 VuePress 与 Markdown 非常契合并且完美集成的事实是另一个需要考虑的因素。如果你是一个喜欢用 Markdown 写作的人（就像我自己一样），VuePress 可能正是你在寻找的静态网站生成 CMS！

另一方面，目前唯一的缺点是，精简的 VuePress 软件目前并没有出色的博客支持。开发人员通常会构建他们的文档站点，类似于博客，包括评论、查询、标签和内容的分类。VuePress 目前没有这些功能。当然，它可能会在不久的将来添加这些功能，但这更多是一种预测，而不是确定性。

说到底，可以肯定地假设如果以下情况之一适用于你，你可以并且应该使用 VuePress：

• 你正在寻找一个简单的静态网站生成器

• 你更喜欢使用 Vue.js

• 你需要具有出色的国际化能力、带有出色默认主题并且支持 Markdown 的东西

• 你的主要目的是整理一系列内容并且 Git 集成可能对你有所帮助

另一方面，如果你符合以下情况之一，你可能会觉得 VuePress 不值得你的努力：

• 如果你需要高级功能的支持，比如博客、杂志式发布、所见即所得编辑等等

• 你不喜欢 Markdown，也不觉得有必要像文档项目一样有条理地组织内容

总结

就是这样！

在本章中，我们涵盖了 VuePress 中与国际化相关的所有内容。通过选择合适的语言环境，你可以轻松将 VuePress 网站本地化为你选择的语言。

另外，我们还简要讨论了 VuePress 可能的未来发展方向。毫无疑问，这款产品正在稳步发展，新功能和 bug 修复也在相当频繁地提供。当然，它可能适合也可能不适合你的工作流程，但如果你需要一个基于 Markdown 并且易于使用的东西，VuePress 绝对值得一试！

未来会怎样呢？

在本书的最后一章中，我们将把注意力转向 VuePress 部署到云端，这样我们就可以将网站上线了。在第四章 在 VuePress 中创建网站中，我们已经创建了一个小型的 VuePress 网站，在接下来的章节中，我们学习了如何使用 Markdown 进行内容编辑以及在 VuePress 中进行主题定制。

当然，学习如何部署我们的 VuePress 网站是有意义的。因此，在接下来的章节中，我们将学习如何将 VuePress 网站部署到 Heroku、Netlify 等服务上！

第八章：将 VuePress 部署到网络上

在本书的前几章中，我们已经对 VuePress 有了相当多的了解。我们从静态站点生成器开始，介绍了 VuePress 的定位，然后进行了安装、设置和变量配置，以及 Markdown 中的实际使用和内容编辑。

除此之外，我们还特别关注了 VuePress 中的本地化、国际化和主题定制。

现在，在这个阶段，你很可能已经在 VuePress 中准备好了一个网站。你可能也已经配置和修改了它。

这意味着我们唯一需要做的就是将我们的网站上线！为了做到这一点，我们需要部署我们的网站，让全世界都能看到它。

Web 应用程序和网站的部署并不是一件大事，如果你有丰富的 Web 开发经验，你可能会经常部署项目。然而，像 VuePress 这样的 JavaScript 应用程序不能简单地在任何服务器上直接上线。通常，共享托管提供商并不直接支持 JavaScript。

因此，在本章中，我们将把注意力转向 VuePress 的部署。我们将涵盖诸如在哪里部署我们的网站，如何做到这一点等主题。

在本章中，您将学习以下内容：

• VuePress 部署建议

• 将 VuePress 部署到各种云/远程托管提供商

• 在 VuePress 站点上使用自定义域名

VuePress 部署-简介

目前，我们有一个 VuePress 网站，我们在第四章中构建了它，在 VuePress 中创建网站。此外，我们还设法在接下来的章节中调整了外观并在 Markdown 中编辑了内容。

因此，我们目前拥有的是一个托管在本地主机上的网站；也就是说，我们自己的设备上。它可以是你正在开发的笔记本电脑或计算机。或者，如果你直接在远程服务器上开发，你可能已经部署了网站。

因此，本章将假设我们构建的网站位于本地存储设备上，并相应地进行。我们将学习如何部署到各种服务，包括以下内容：

• GitHub Pages

• GitLab Pages

• Google Firebase

• Heroku

• Netlify

• Surge.sh

但在继续之前，值得注意的是，我们的重点将仅放在那些要么完全免费使用要么提供免费计划的服务上。当然，如果您已经有一个或者打算获得一个高级计划，您可以选择使用高级计划。但是纯粹为了部署静态站点而注册付费服务几乎没有意义。

自然地，这意味着 VuePress 部署将要求您注册您计划使用的服务。在某些情况下，您可能已经有一个账户，例如，如果您是 GitHub 用户，您已经有一个 Pages 账户；您只需要设置好来使用它。

这就引出了一个重要的问题。为什么我们不能随意使用任何云托管服务来部署我们的 VuePress 网站呢？

VuePress 部署的先决条件

正如我们已经知道的，VuePress 本身的系统要求非常少。它不使用数据库从服务器获取和写入数据，因此很少需要 MySQL 或 MS-SQL。

考虑到 VuePress 作为单页面 Web 应用程序运行，它非常迅速，内存使用低。您甚至可以在内存有限的基本服务器上运行它，而不像其他内容管理系统那样需要大量内存才能运行。

然而，VuePress 确实有一些要求才能正常运行：

• 很明显，VuePress 由 Vue.js 驱动。因此，您的服务器应该支持 JavaScript 和 Vue.js，并安装所有依赖和变量。

• VuePress 需要 Node.js 8 或更高版本才能运行。

我们能使用共享托管来运行 VuePress 吗？

如今，在共享托管环境上运行网站和项目非常普遍，特别是如果它们不是高流量网站。这样的托管计划每月只需花费 3 美元，而且功能齐全。

事实上，许多 WordPress 网站往往可以在共享托管计划上顺利运行，有些甚至可以轻松处理每天超过 25,000 个访问者，如果进行了适当的优化。自然地，考虑在共享托管平台上运行 VuePress 可能是一种诱惑。毕竟，如果 WordPress 和 Drupal 都可以在上面运行，为什么 VuePress 不行呢（它消耗的资源远少于 WordPress 和 Drupal）？

嗯，在教科书上的术语中，是的，VuePress 可以部署到共享服务器上。

实际上，遗憾的是，这样的部署是不可能的。这是因为共享主机往往有自己预配置的变量和语言支持。您无法安装新的依赖项和其他语言或框架，因为您无法访问服务器的根目录。

大多数共享主机提供商默认提供 PHP 和 MySQL，以及 Python 和其他脚本语言。WordPress、Drupal 和其他各种 CMS 都需要 PHP 才能运行。但 JavaScript 框架，如 Vue.js 和 Node.js，在共享主机环境中很少见。

这意味着，虽然理论上您可以在共享服务器上运行 VuePress，但实际上不太可能。对于大多数共享主机提供商来说，支持 Vue.js 站点生成器在其服务器上的机会很渺茫。

那么这是否意味着您需要购买自己的 VPS 或专用服务器？当然不是！

有一些令人惊奇的服务，既免费又付费，可以帮助我们部署 VuePress 站点。

使用 VuePress 部署入门

在开始传输过程之前，请确保您的项目目录结构正确。

如果您将 VuePress 作为现有项目中的本地依赖项使用（请参阅本书的第一章，了解本地依赖项和全局安装之间的区别），您应该在开始部署之前运行以下 npm 命令：

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

VuePress 默认的构建输出位置是.vuepress目录中的 dist 目录。如果您愿意，可以选择更改它，但在本章中，我们将坚持使用默认位置。如果您已更改了默认的构建输出位置，请确保相应编辑您的部署命令。否则，部署可能会失败。

将 VuePress 部署到 GitHub Pages

现在我们将学习如何将现有的 VuePress 站点部署到 GitHub Pages，这是一个非常受开发社区欢迎的托管静态站点的服务。

GitHub Pages 是什么？

GitHub Pages 是一个流行的服务，可以让您为项目部署和托管网站。您也可以直接从 GitHub 存储库部署。这意味着每次您对数据进行更改时，只需将它们推送到 GitHub 存储库，页面站点将相应更新。

GitHub Pages 在托管静态站点方面是一个非常知名的名字。在第一章中，介绍静态站点生成器和 VuePress，您简要介绍了博客工具 Jekyll，它也是一个像 VuePress 一样的静态站点生成器。GitHub Pages 在 Jekyll 中运行得非常好，实际上，它是目前托管 Jekyll 博客最流行的平台。

GitHub Pages 没有单独的定价结构，但您需要注册 GitHub 提供的计划之一。有一个免费的计划，并且对于高端用户，还有带有额外功能的付费计划。

在很大程度上，许多新开发者倾向于完全依赖 GitHub 的免费计划。

用法

使用 GitHub Pages 部署您的 VuePress 站点非常简单。

首先，您需要在config.js文件中指定正确的基础。默认情况下，VuePress 将基础读取为/，因此，如果您部署在根域上，可以选择不指定基础。

在这里，根域指的是类似yourusername.github.io的东西。

但是，如果您要部署到子目录，则需要指定基础。例如，如果您要部署到yourusername.github.io/vuep，那么基础将是/vuep/。

在使用 GitHub Pages 时，您的存储库名称通常也是部署地址。

下一步是创建一个部署脚本。在您的 VuePress 项目中，创建一个名为deploy.sh的文件，具有以下语法（确保将路径替换为您的存储库的路径）：

# !/usr/bin/env sh

# aborting on errors
set -e

# building
npm run docs:build

# navigating to the build output directory
cd .vuepress/dist

# if you are deploying to a custom domain
# be sure to add proper CNAME records to your domain 
echo 'www.myfancydomain.com' > CNAME-record-here

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

# if deploying to https://yourusername.github.io
git push -f git@github.com:yourusername/yourusername.github.io.git master

# or if deploying to https://username.github.io/reponame
git push -f git@github.com:username/repo.git master:gh-pages

请注意，在前述语法的最后两个命令中，您必须根据您的部署路径选择使用其中一个。

就是这样。一旦运行了前述脚本，部署就完成了。请记住，您必须根据您的项目结构指定路径和详细信息。

或者，如果您将 VuePress 作为 Pages 帐户的唯一站点，并且/或者希望创建一个组织站点，您还可以通过存储库直接部署。

为了实现这一点，第一步是使用您的 GitHub 用户名（或组织名称）创建一个新的存储库，类似于username.github.io，如下所示：

下一步是使用以下命令克隆新的存储库：

git clone https://github.com/username/username.github.io

使用前述命令时，请确保将用户名字段更改为您自己的用户名。

然后，剩下的就是添加、提交和推送更改，如下所示：

git add --all
git commit -m "initial commit"
git push -u origin master

使用自定义域名

GitHub Pages 允许用户向其项目站点添加自定义域名，而不受其所在计划的限制。

要将域名映射到您的站点，首先步骤显然是注册该域名。

有许多域名注册商，例如GoDaddy、Register.com、Gandi.net等。我个人使用Namecheap和Name.com注册所有我的域名，但这更多是偏好而不是推荐。

注册域名后，您需要修改其 DNS 记录，指向所涉及的托管平台，例如 GitHub Pages。通常，这是通过 CNAME 记录来实现的，尽管有些平台也可能使用 A 记录。

根据您的域名注册商提供的界面和设置，添加或修改 DNS 记录的程序可能会有所不同。如果有疑问，请务必联系您的注册商支持团队！不正确的配置可能导致域名无法解析。

对于 GitHub Pages，您只需将域名添加到存储库设置（而不是页面设置）中。然后，您只需输入 CNAME 记录并等待 DNS 传播。

您可以在help.github.com/articles/using-a-custom-domain-with-github-pages/找到详细的自定义域名映射指南。

将 VuePress 部署到谷歌 Firebase

VuePress 可以借助 Firebase CLI 工具部署到 Firebase 上。Firebase 是一个众所周知但相对更复杂的选项，用于在云中托管站点和项目。

什么是谷歌 Firebase？

如果您对 Firebase 还不熟悉，首先要注意的是它由谷歌支持。这意味着您的项目将获得企业级可靠性、令人惊叹的云基础设施以及谷歌提供的各种其他功能。

Firebase 让您可以使用谷歌基础设施在云中托管您的应用程序和项目。但它不仅仅止步于此——每个 Firebase 计划（包括免费计划）都附带了各种令人惊叹的功能：

• A/B 测试

• 谷歌分析

• Crashlytics

• 云消息传递（FCM）

• 远程配置

• 性能监控

• 云测试

• 自定义域

• 自定义 SSL 证书

• 还有更多！

事实上，一个简单的 VuePress 网站甚至不需要大多数这些功能。话虽如此，谷歌 Firebase 免费提供如此多的令人惊叹的功能，确实是一笔非常划算的交易！

Firebase 的免费计划为您提供 1GB 的存储空间，但没有数据库访问权限。对于大多数 VuePress 网站来说，这已经足够了。然而，令人遗憾的是，免费计划中只有 10GB 的月度带宽。对于一个繁忙的网站，10GB 的带宽可能不足够。

您也可以选择付费计划，起价为每月 25 美元，或选择按使用量额外付费。这意味着如果您超出了免费计划，您只需支付额外的使用费用。

如果您担心 Google Firebase 的定价结构，您可以使用他们的费用计算器来评估您每月可能支付的费用。在firebase.google.com/pricing/找到计算器。

用法

为了使用 Firebase，我们需要注册一个帐户，无论是免费还是高级。

一旦我们注册了 Firebase，就会得到一个 Firebase ID。确保将其保存在安全的地方（您可以在 Firebase 控制台中找到密钥）。

将项目添加到 Firebase 控制台很简单 - 我们只需要指定项目名称，如图所示（默认情况下，项目将添加到免费计划中）：

一旦我们创建了一个项目，Firebase 将自动带我们进入项目的控制台页面。随意尝试一下；由于 VuePress 还没有连接到 Google Firebase，在这个阶段不用担心破坏任何东西。控制台页面如下所示：

接下来，是时候为我们的 VuePress 实例做好部署的准备了。我们的系统上已经有了 Node 和 npm，但我们需要 Firebase 工具才能在系统上运行 Firebase 命令。

Firebase 工具是一组命令行工具和命令，可用于将代码部署到 Firebase 项目，向 Firebase 添加和删除用户和其他数据，并在需要时读取和写入数据到我们的 Firebase 数据库。更多细节可以在www.npmjs.com/package/firebase-tools找到。

要安装 Firebase 工具，我们需要运行此命令：

npm install -g firebase-tools

安装完成后，我们可以在 CLI 中使用 Firebase 命令。

此时，我们需要在 VuePress 网站的根文件夹中创建两个文件。

首先，我们将创建firebase.json文件，语法如下（添加到您特定的 dist 目录的路径）：

{
 "hosting": {
   "public": "path-to-dist-directory",
   "ignore": [ ]
 }
 }

我们需要创建的第二个文件是.firebaserc（请注意，这是一个点文件，在 Linux/UNIX 系统的文件查看器中默认情况下将被隐藏）。此文件的语法如下（添加您的 Firebase ID）：

{
 "projects": {
   "default": "Firebase-ID-comes-here"
 }
 }

然后，我们只需要使用以下命令构建项目：

npm run docs:build

最后，要部署我们的网站，我们使用此命令：

firebase deploy

就这样！我们的网站将部署在 Firebase 服务器上。

然后，我们可以返回 Firebase 控制台进行其他任务，例如自定义域名映射、A/B 测试、Crashlytics，甚至其他集成，如 AdSense、Slack 等。

使用自定义域名

此时，我们的网站将位于免费子域，类似于yoursite.firebaseapp.com。

要映射自定义域名，在 Firebase 控制台中，我们需要点击“连接域”按钮，如此截图所示：

然后，我们将指定我们的域名，并验证其所有权。最简单的方法是通过 CNAME 记录来实现，如下所示：

请记住，域名传播可能需要几个小时，即使是 CNAME 记录的情况也是如此。

根据我们注册域名的域名注册商，添加 CNAME 记录的过程可能会有所不同。因此，建议与注册商的支持团队联系以获取更多建议。

了解如何将自定义域名连接到 Firebase 的更多信息，请访问firebase.google.com/docs/hosting/custom-domain。

将 VuePress 部署到 Surge

VuePress 可以部署到 Surge.sh 静态站点托管服务。这种特定的服务并不像 Google Firebase 那样功能丰富，但它已被证明非常可靠，并且在性能方面非常快。

什么是 Surge？

Surge 是一个让您可以直接从命令行发布网站到网络的服务。它更适合前端开发人员，但并没有严格限制谁可以使用它。

与 Firebase 不同，后者通常专门为 Android 或其他移动应用开发人员定制，Surge 旨在满足 HTML 和 JavaScript 编码人员的需求，特别是 Web 开发人员的需求。

Surge 自带了针对 Gulp 和 Grunt 的即插即用插件。它还与 GitHub 集成，并支持各种静态站点生成器，包括 Jekyll 和 VuePress！

在定价方面，Surge 也有免费和付费计划。付费计划每月 30 美元，提供无限制的一切，以及自定义 SSL、自定义重定向规则和密码保护。

另一方面，免费计划允许我们添加具有基本 SSL 的自定义域，但不会对发布设置任何限制。这意味着我们可以对我们的网站进行任意数量的更改，而不必担心带宽限制或其他类似问题。这就是使 Surge 对前端开发人员特别有帮助的原因！

用法

在继续之前，我们需要通过 npm 安装 Surge。只需运行以下命令：

npm install -g surge

这应该在我们的系统上安装 Surge，现在我们可以使用 Surge 命令。有关该命令的更多详细信息，请访问www.npmjs.com/package/surge。

之后，我们只需要构建我们的文档，如下所示：

npm run docs:build

最后，是时候部署了（请注意，如果您偶然更改了值或路径，可能需要传递正确的路径到您的 dist 目录）：

surge .vuepress/dist

就是这样！Surge 是最容易使用的静态站点托管服务之一！

如果我们在根目录中添加一个名为404.html的文件，Surge 足够智能，可以将该文件用作自定义 404 页面，在出现页面未找到错误时显示。

使用自定义域

如果您有一个希望使用的自定义域名，最好的做法是遵循官方 Surge 文档，其中包含逐步指南，适用于十多个域名注册商。

此文档可在surge.sh/help/adding-a-custom-domain找到。

然而，值得注意的是，如果我们不使用默认的 surge.sh 子域，我们需要在部署命令中传递自定义域名。因此，前面的命令将改为以下内容：

surge .vuepress/dist mycustomdomain.com

将 VuePress 部署到 Heroku

对于 VuePress 网站使用 Heroku 通常似乎有些大材小用。这是因为 Heroku 提供了大量功能，通常对于简单的 VuePress 网站并不需要。

但是，如果您已经有一个 Heroku 账户（比如，用于您的其他开发项目），将您的 VuePress 网站添加到其中可能比浪费时间、精力和金钱注册另一个服务更有意义。

什么是 Heroku？

Heroku 是一个强大而强大的云托管平台，支持非常广泛的语言、脚本、技术等。您可以轻松在 Heroku 上运行 PHP、JavaScript、Ruby、UNIX、Python、Perl 等许多其他应用程序。

Heroku 还能够支持多个数据库管理系统，如 MySQL 甚至 PostgreSQL。这意味着 Heroku 拥有广泛的用户群，涵盖了多种方法论和编码范式。

当然，在所有这些中，对于静态网站使用 Heroku 可能看起来是不必要的。但是话虽如此，如果您的目标是在您的工作流程的更大框架内使用 VuePress，比如现有的 React 或 Vue.js 应用程序，那么 Heroku 可以为整个项目提供无缝的平台，并与各种管理工具集成。

在定价方面，Heroku 提供了一个非常多样化的定价模型，从 7 美元开始，一直到企业定价，每月达到 500 美元。更合理的是直接呈现定价表的整体情况：

如您所见，免费计划让我们拥有一个工作连接，并且还允许我们映射我们的自定义域。

您可以在www.heroku.com/pricing上计算运行 Heroku 实例的预计成本。

用法

为了将我们的 VuePress 网站部署到 Heroku，我们首先需要注册一个 Heroku 账户。您可以在signup.heroku.com/注册免费账户。注册界面将看起来像这样：

请注意，在注册过程中有选择主要开发语言的要求。如果没有其他主要使用的语言，Node.js 是您需要选择的 VuePress 部署语言。这并不重要；您可以选择任何语言，仍然可以轻松部署其他语言的应用程序。

一旦我们成功创建了一个帐户，我们将被带到 Heroku 仪表板。我们现在可以在这里注册一个新的应用程序：

有两种主要方法可以将 VuePress 项目部署到 Heroku：

• 使用 Heroku CLI 依赖于 Heroku Git

• 连接到 GitHub 本身

连接到 GitHub 意味着我们正在将存储库的一个分支部署到 Heroku，以便更改会自动推送到现场，如下所示：

然而，让我们讨论使用 CLI 的主流路线，因为有时可能更具挑战性。

在继续之前，需要安装 Heroku CLI。使用 npm，只需发出以下命令即可：

npm install -g heroku

然而，在这里情况略有不同。Heroku CLI 依赖于最新版本的 Node，如果我们的系统跟不上它，事情可能会潜在地出错。为了避免这种情况，如果通过 npm 安装了 Heroku CLI，则不提供自动更新。我们需要根据可能或必要的情况手动更新 CLI。

当然，这可能会增加太多额外的工作。更简单的方法是使用官方安装程序。Heroku 为 Windows、Mac 和 Ubuntu 平台提供了安装程序。对于其他 Linux 版本，安装的一般命令如下（以超级用户身份运行）：

sudo snap install --classic heroku

有关 Heroku CLI 安装过程的更多详细信息，以及下载 Windows 和 macOS 安装程序的链接，可在devcenter.heroku.com/articles/heroku-cli找到。

Heroku CLI 需要 Git 才能运行。在安装 Heroku CLI 之前，请确保您的系统已安装 Git。

一旦我们创建了一个帐户并设置了 Heroku CLI，就该使用我们的密码和用户名凭据登录 Heroku 了。我们只需输入以下命令，然后在提示时输入我们的登录详细信息：

heroku login

此后，我们需要在 VuePress 项目的根目录中创建一个static.json文件。该文件应填写以下内容（需要完整指定到dist目录的路径）：

{
  "root": "path-to-vuepress-dist-directory"
 }

static.json文件非常重要，如果没有它，远程部署将无法工作！

完成后，我们需要使用 Heroku Git 进行设置。要添加 Git 提交，请使用以下代码：

# version change
cd project-path

git init

heroku git:remote -a app-name-here
git add
git commit -m "Ready to deploy."

要创建新的应用程序，请输入以下命令：

# creates a new app
heroku apps:create vuepress-app-name

要设置buildpack，请使用此命令：

# buildpack for static sites 
heroku buildpacks:set https://github.com/heroku/heroku-buildpack-static.git

Heroku 的buildpack是一个主要用于静态站点的自定义工具和命令集。在其 GitHub 页面上了解更多关于其用法：github.com/heroku/heroku-buildpack-static。

最后，我们只需要部署我们的网站并推送更改，如下所示：

git push heroku master

我们完成了！关于网站的指标和使用统计可以在 Heroku 仪表板中查看。

使用自定义域名

我们可以在 Heroku 仪表板中为 VuePress 网站添加多个自定义域名。默认情况下，我们的网站只会使用herokuapp.com子域。

然而，为了添加自定义域名，需要验证您的帐户。这可以通过添加信用卡详细信息来完成。虽然信用卡上不会有任何账单或费用，但为了防止滥用 Heroku 系统，这些详细信息是必需的。

添加了自定义域名后，我们可以在域名注册商那里修改 CNAME 记录，将域名指向我们的 VuePress 网站。

将 VuePress 部署到 Netlify

由于其自动化工作机制，Netlify 已经成为 Web 开发人员中的知名品牌。您只需从 GitHub、GitLab 等处推送更改，Netlify 就可以处理其余的工作。

事实上，在使用 Netlify 时很少出现问题的可能性。对于寻找只需点击几下即可使用的云托管服务的人来说，它通常是推荐的解决方案。

不用说，Netlify 也非常适用于 VuePress。

什么是 Netlify？

Netlify 自称为自动化现代 Web 项目的一体化平台。简而言之，它让您可以在全球基础设施上部署您的 Web 项目，具有自动 SSL、自定义域名、多个内容交付网络（CDN）等功能。

您可以选择通过 Git 直接部署，然后根据需要推送更改：

Netlify 的高级计划从每月 45 美元起。然而，免费计划让我们轻松部署个人项目，并且还允许我们使用自定义域名。不足之处在于免费计划有一个用户限制，这排除了任何团队协作。定价选项如下所示：

此外，企业级 CDN 在免费计划中也不可用。但就价值而言，免费计划应该足够用于 VuePress 部署。

用法

为了将我们的网站部署到 Netlify，我们首先需要注册一个计划。之后，我们将能够在其中添加关于我们项目的详细信息。

好消息是，Netlify 提供了多种注册选项。我们可以选择使用 GitHub、GitLab 或 BitBucket 进行注册，然后轻松地推送我们的存储库，如下所示：

或者，我们可以依赖电子邮件注册机制。

Netlify 界面非常出色，因为它非常简洁，所以新手用户不会感到困惑：

我们所需要做的就是点击“从 Git 创建新站点”按钮！

然后，我们需要连接到我们选择的 Git 服务，如下所示：

之后，我们只需要选择我们的项目所在的存储库，然后按照以下选项进行指定：

• 对于构建命令，我们将输入npm run docs:build

• 对于“发布”目录，我们必须指定完整的路径到我们的dist目录，比如.vuepress/dist

就是这样！

使用自定义域名

Netlify 允许我们在免费计划中为我们的网站添加自定义域名。默认情况下，网站首先在sitename.netlify.com子域上线。

网站添加后，我们可以指定要添加的域名，然后根据我们的域名注册商提供的界面添加 CNAME 记录。

值得注意的是，Netlify 也提供域名的 DNS 管理服务，尽管是在付费计划中。

正如所见，将网站部署到 Netlify 相当容易。唯一的问题是，从本地主机进行部署可能会相当棘手。但如果您是 GitHub、GitLab 或 BitBucket 用户，Netlify 是一个非常简单和可靠的部署解决方案。

将 VuePress 部署到 GitLab Pages

与 GitHub Pages 非常相似，GitLab Pages 也是一种类似的提供，并提供几乎相同级别的功能。

此外，与 GitHub Pages 非常相似，GitLab Pages 也非常注重静态站点及其部署。它可以与 Jekyll、Hugo、Harp、Hexo、Pelican 和显然 VuePress 等服务和软件直接配合使用。我们在本书的第一章中学习了这些静态站点生成器，介绍静态站点生成器和 VuePress。

什么是 GitLab Pages？

GitLab Pages 为基于 GitLab 的项目和存储库提供可靠且高度灵活的托管解决方案。虽然 GitLab 在某种意义上与 GitHub 相似，因为这两个服务都基于 Git，但前者也有自托管的选择，最近变得越来越受欢迎。有许多开发人员出于这个原因而更喜欢 GitLab。

GitLab Pages 允许我们连接自定义域名，以及 SSL 证书。我们可以选择在自己的服务器上运行 GitLab，或者在GitLab.com上运行——无论我们的选择是什么，GitLab Pages 仍然可以用来将站点部署到云端。

在定价方面，GitLab 的自管理和托管变体都配备了免费计划。好处是，与 GitHub 不同，我们甚至可以在免费计划中拥有私人项目！付费计划更适合高端特定用途；如果您的最终目标只是建立一个 VuePress 网站，免费计划就足够了。

值得注意的是，GitLab Pages 没有单独的定价结构。无论是免费还是付费，都是针对 GitLab 本身的。GitLab Pages 是所有计划的免费附加组件。

用法

为了将我们的 VuePress 站点部署到 GitLab Pages，我们首先需要确保在我们的config.js文件中指定了正确的基本值。否则，部署将无法正常工作。

默认情况下，VuePress 将基本值读取为/。这意味着如果站点部署在username.gitlab.io，那么我们可以在config.js中省略基本值。

但是，如果我们要在其他地方部署站点，比如username.gitlab.io/mysite，那么我们需要将基本值指定为/mysite/，依此类推。

此外，config.js文件中的dest值设置为public非常重要。否则，GitLab Pages 可能无法读取项目数据。

一旦我们在config.js文件中输入了所需的值，我们需要在 VuePress 项目的根目录中创建一个名为.gitlab-ci.yml的新文件。然后，我们将根据 VuePress 开发人员的建议填充该文件的以下内容：

image: node:9.11.1

 pages:
  cache:
    paths:
    - node_modules/

  script:
  - npm install
  - npm run docs:build
  artifacts:
    paths:
    - public
  only:
  - master

这个文件只是在我们对站点进行更改时运行所需的脚本来构建和部署我们的站点。

使用自定义域名

默认情况下，GitLab Pages 上的每个站点都可以在项目页面地址上访问，例如myusername.gitlab.io/myproject。

我们可以很容易地将其更改为myusername.gitlab.io（即删除/myproject子路径）。我们只需要在设置中输入项目的名称为myusername.gitlab.io即可——这适用于 GitLab Pages 上托管的几乎所有静态站点生成器。

如果我们需要为我们的站点添加自定义域名，这也是可以做到的。为此，我们需要在站点设置中指定域名，然后将相关的 CNAME 记录添加到我们的域名本身。

GitLab Pages 提供了有关自定义域映射的详细指南，网址为docs.gitlab.com//ce/user/project/pages/introduction.html#add-a-custom-domain-to-your-pages-website。

总结

好了，这就是 VuePress 快速入门指南的结束。在本章中，我们介绍了 VuePress 在各种云托管服务上的部署。

远程或云平台的链接

为了方便参考，这里是本章中我们谈论过的云和远程托管提供商的链接：

• GitHub Pages: pages.github.com/

• GitLab Pages: about.gitlab.com/features/pages/

• Google Firebase: firebase.google.com/

• Heroku: heroku.com/home/

• Netlify: www.netlify.com/

• Surge.sh: surge.sh/

结束语

在本书的过程中，我们学习了关于 VuePress 的大量知识，包括以下内容：

• VuePress 在本地主机或机器上的安装

• VuePress 配置

• VuePress 的使用和构建

• VuePress 主题定制

• 使用 Markdown 处理内容

• VuePress 国际化

• 最后，在本章中，我们学习了如何将站点从本地主机或存储设备部署到远程或云平台

随着 VuePress 的开发和部署的进展，您会发现它非常易于使用，并且是一个相当强大的软件。此外，VuePress 仍在积极开发中，是一个相对较新的工具。这意味着随着时间的推移，VuePress 必定会在功能和受欢迎程度上不断增长。

事实上，在我写这本书的时候，VuePress 推出了九个新版本（包括主要版本和次要版本）！

在这一点上，强烈建议并推荐学习 Vue.js，特别是如果你想在 VuePress 中构建项目并做更多事情的话。在当今时代拥有一个 JavaScript 框架总是一个好主意，要牢记 JavaScript 的日益流行。

读者可以在 GitHub 上浏览本书的代码示例仓库，网址是github.com/packtpublishing/vuepress-quick-start-guide。

另外，最新的 VuePress 代码可以在其 GitHub 仓库中找到，网址是github.com/vuejs/vuepress。

话虽如此，我希望你在阅读本书并特别了解 VuePress 的过程中度过了愉快的时光。

编程愉快！