半天从零快速实现产品静态官网

时间：2023-10-12 10:06:02 | 来源：网站运营

时间：2023-10-12 10:06:02 来源：网站运营

半天从零快速实现产品静态官网：作者：Tony@伽马影迷

背景

通过本教程，你能：

1. 在短时间内搭建产品的个性化官网

2. 编写支持Markdown格式展示的说明书页面

部署效果预览 https://v2.ext.ggt1024.com

选型

通过对支持 markdown 格式、响应式的类似内容构建框架的分析，本文将使用最贴合 Vue 生态的 VuePress 作为基础框架，各框架详细对比如下：

框架	专注	活跃度	备注
GitBook	手册和书籍	99 贡献，1300 使用，3700 克隆，最后更新 2018-12	使用 Ruby 构建；活跃度是对 CLI 工具 统计；GitBook 平台(闭源)在线编辑器上中文输入有 Bug
hexo	博客	164 贡献，10 万 使用，4400 克隆，最后更新 2022-07	使用 node.js 构建
jekyll & GitHub Pages	静态网站和博客	993 贡献，150 万使用，9800 克隆，最后更新 2022-08	使用 Ruby 构建
docsify	手册和文档	171 贡献者，4000 使用，5100 克隆，最后更新 2022-08	使用 node.js 和 Vue 构建；起步早
hugo	静态网站	740 贡献，213 使用，6700 克隆，最后更新 2022-08	使用 Go 构建；默认不支持本地搜索
VuePress v1	静态网站	371 贡献，2.7 万使用，4600 克隆，最后更新 2020-07	基于 node.js 和 Vue 构建；对 Vue 生态友好
VuePress v2	静态网站	42 贡献，5 万使用，710 克隆，最后更新 2020-08	基于 node.js 和 Vue 构建；对 Vue 生态友好

以上「活跃度」中各项数据指标 「贡献」指参与该开源项目提交过代码的用户量； 「使用」指克隆代码并二次开发或在自有项目中使用的用户； 「克隆」可能是无意识的「关注」举动。

各项指标重要性从左到右依次递减。

如果仅从活跃度数据考虑，我们应选择 jekyll 或 hexo。但我们看好 Vue 易上手和 Vue 生态，因此选了 VuePress 。

实现

从 VuePress 文档和搜索引擎结果得知以下几点：

• Vue 生态相关的几个框架的文档清一色用 VuePress 编写：Vue、Vite、Pinia、Vue Router、ElementPlus；
• 首页和布局几乎长一样；
• 主题和样式可自定义，这里的主题和其他网站仅仅修改颜色风格的「主题」不一样，它有固定的页面布局和配置；以默认主题为例
• 首页布局较特殊，默认支持 hero banner 样式，分两部分，上面顶部导航，下面正文内容；
• 非首页布局分三部分，顶部导航，左侧导航，右下侧正文内容。另右侧导航为当页目录(TOC，Table Of Content)默认不显示；
• 目录内容和网页路径一一对应，如

/README.md => //install/README.md => /install//install/foo.md => /install/foo.html我们的场景为实现一个静态页面网站，内容为一款浏览器插件产品文档，包含「安装指南」、「使用指南」和「常见问题解决方法」三部分， 布局和 Vue 文档类似，三个主部分为顶部导航栏项，每个部分为一页编写内容。

综上，使用 vuepress@next 创建项目后，填充三个页面内容+少量配置即可。

文档静态站构建步骤如下。

安装依赖软件包

安装 node

安装 node 的包管理器 yarn

npm install --global yarn

实现 hello world

在命令提示符或终端下执行以下命令：

# extdocs 为我们的项目名，这里可按需自定义mkdir extdocscd extdocsyarn inityarn add -D vuepress@next默认项目目录结构如下

.├── node_modules/ node依赖包安装目录├── package.json npm包信息└── yarn.lock修改 package.json 增加以下

"scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" }在 docs 目录下新建 README.md，写入内容

# helloworld目录结构如下

.├── docs│ └── README.md├── node_modules/├── package.json└── yarn.lock在命令行提示符或终端输入 yarn docs:dev 后再用浏览器打开 http://localhost:8080/ 预览 hello world 。如下图




页面默认布局为三部分，顶部导航，左侧导航，右下侧正文，和预期一致。




修改 docs/README.md 并不需要频繁手动重启 yarn docs:dev ，它是自动热重载 hot-reload，自动监听文件变更并重新编译显示最新内容。

编写完整内容

修改目录结构如下

. ├── docs │ ├── .vuepress │ │ ├── public │ │ │ └── assets/ 可选新增，静态文件目录，放页面引用的图片文件 │ │ │ └── logo.png 入口页面引用的 logo 文件 │ │ ├── styles │ │ │ └── index.scss 可选新建，自定义全局样式 │ │ └── config.ts VuePress 配置 │ │ │ ├── install 新建，以下 install、usage 和 faqs 三个目录分别对应「安装指南」、「使用指南」和「常见问题解决方法」三部分内容 │ │ └── README.md │ ├── usage │ │ └── README.md │ ├── faqs │ │ └── README.md │ │ │ └── README.md 新建，首页 │ └── package.json

