半天從零快速實(shí)現(xiàn)產(chǎn)品靜態(tài)官網(wǎng)

時(shí)間：2023-10-12 10:06:02 | 來(lái)源：網(wǎng)站運(yùn)營(yíng)

時(shí)間：2023-10-12 10:06:02 來(lái)源：網(wǎng)站運(yùn)營(yíng)

半天從零快速實(shí)現(xiàn)產(chǎn)品靜態(tài)官網(wǎng)：作者：Tony@伽馬影迷

背景

通過(guò)本教程，你能：

1. 在短時(shí)間內(nèi)搭建產(chǎn)品的個(gè)性化官網(wǎng)

2. 編寫(xiě)支持Markdown格式展示的說(shuō)明書(shū)頁(yè)面

部署效果預(yù)覽 https://v2.ext.ggt1024.com

選型

通過(guò)對(duì)支持 markdown 格式、響應(yīng)式的類似內(nèi)容構(gòu)建框架的分析，本文將使用最貼合 Vue 生態(tài)的 VuePress 作為基礎(chǔ)框架，各框架詳細(xì)對(duì)比如下：

框架	專注	活躍度	備注
GitBook	手冊(cè)和書(shū)籍	99 貢獻(xiàn)，1300 使用，3700 克隆，最后更新 2018-12	使用 Ruby 構(gòu)建；活躍度是對(duì) CLI 工具 統(tǒng)計(jì)；GitBook 平臺(tái)(閉源)在線編輯器上中文輸入有 Bug
hexo	博客	164 貢獻(xiàn)，10 萬(wàn) 使用，4400 克隆，最后更新 2022-07	使用 node.js 構(gòu)建
jekyll & GitHub Pages	靜態(tài)網(wǎng)站和博客	993 貢獻(xiàn)，150 萬(wàn)使用，9800 克隆，最后更新 2022-08	使用 Ruby 構(gòu)建
docsify	手冊(cè)和文檔	171 貢獻(xiàn)者，4000 使用，5100 克隆，最后更新 2022-08	使用 node.js 和 Vue 構(gòu)建；起步早
hugo	靜態(tài)網(wǎng)站	740 貢獻(xiàn)，213 使用，6700 克隆，最后更新 2022-08	使用 Go 構(gòu)建；默認(rèn)不支持本地搜索
VuePress v1	靜態(tài)網(wǎng)站	371 貢獻(xiàn)，2.7 萬(wàn)使用，4600 克隆，最后更新 2020-07	基于 node.js 和 Vue 構(gòu)建；對(duì) Vue 生態(tài)友好
VuePress v2	靜態(tài)網(wǎng)站	42 貢獻(xiàn)，5 萬(wàn)使用，710 克隆，最后更新 2020-08	基于 node.js 和 Vue 構(gòu)建；對(duì) Vue 生態(tài)友好

以上「活躍度」中各項(xiàng)數(shù)據(jù)指標(biāo) 「貢獻(xiàn)」指參與該開(kāi)源項(xiàng)目提交過(guò)代碼的用戶量； 「使用」指克隆代碼并二次開(kāi)發(fā)或在自有項(xiàng)目中使用的用戶； 「克隆」可能是無(wú)意識(shí)的「關(guān)注」舉動(dòng)。

各項(xiàng)指標(biāo)重要性從左到右依次遞減。

如果僅從活躍度數(shù)據(jù)考慮，我們應(yīng)選擇 jekyll 或 hexo。但我們看好 Vue 易上手和 Vue 生態(tài)，因此選了 VuePress 。

實(shí)現(xiàn)

從 VuePress 文檔和搜索引擎結(jié)果得知以下幾點(diǎn)：

• Vue 生態(tài)相關(guān)的幾個(gè)框架的文檔清一色用 VuePress 編寫(xiě)：Vue、Vite、Pinia、Vue Router、ElementPlus；
• 首頁(yè)和布局幾乎長(zhǎng)一樣；
• 主題和樣式可自定義，這里的主題和其他網(wǎng)站僅僅修改顏色風(fēng)格的「主題」不一樣，它有固定的頁(yè)面布局和配置；以默認(rèn)主題為例
• 首頁(yè)布局較特殊，默認(rèn)支持 hero banner 樣式，分兩部分，上面頂部導(dǎo)航，下面正文內(nèi)容；
• 非首頁(yè)布局分三部分，頂部導(dǎo)航，左側(cè)導(dǎo)航，右下側(cè)正文內(nèi)容。另右側(cè)導(dǎo)航為當(dāng)頁(yè)目錄(TOC，Table Of Content)默認(rèn)不顯示；
• 目錄內(nèi)容和網(wǎng)頁(yè)路徑一一對(duì)應(yīng)，如

