使用Docsify搭建Markdown文件服务器

2023-10-14 10:35:40

使用docsify快速生成文档网站

概述

docsify网站：https://docsify.js.org/#/zh-cn/

docsify 可以快速帮你生成文档网站。不同于 GitBook、Hexo 的地方是它不会生成静态的 .html 文件，所有转换工作都是在运行时。如果你想要开始使用它，只需要创建一个 index.html 就可以开始编写文档并直接部署在 GitHub Pages。

安装 docsify-cli 工具

推荐使用如下命令全局安装 docsify-cli 工具，可以方便地创建及在本地预览生成的文档。

npm i docsify-cli -g

初始化项目

如果想在项目的 ./docs 目录里写文档，直接通过 docsify init 命令初始化项目。

docsify init ./docs

初始化后./docs目录文件结构如下：

文件结构介绍：

index.html 入口文件，在该文件中可以设置docsify配置项，配置项信息请查阅 docsify 配置项。
README.md 会做为主页内容渲染。
.nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件。

直接编辑 docs/README.md 就能更新文档内容，当然也可以添加更多页面。

本地预览

终端运行 docsify serve docs命令启动一个本地服务器，可以方便地实时预览效果。默认访问地址 http://localhost:3000。

docsify serve docs

也可以直接使用浏览器打开./docs目录下的index.html文件进行本地预览。

多页文档

docsify支持设置多页文档，多页文档之间的跳转设置和Markdown文档与文档之间的跳转方式一致。

格式：[显示的文本内容](跳转地址)

配置项

可以在window.$docsify中设置配置项信息。

el

类型：string
默认值：#app

docsify 初始化的挂载元素，可以是一个 CSS 选择器，默认为 #app 如果不存在就直接绑定在 body 上。

window.$docsify = {
  el: '#app',
};

repo

类型：String
默认值: null

配置仓库地址或者 username/repo 的字符串，会在页面右上角渲染一个 GitHub Corner 挂件。

window.$docsify = {
  repo: 'docsifyjs/docsify',
  // or
  repo: 'https://github.com/docsifyjs/docsify/',
};

maxLevel

类型：Number
默认值: 6

默认情况下会抓取文档中所有标题渲染成目录，可配置最大支持渲染的标题层级。

window.$docsify = {
  maxLevel: 4,
};

loadNavbar

类型：Boolean|String
默认值: false

加载自定义导航栏，参考定制导航栏了解用法。设置为 true 后会加载 _navbar.md 文件，也可以自定义加载的文件名。

window.$docsify = {
  // 加载 _navbar.md
  loadNavbar: true,

  // 加载 nav.md
  loadNavbar: 'nav.md',
};

homepage

类型：String
默认值: README.md

设置首页文件加载路径。适合不想将 README.md 作为入口文件渲染，或者是文档存放在其他位置的情况使用。

window.$docsify = {
  // 入口文件改为 /home.md
  homepage: 'home.md',

  // 文档和仓库根目录下的 README.md 内容一致
  homepage:
    'https://raw.githubusercontent.com/docsifyjs/docsify/master/README.md',
};

更多配置项请自行查阅官方文档。

—— END ——

码农公寓