使用VuePress创建和定制快速文档和博客网站

WBOLT_COM 10 月 09, 2023 513 0

在当今快节奏的数字时代，拥有一个条理清晰、具有视觉吸引力的文档或博客网站，对于吸引受众的注意力并保持他们的参与度至关重要。但是，如何才能在不花费大量时间进行网页开发的情况下实现这一目标呢？

本文将介绍如何使用简约而强大的静态网站生成器（SSG）VuePress 创建和定制一个快速的文档和博客网站。

VuePress 文档和博客演示

什么是 VuePress？

VuePress 是一个开源框架，专门用于生成静态网站，主要面向文档和博客。它是由 Vue.js 背后的天才 Evan You 创建的，体现了 Vue.js 著名的简单易用的理念。

以下是一些令人信服的理由，说明为什么 VuePress 可能是您的最佳选择。

Markdown 简洁性：VuePress 使用 Markdown 简化了内容创建，无需复杂的格式即可轻松编写和组织内容。
Vue.js 集成：VuePress 无缝集成了 Vue.js，支持交互式动态网页元素，带来引人入胜的用户体验。
性能和定制：VuePress 性能卓越，可快速加载静态网站，并提供丰富的自定义选项，以满足您的风格和需求。

VuePress 入门

在深入学习 VuePress 之前，请确保您的计算机上安装了 Node.js 或 Yarn Classic。开始使用 VuePress 有两种方法，一种是使用 create-vuepress-site 生成器，它会为你搭建 VuePress 网站的基本结构；另一种是手动安装。

在本文中，让我们使用手动安装方法。

mkdir vuepress-starter && cd vuepress-starter

使用你喜欢的软件包管理器进行初始化。本文使用 Yarn：

yarn init

将 VuePress 作为开发人员依赖项安装到您的项目中：

yarn add -D vuepress

创建一个 docs 文件夹来存放所有代码，然后创建一个 README.md 文件，作为项目的索引文件，类似于 index.html：

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

在代码编辑器中打开你的项目，在 package.json 文件中添加以下脚本，这样你就可以服务和构建你的网站了：

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

现在，您可以运行 yarn dev 命令来为您的网站提供服务。VuePress 将在 http://localhost:8080 启动你的开发服务器。

手动安装 VuePress 的默认主题

手动安装 VuePress 的默认主题。

现在您已经创建了一个文档网站。您会发现，VuePress 提供了一个简洁、极简的默认主题。不过，它的可定制性很高，让您可以自由发挥创意，为自己的网站打造独特的外观和感觉。

创建文档页面

VuePress 采用简单明了的目录结构来组织文档。在你的项目文件夹中，你会发现我们创建的 docs 目录，在这里你可以为你的文档页面创建 Markdown（ .md ）文件。

例如，你可以创建 getting-started.md、usage.md 和 troubleshooting.md 等文件。导航到 http://localhost:8080/getting-started、http://localhost:8080/usage 和 http://localhost:8080/troubleshooting 时，这些文件会自动成为可访问的路径。

为了加强文档的组织，可以为相关文档页面创建专用文件夹。例如，可以创建一个名为 guide 的文件夹，并将其与特定指南（如 using-kinsta-stsh.md）放在一起。采用这种结构后，using-kinsta-stsh.md 中的内容就可以通过 http://localhost:8080/guide/using-kinsta-stsh 这样的 URL 访问。

您还可以在指南文件夹的根级创建一个 README.md 或 index.md 文件。该文件将作为索引页，允许用户导航至 http://localhost:8080/guide/，并通过侧边栏方便地访问内容，您将在下一节学习如何配置侧边栏。

在这个 VuePress 示例资源库中，你会发现所有这些文件都已创建，而且每个文件都添加了一些标记内容。你可以根据自己的喜好创建文件，既可以从头开始创建以满足你的特定需求，也可以从资源库中的内容中汲取灵感。

自定义 VuePress 外观

一旦您创建了包含内容的文档网站，您可能会发现导航很有难度，尤其是当您有许多文件需要管理时。不过，VuePress 允许您自定义网站的导航结构，使其更加友好和有序。