/README.md => //install/README.md => /install//install/foo.md => /install/foo.html我們的場(chǎng)景為實(shí)現(xiàn)一個(gè)靜態(tài)頁(yè)面網(wǎng)站，內(nèi)容為一款瀏覽器插件產(chǎn)品文檔，包含「安裝指南」、「使用指南」和「常見(jiàn)問(wèn)題解決方法」三部分， 布局和 Vue 文檔類似，三個(gè)主部分為頂部導(dǎo)航欄項(xiàng)，每個(gè)部分為一頁(yè)編寫(xiě)內(nèi)容。

綜上，使用 vuepress@next 創(chuàng)建項(xiàng)目后，填充三個(gè)頁(yè)面內(nèi)容+少量配置即可。

文檔靜態(tài)站構(gòu)建步驟如下。

安裝依賴軟件包

安裝 node

安裝 node 的包管理器 yarn

npm install --global yarn

實(shí)現(xiàn) hello world

在命令提示符或終端下執(zhí)行以下命令：

# extdocs 為我們的項(xiàng)目名，這里可按需自定義mkdir extdocscd extdocsyarn inityarn add -D vuepress@next默認(rèn)項(xiàng)目目錄結(jié)構(gòu)如下

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

"scripts": { "docs:dev": "vuepress dev docs", "docs:build": "vuepress build docs" }在 docs 目錄下新建 README.md，寫(xiě)入內(nèi)容

# helloworld目錄結(jié)構(gòu)如下

.├── docs│ └── README.md├── node_modules/├── package.json└── yarn.lock在命令行提示符或終端輸入 yarn docs:dev 后再用瀏覽器打開(kāi) http://localhost:8080/ 預(yù)覽 hello world 。如下圖




頁(yè)面默認(rèn)布局為三部分，頂部導(dǎo)航，左側(cè)導(dǎo)航，右下側(cè)正文，和預(yù)期一致。




修改 docs/README.md 并不需要頻繁手動(dòng)重啟 yarn docs:dev ，它是自動(dòng)熱重載 hot-reload，自動(dòng)監(jiān)聽(tīng)文件變更并重新編譯顯示最新內(nèi)容。

編寫(xiě)完整內(nèi)容

修改目錄結(jié)構(gòu)如下

. ├── docs │ ├── .vuepress │ │ ├── public │ │ │ └── assets/ 可選新增，靜態(tài)文件目錄，放頁(yè)面引用的圖片文件 │ │ │ └── logo.png 入口頁(yè)面引用的 logo 文件 │ │ ├── styles │ │ │ └── index.scss 可選新建，自定義全局樣式 │ │ └── config.ts VuePress 配置 │ │ │ ├── install 新建，以下 install、usage 和 faqs 三個(gè)目錄分別對(duì)應(yīng)「安裝指南」、「使用指南」和「常見(jiàn)問(wèn)題解決方法」三部分內(nèi)容 │ │ └── README.md │ ├── usage │ │ └── README.md │ ├── faqs │ │ └── README.md │ │ │ └── README.md 新建，首頁(yè) │ └── package.json

1、編寫(xiě)首頁(yè)內(nèi)容

VuePress 中的「主題」概念和其他網(wǎng)站僅僅修改顏色風(fēng)格的「主題」不一樣，它有固定的頁(yè)面布局和配置。

主題(theme) - 布局配置格式刷(formatter) - 配置項(xiàng)

首頁(yè)默認(rèn)樣式和布局為 hero 樣式。如下圖，hero 樣式是一種特殊常見(jiàn)首頁(yè)樣式和布局，通常在顯眼正文顯示特大號(hào)字體顯示正副標(biāo)題，示例：




修改 docs/README.md 文件內(nèi)容如下

---home: trueheroText: 伽馬影迷插件tagline: 是一個(gè)在電腦瀏覽器中使用的插件程序，幫助電影迷快速了解一部電影。features: - title: 查評(píng)分 details: 一鍵查大眾評(píng)分和專業(yè)評(píng)分?jǐn)?shù)據(jù) - title: 看解說(shuō) details: 三分鐘了解一部電影劇情、比2倍數(shù)更快刷劇 - title: 找片源 details: 既可在線看新片正版，也可下載高清無(wú)碼無(wú)刪減資源actions: - text: 安裝指南 link: /install/ type: primary - text: 使用指南 link: /usage/ type: secondary - text: 常見(jiàn)問(wèn)題解決方法 link: /faqs/ type: secondaryfooter: Copyright © 2021~ Guangzhou GamMaan Tech LLCfooterHtml: true---預(yù)覽頁(yè)面效果（點(diǎn)擊圖片可查看大圖）：




格式刷配置說(shuō)明：

home=true 定義頁(yè)面為首頁(yè)，引用對(duì)應(yīng)格式刷配置項(xiàng)；
heroText tagline 對(duì)應(yīng) hero 樣式中正文顯眼位置特大號(hào)字體顯示正副標(biāo)題；
features 為產(chǎn)品顯著特性，列出吸引用戶； actions 為主要內(nèi)容頁(yè)面入口按鈕/鏈接；
footer* 為頁(yè)腳相關(guān)。

其他完整配置選項(xiàng)見(jiàn) https://v2.vuepress.vuejs.org/reference/default-theme/config.html

