Vitepress:SSG框架使用

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

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

Vitepress

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

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

// .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的信息.

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

---
# 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

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

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就行.

Sekyoro的博客小屋