1、编写首页内容

VuePress 中的「主题」概念和其他网站仅仅修改颜色风格的「主题」不一样，它有固定的页面布局和配置。

主题(theme) - 布局配置格式刷(formatter) - 配置项

首页默认样式和布局为 hero 样式。如下图，hero 样式是一种特殊常见首页样式和布局，通常在显眼正文显示特大号字体显示正副标题，示例：




修改 docs/README.md 文件内容如下

---home: trueheroText: 伽马影迷插件tagline: 是一个在电脑浏览器中使用的插件程序，帮助电影迷快速了解一部电影。features: - title: 查评分 details: 一键查大众评分和专业评分数据 - title: 看解说 details: 三分钟了解一部电影剧情、比2倍数更快刷剧 - title: 找片源 details: 既可在线看新片正版，也可下载高清无码无删减资源actions: - text: 安装指南 link: /install/ type: primary - text: 使用指南 link: /usage/ type: secondary - text: 常见问题解决方法 link: /faqs/ type: secondaryfooter: Copyright © 2021~ Guangzhou GamMaan Tech LLCfooterHtml: true---预览页面效果（点击图片可查看大图）：




格式刷配置说明：

home=true 定义页面为首页，引用对应格式刷配置项；
heroText tagline 对应 hero 样式中正文显眼位置特大号字体显示正副标题；
features 为产品显著特性，列出吸引用户； actions 为主要内容页面入口按钮/链接；
footer* 为页脚相关。

其他完整配置选项见 https://v2.vuepress.vuejs.org/reference/default-theme/config.html

2、配置顶部导航

新建或修改 docs/.vuepress/config.ts VuePress 统一配置文件，这里可用 JavaScript(.js) 也可用 TypeScript(.ts)，VuePress 都能自动识别。 配置文件内容如下：

import { defineUserConfig } from "vuepress";import { defaultTheme } from "@vuepress/theme-default";export default defineUserConfig({ lang: "zh-CN", title: "伽马影迷插件", description: "影迷、影视自媒体必备神器", theme: defaultTheme({ logo: "/logo.png", navbar: [ { text: "安装指南", link: "/install/", }, { text: "应用商店", children: [ { text: "edge", link: "https://microsoftedge.microsoft.com/addons/detail/cmnchflmcededjokdbjafjcpbhpodmmo", }, ], }, ], }),});上面引用 logo 文件放在 docs/.vuepress/public/logo.png 目录下。

预览页面效果：




配置说明：

lang 定义页面语言，选填； title 设置 HTML title 标签值、顶部导航首页项文字；
description 设置 HTML meta-description 标签值，title 和 description 对于被搜索引擎解释很重要； theme::logo 设置顶部导航首页项 logo； navbar 设置导航项文字和链接，支持嵌套；以上添加了两个，一个没有嵌套，一个有。

3、偏写其他页面内容

续上，点击「安装指南」导航项，会跳转提示 404 (页面找不到)。我们创建对应页面修复这个问题。 创建 docs/install/README.md ，内容如下：

# 插件安装指南## 步骤一在 Edge 浏览器上搜索「伽马影迷插件」，点击搜索结果第一个链接进入应用商店。## 步骤二在「伽马影迷插件」应用商店详情页，点击右边「获取」按钮。再次点击首页顶部导航「安装指南」项后能正常跳转。如下图




页脚显示「上一章」或「上一节」效果，在 docs/install/README.md 顶部添加格式刷配置：

---prev: /---由于 VuePress 是针对开源项目编写文档场景设计，所以还提供了和 Github 相关特殊配置，如

• 在顶部导航栏添加 Github 仓库跳转链接
• 在非首页页面添加「编辑此页面」跳转链接

在 docs/.vuepress/config.ts 配置文件中 defaultTheme 层级添加以下配置：

docsBranch: "master",editLinkText: "编辑此页面",repo: "https://github.com/ggt1024/extdocs",配置说明： docsBranch 文档 Git 代码仓库对应的分支；
editLinkText 自定义非首页显示的Edit this page 按钮链接文本；
repo 导航顶部显示 Github 图标并指向此链接仓库；这里以我们实际使用的 https://github.com/ggt1024/extdocs 为例。

用户在「安装指南」页面页脚点击「编辑此页面」后，会跳转到 Github https://github.com/ggt1024/extdocs 仓库 master 分支上此页面对应的文件。

完整效果：

部署

通过 VuePress 生成文档项目本质是一个 npm 包，将其构建内容结果目录生成一个压缩后，解压到对应 NGINX 类虚拟主机目录，并配置域名即可生效。 打包脚本可参考这里 pack.js 。

部署效果预览 https://v2.ext.ggt1024.com ， 完整代码见 https://github.com/ggt1024/extdocs 。

国内运营的网站需要 ICP 备案，这里不赘述。

总结

VuePress 是一个简单灵活易上手、支持 Markdown 格式编写文档并生成静态页面网站的工具，对程序员友好。 推荐安利给技术类产品、开源项目编写文档或/和官网首页。

参考

• VuePress
• 3 Popular Website Heroes Created With CSS Grid Layout