2、配置頂部導(dǎo)航

新建或修改 docs/.vuepress/config.ts VuePress 統(tǒng)一配置文件，這里可用 JavaScript(.js) 也可用 TypeScript(.ts)，VuePress 都能自動(dòng)識(shí)別。 配置文件內(nèi)容如下：

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: "應(yīng)用商店", children: [ { text: "edge", link: "https://microsoftedge.microsoft.com/addons/detail/cmnchflmcededjokdbjafjcpbhpodmmo", }, ], }, ], }),});上面引用 logo 文件放在 docs/.vuepress/public/logo.png 目錄下。

預(yù)覽頁(yè)面效果：




配置說(shuō)明：

lang 定義頁(yè)面語(yǔ)言，選填； title 設(shè)置 HTML title 標(biāo)簽值、頂部導(dǎo)航首頁(yè)項(xiàng)文字；
description 設(shè)置 HTML meta-description 標(biāo)簽值，title 和 description 對(duì)于被搜索引擎解釋很重要； theme::logo 設(shè)置頂部導(dǎo)航首頁(yè)項(xiàng) logo； navbar 設(shè)置導(dǎo)航項(xiàng)文字和鏈接，支持嵌套；以上添加了兩個(gè)，一個(gè)沒(méi)有嵌套，一個(gè)有。

3、偏寫(xiě)其他頁(yè)面內(nèi)容

續(xù)上，點(diǎn)擊「安裝指南」導(dǎo)航項(xiàng)，會(huì)跳轉(zhuǎn)提示 404 (頁(yè)面找不到)。我們創(chuàng)建對(duì)應(yīng)頁(yè)面修復(fù)這個(gè)問(wèn)題。 創(chuàng)建 docs/install/README.md ，內(nèi)容如下：

# 插件安裝指南## 步驟一在 Edge 瀏覽器上搜索「伽馬影迷插件」，點(diǎn)擊搜索結(jié)果第一個(gè)鏈接進(jìn)入應(yīng)用商店。## 步驟二在「伽馬影迷插件」應(yīng)用商店詳情頁(yè)，點(diǎn)擊右邊「獲取」按鈕。再次點(diǎn)擊首頁(yè)頂部導(dǎo)航「安裝指南」項(xiàng)后能正常跳轉(zhuǎn)。如下圖




頁(yè)腳顯示「上一章」或「上一節(jié)」效果，在 docs/install/README.md 頂部添加格式刷配置：

---prev: /---由于 VuePress 是針對(duì)開(kāi)源項(xiàng)目編寫(xiě)文檔場(chǎng)景設(shè)計(jì)，所以還提供了和 Github 相關(guān)特殊配置，如

• 在頂部導(dǎo)航欄添加 Github 倉(cāng)庫(kù)跳轉(zhuǎn)鏈接
• 在非首頁(yè)頁(yè)面添加「編輯此頁(yè)面」跳轉(zhuǎn)鏈接

在 docs/.vuepress/config.ts 配置文件中 defaultTheme 層級(jí)添加以下配置：

docsBranch: "master",editLinkText: "編輯此頁(yè)面",repo: "https://github.com/ggt1024/extdocs",配置說(shuō)明： docsBranch 文檔 Git 代碼倉(cāng)庫(kù)對(duì)應(yīng)的分支；
editLinkText 自定義非首頁(yè)顯示的Edit this page 按鈕鏈接文本；
repo 導(dǎo)航頂部顯示 Github 圖標(biāo)并指向此鏈接倉(cāng)庫(kù)；這里以我們實(shí)際使用的 https://github.com/ggt1024/extdocs 為例。

用戶在「安裝指南」頁(yè)面頁(yè)腳點(diǎn)擊「編輯此頁(yè)面」后，會(huì)跳轉(zhuǎn)到 Github https://github.com/ggt1024/extdocs 倉(cāng)庫(kù) master 分支上此頁(yè)面對(duì)應(yīng)的文件。

完整效果：

部署

通過(guò) VuePress 生成文檔項(xiàng)目本質(zhì)是一個(gè) npm 包，將其構(gòu)建內(nèi)容結(jié)果目錄生成一個(gè)壓縮后，解壓到對(duì)應(yīng) NGINX 類虛擬主機(jī)目錄，并配置域名即可生效。 打包腳本可參考這里 pack.js 。

部署效果預(yù)覽 https://v2.ext.ggt1024.com ， 完整代碼見(jiàn) https://github.com/ggt1024/extdocs 。

國(guó)內(nèi)運(yùn)營(yíng)的網(wǎng)站需要 ICP 備案，這里不贅述。

總結(jié)

VuePress 是一個(gè)簡(jiǎn)單靈活易上手、支持 Markdown 格式編寫(xiě)文檔并生成靜態(tài)頁(yè)面網(wǎng)站的工具，對(duì)程序員友好。 推薦安利給技術(shù)類產(chǎn)品、開(kāi)源項(xiàng)目編寫(xiě)文檔或/和官網(wǎng)首頁(yè)。

參考

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