Vitepress:SSG框架使用

最近想着把一些框架总结的东西放到一个在线文档而不是博客里,于是又在网上搜寻了一些静态网站生成器(事实上现在我用的hexo也算是),这类框架把类似markdown这种build成html,适合文档、博客这种没有后台服务的. 如果你想要复杂的,可以试试Astro入门指南 | Docs (astro.build),这个框架默认服务端渲染.

对于前端,可选的文档框架还是很多的,我最推荐vitepress(这也是本篇文章主要讲的),或者你也可以使用vuepress.

Vitepress

vue的团队打造,很好用.自带的样式不错,自定义性强.

配置文件配置主题的标题,描述

1
2
3
4
5
6
7
8
9
10
// .vitepress/config.js
export default {
// site-level options
title: 'VitePress',
description: 'Just playing around.',

themeConfig: {
// theme-level options
}
}

主题配置包括logo,nav,siderbar,footer等.我试用了一下,适合写产品文档,它本身的官网VitePress | Vite & Vue Powered Static Site Generator就是vitepress写的.

可以在这个配置里写nav和sidebar的信息.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
import { defineConfig } from "vitepress";
// https://vitepress.dev/reference/site-config
export default defineConfig({
title: "protools",
description: "tools which I learn and use",
themeConfig: {
// https://vitepress.dev/reference/default-theme-config
search: {
provider: "local",
},
sidebar: [
{
text: "Web框架",
items: [
{ text: "Node", link: "/node_web" },
{ text: "Python", link: "/python_web" },
],
},
],
nav: [
{
text: "Web框架",
items: [
{ text: "Node", link: "/node_web" },
{ text: "Python", link: "/python_web" },
],
},
],
footer: {
message: "Released under the MIT License.",
copyright: `Copyright ©${new Date().getFullYear()}.Made with ❤ <a href="https://sekyoro.top">Sekyoro</a>`,
},

socialLinks: [
{ icon: "github", link: "https://github.com/drowning-in-codes" },
],
},
});

而Home page作为主页,layout设置为home,其他的可以设置为doc

image-20240401233049341

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
---
# https://vitepress.dev/reference/default-theme-home-page
layout: home

hero:
name: "protools"
text: "tools which I learn and use"
tagline: Help me and others to learn and use.
image:
src: /logo.png
alt: protools
actions:
- theme: brand
text: 'Web框架'
link: '/node_web'
features:
- title: Learn
details: No features
---

在写markdown时可以多利用vitepress自带的一些特性,

写完之后build一下把.vitepress目录下的dist拿来部署就行.我就部署在了vercel上,整个过程很顺畅protools (protool-ten.vercel.app)

但是也有缺点,比如markdown增加了一些东西增加学习成本.不过官方文档还是写得很清楚的.

Docusaurus

1
npx create-docusaurus@latest my-website classic

比较新的东西,使用react写界面

Docsify

也是js的静态网站生成器docsify.不过都有vitepress了,感觉必要性不是很大,这种东西没必要搞几个

1
2
npm i docsify-cli -g
docsify init ./docs

启动完成后,你可以在 ./docs 子目录下看到文件列表。

  • 作为入口文件的 index.html
  • 作为主页的 README.md
  • .nojekyll 阻止 GitHub 页面忽略以下划线开头的文件

下面是Python的文档生成器.适合Python写的库

Mkdocs

mkdocs.org看界面就有Python那种感觉了,毕竟Python的文档经常长这种样子.

1
2
3
pip install mkdocs
mkdocs new my-project
cd my-project

The initial MkDocs layout

mkdocs.yml配置中加上网站信息和nav等

1
2
3
4
5
site_url: https://example.com/
nav:
- Home: index.md
- About: about.md
theme: readthedocs
1
mkdocs build

这种网站可以部署在Host, run, and code Python in the cloud: PythonAnywhere (www.pythonanywhere.com)和github pages上,vercel上目前不太行.

Sphinx

Sphinx初尝 — Sphinx 使用手册 (zh-sphinx-doc.readthedocs.io)

不推荐,本身不支持markdown,使用的是reStructuredText编写,界面也一般.

Read the Docs

免费托管项目,可以使用Sphinx或者Mkdocs.通过recommonmark 来支持markdown.

其他的相当于类似在线服务了,基本上不需要配置直接粘贴内容就行

gitbook

本身还是很不错的服务GitBook – Knowledge management for technical teams

很多人拿来制作电子书

语雀

语雀,为每一个人提供优秀的文档和知识库工具 (yuque.com)国内的平台,正如介绍一样,可以拿来写文档和提供知识

说到语雀,有必要提一下笔记类产品的比较和使用产品分析报告 - 笔记类产品比较)

  • 语雀,在线文档和云端知识库,笔记界的GitHub;
  • 印象笔记,知识管理和效率工具,强调信息的剪藏和管理;
  • 飞书,团队协作和办公利器,帮助B端用户全面激活生产力;
  • Notion,超酷的基于双链和数据库的知识系统,打破了传统的office逻辑,丰富了知识管理的可玩性;
  • Obsidian,基于markdown的双链笔记管理软件,构建你的知识网络;
  • flomo,小而美,强调自由、快速、持续地记录你的想法;

目前市面上笔记软件挺多的,大厂基本都有自己推出的笔记软件.如何选择合适好用的笔记软件还是挺重要的.个人觉得语雀用来撰写和分享,形成知识库. Notion功能比较强大,微软的OneNote可以用来记录随笔和生活.如果按办公和学习记录来分,飞书和Wolai偏向办公,语雀比较中立,Notion用来学习和分享都合适.

最后总结一下,如果写偏技术性文档,偏前端的技术或者产品使用vitepress,其他用read the docs或者mkdocs(也可以都是用vitepress,主要是前端的风格跟vitepress很搭)

如果面向大众的那种知识文档,用gitbook就行.

相关资料

  1. 几款文档框架:Mkdocs、Sphinx、Teadocs、docsify-CSDN博客
  2. Getting Started | VitePress
-------------本文结束感谢您的阅读-------------
感谢阅读.

欢迎关注我的其它发布渠道