要自定义网站的外观和导航，请在项目根目录下创建一个 .vuepress 文件夹。该文件夹将存放与 VuePress 网站相关的配置文件和资产。

在 .vuepress 文件夹中创建一个 config.js 文件。您也可以使用 YAML (.yml) 、TOML (.toml) 或 TypeScript (.ts) 等其他文件格式进行配置。

在 config.js 文件中，你可以使用 themeConfig 对象定义网站的导航结构。下面是一个配置示例：

module.exports = {
title: 'Kinsta Vuepress',
description: 'A VuePress QuickStart for Kinsta',
themeConfig: {
nav: [
{
text: 'Guide',
link: '/guide/',
},
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],
sidebar: {
'/guide/': [
{
title: 'Guide',
collapsable: false,
children: ['', 'using-kinsta-stsh'],
},
],
},
},
};

在本例中，我们将配置网站的 title 和 description，定义导航链接，并为 /guide/ 部分设置侧边栏。

nav 数组指定网站顶部的导航链接。侧边栏对象定义特定部分的侧边栏结构。在本例中，它是为 /guide/ 部分配置的。

有关导航栏配置的更多信息，请参阅 VuePress 文档。

样式

VuePress 允许您通过样式自定义网站的外观。您可以使用一些已定义的变量覆盖默认样式，也可以定义自己的样式。要做到这两点，请在 .vuepress 文件夹中创建一个 styles 文件夹。

要对默认预设的样式进行简单的覆盖或定义一些变量供以后使用，可以在 .vuepress/styles 中创建一个 palette.styl 文件。这些是你可以调整的一些预定义变量：

// colors
$accentColor = #5333ED
$textColor = #2c3e50
$borderColor = #eaecef
$codeBgColor = #282c34
$arrowBgColor = #ccc
$badgeTipColor = #42b983
$badgeWarningColor = darken(#ffe564, 35%)
$badgeErrorColor = #DA5961
// layout
$navbarHeight = 3.6rem
$sidebarWidth = 20rem
$contentWidth = 740px
$homePageWidth = 960px
// responsive breakpoints
$MQNarrow = 959px
$MQMobile = 719px
$MQMobileNarrow = 419px

这些变量可用于在整个网站中保持一致的样式。VuePress 还提供了添加额外样式的便捷方法。您可以在 .vuepress/styles 文件夹中创建一个 index.styl 文件，并在其中使用正常的 CSS 语法：

.content {
font-size 30px
}

请在官方文档中阅读有关 VuePress 样式的更多信息。

使用组件

VuePress 支持使用组件来增强页面的功能和外观。您可以创建 Vue 组件并将其包含在您的 Markdown 文件中。在 .vuepres 下创建一个组件文件夹，然后在 .vuepress/components 中找到的任何 *.vue 文件都会自动注册为全局组件。

例如，考虑创建两个组件：HomeOptions.vue 和 HostingBanner.vue：

.
└─ .vuepress
└─ components
├─ HomeOptions.vue
└─ HostingBanner.vue

在这些 vue.js 组件文件中，您可以添加 CSS 代码。让我们在 HomeOptions.vue 和 HostingBanner.vue 组件中添加代码。

在 HomeOptions.vue 中添加以下代码：

<template>
<div class="options">
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/static-site-quick-start-examples/"
target="_blank"
>
<h3>Quick Start Examples</h3>
</a>
<p>Explore quick start examples for setting up static sites.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/getting-started-static-site-hosting/"
target="_blank"
>
<h3>Getting Started</h3>
</a>
<p>Learn how to get started with static site hosting.</p>
</div>
<div class="option">
<a
href="https://kinsta.com/docs/static-site-hosting/manage-static-sites/"
target="_blank"
>
<h3>Manage Static Sites</h3>
</a>
<p>Discover how to efficiently manage your static sites.</p>
</div>
</div>
</template>
<style scoped>
a {
color: #2c3e50;
}
a:hover {
color: #5333ed;
}
.options {
display: flex;
gap: 10px;
margin: 40px 0;
}
.option {
border: 2px solid #eaecef;
border-radius: 5px;
padding: 10px;
}
</style>

另外，将下面的代码添加到 HostingBanner.vue 中：

<template>
<div class="banner">
<p>Host Your Static Site With Kinsta for Free!</p>
<a
href="https://kinsta.com/docs/static-site-hosting/"
target="_blank"
class="btn"
>Read More</a
>
</div>
</template>
<style> scoped>
.banner {
background: rgb(156, 85, 34);
background: linear-gradient(
90deg,
rgba(156, 85, 34, 1) 0%,
rgba(32, 50, 103, 1) 42%,
rgba(13, 18, 25, 1) 69%,
rgba(22, 47, 60, 1) 100%
);
color: #fff;
padding: 20px;
border-radius: 5px;
display: flex;
justify-content: center;
align-items: center;
flex-direction: column;
}
.banner p {
width: 600px;
font-size: 40px;
font-weight: bold;
text-align: center;
line-height: 50px;
}
.banner .btn {
border-radius: 5px;
padding: 15px;
color: #1f1f1f;
font-weight: bold;
background: #fff;
display: inline-block;
margin-bottom: 10px;
}
.banner .btn:hover {
background: #111319;
color: #fff;
}
</style>

在任何 Markdown 文件中，您都可以直接使用这些组件（根据文件名推断名称）：

<HomeOptions/>
<HostingBanner/>

请在文档中阅读有关 VuePress 组件的更多信息。

自定义主页

在 VuePress 中，默认主题提供了一个预先设计好的主页布局，您可以利用它为您的网站创建一个引人入胜、信息丰富的起点。要使用这种主页布局，您需要指定 home: true ，并在根 README.md 文件的 YAML frontmatter 中包含一些额外的元数据。

下面是 YAML frontmatter 的示例：

---
home: true
heroImage: /hero.png
heroText: Hero Title
tagline: Hero subtitle
actionText: Get Started →
actionLink: /guide/
features:
- title: Simplicity First
details: Minimal setup with markdown-centered project structure helps you focus on writing.
- title: Vue-Powered
details: Enjoy the dev experience of Vue + webpack, use Vue components in markdown, and develop custom themes with Vue.
- title: Performant
details: VuePress generates pre-rendered static HTML for each page, and runs as an SPA once a page is loaded.
footer: MIT Licensed | Copyright © 2018-present Evan You
---

所有这些配置将使您的文档主页看起来像这样：

VuePress 默认首页

值得注意的是，如果你喜欢更简单的布局或不包含这些内容，可以通过将相应字段设为 null 来禁用 heroText 和 tagline 或任何其他值。在 YAML 前置事项（即元数据部分）之后包含的任何内容都将被视为常规 Markdown，并在功能部分之后呈现。

如果您想要完全自定义的主页布局，VuePress 也支持自定义布局。此外，您还可以使用 Markdown Slot Syntax 创建富文本页脚，从而更灵活地显示页脚内容。下面是一个如何设置富文本页脚的示例：

---
home: true
---
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::

在这种情况下， ::: slot footer 部分的内容允许您在主页页脚区域添加链接和其他信息。

现在您已了解如何执行上述自定义操作，请将之前创建的组件添加到主页，并移除一些选项，使主页看起来更美观：

---
home: true
tagline: A VuePress QuickStart for Kinsta
actionText: Quick Start →
actionLink: /guide/
---
<HomeOptions/>
<HostingBanner/>
::: slot footer
Made with ❤️ by Kinsta. [Static Site Hosting](https://kinsta.com/static-site-hosting/)
:::

在 VuePress 主页上使用组件

在 VuePress 主页上使用组件。

通过遵循这些 VuePress 定制技术，您可以创建一个文档网站，它不仅能提供有价值的内容，还能通过有序的导航和吸引人的样式提供出色的用户体验。

您可以在文档中阅读有关自定义默认主题的更多信息。

使用 VuePress 创建博客版块

在您的 VuePress 站点中添加博客部分轻而易举，因为 VuePress 允许您编写可插入任何 Markdown 文件的自定义 Vue 组件。让我们创建一个组件来呈现博客文章列表。

在 components 文件夹中创建一个 BlogIndex.vue 文件，并添加以下代码：

<template>
<div>
<div v-for="post in posts" v-bind:key="post.path">
<h2>
<router-link> :to="post.path">{{ post.frontmatter.title }}</router-link>
</h2>
<p>{{ post.frontmatter.description }}</p>
<p><router-link> :to="post.path">Read more</router-link></p>
</div>
</div>
</template>
<script>>
export default {
computed: {
posts() {
return this.$site.pages
.filter(
(x) => x.path.startsWith('/blog/') && !x.frontmatter.blog_index
)
.sort(
(a, b) =>
new Date(b.frontmatter.date) - new Date(a.frontmatter.date)
);
},
},
};
</script>

在提供的代码片段中，您定义了一个 Vue 模板，该模板使用 v-for 循环浏览博客文章，显示文章标题、描述以及每篇文章的 “Read more” 链接。

脚本部分导出一个 Vue 组件，用于计算和检索博客文章。这些文章会根据其路径（以 /blog/ 开头）和是否没有 blog_index frontmatter 属性进行过滤。然后按日期降序排序，首先显示最新的博文。

创建新博文时，需要指定博文日期作为 frontmatter 信息的一部分。这将有助于对博文进行排序，使最新的博文出现在最前面。

要存储博客文章，请在项目根目录下创建一个名为 blog 的文件夹。在该文件夹中，添加一个 README.md 文件。这将是博客索引，你将在其中包含 BlogIndex 组件，以列出所有博客文章。

---
blog_index: true
---
# Blog
Welcome To Our Blog
<BlogIndex />

确保添加 blog_index frontmatter 属性，因为该属性有助于确保博客索引本身不在单个博客文章中列出。在 BlogIndex.vue 组件的 posts 计算属性中筛选文章时，将使用该属性。

接下来，在项目根目录下创建一个博客文件夹，用于存储所有博客文章并创建每个文章。例如，创建 first-post.md 文件并添加以下标记内容：

---
title: "My Exciting VuePress Blog Journey"
date: 2023-09-28
description: "Exploring VuePress, a versatile static site generator, and sharing my experiences along the way."
---
# My Exciting VuePress Blog Journey
In this inaugural blog post, I embark on an exciting journey with VuePress, a powerful static site generator that's perfect for creating documentation, blogs, and more. As I delve into the world of VuePress, I'll be sharing my experiences, insights, and tips on making the most out of this fantastic tool.

对于每篇博文，请确保您定义了重要的前置设置，如博文标题、日期和其他相关元数据。这种细致的组织方式可确保博文的连贯性，并为受众提供引人入胜的阅读体验。

为 VuePress 添加博客

为 VuePress 添加博客。

最后，您可以在 .vuepress/config.js 文件中将博客导航添加到导航栏中：

nav: [
{
text: 'Guide',
link: '/guide/',
},
{ text: 'Blog', link: '/blog/' },
{
text: 'Static Site Hosting',
link: 'https://kinsta.com/static-site-hosting/',
},
],

使用 VuePress，您还可以做很多事情，比如添加插件、使用单独的主题，甚至创建自己的主题。

将 VuePress 静态网站部署到 Kinsta

您可以将代码推送到您喜欢的 Git 提供商（Bitbucket、GitHub 或 GitLab），然后部署到 Kinsta。

在向任何 Git 提供商推送文件之前，请在项目根目录下创建 .gitignore 文件，指定推送代码时 Git 应忽略的文件和文件夹：

# dependencies
/node_modules
# build directory
./docs/.vuepress/dist
/public

提醒：您可以在 .vuepress/config.js 中使用 dest （例如， dest: 'public' ）添加一个目标，从而配置 VuePress SSG 的另一个构建位置。

在本指南中，我们使用 GitHub。在 GitHub 上创建一个仓库来推送源代码。仓库准备就绪后，按照以下步骤将静态网站部署到 Kinsta：

登录或创建账户，查看 MyKinsta 面板。
通过 Git 提供商授权 Kinsta。
单击左侧边栏上的 “Static Sites“，然后单击 “Add site“。
选择要部署的版本库和分支。
为网站指定一个唯一的名称。
按以下格式添加构建设置：
- 构建命令: npm run build
- 节点版本: 16.20.0
- 发布目录: ./docs/.vuepress/dist 或 public