LIUのBlog

Docsify 笔记搭建

一、Docsify

1.1 Docsify 简介

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

1.2 Docsify 安装及初始化

  • 全局安装 docsify-cli 工具，可以方便地创建及在本地预览生成的文档。
npm i docsify-cli -g

新建文件夹（名字、位置随意），进入到文件夹，并初始化

# 我的文件在e盘下docs

e:			# 进入到e:
cd docs			# 进入到文件夹
docsify init		# 初始化
  • 初始化成功后，可以看到 ./docs 目录下创建的几个文件
    • index.html 入口文件
    • README.md 会做为主页内容渲染
    • .nojekyll 用于阻止 GitHub Pages 忽略掉下划线开头的文件
  • 直接编辑 ./docs/README.md 就能更新文档内容

1.3 Docsify 服务启动

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

二、Docsify 配置

服务开启且配置后，网页需多刷新几次才会显示配置的内容，Ctrl+R 强制刷新

2.1 侧边栏与目录

  • 在 ./docs 下新建文件 _sidebar.md，并修改 index.html 文件
<!-- index.html -->

<script>
  window.$docsify = {
+   // 侧边栏
+   loadSidebar: true,
    
+   // 最大目录级别
+   subMaxLevel: 2,
  }
</script>

+ <!-- 官方 -->
+ <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

subMaxLevel `控制着侧边栏显示最大目录级数

  • 在 _sidebar.md 文件中添加如下代码
<!-- docs/_sidebar.md --> 

+ [首页](README.md)
+ [指南]()
  • 在 README.md 文件中添加如下代码
## 我是二级标题
### 我是三级标题
  • 刷新网页，即可看到效果

2.2 导航栏

  • 在 ./docs 下新建文件 _navbar.md，并修改 index.html 文件
<!-- index.html -->

<script>
  window.$docsify = {
+   // 导航栏
+   loadNavbar: true,
  }
</script>

-  <!-- Docsify v4 -->
-  <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
  • 在 _navbar.md 文件中添加如下代码
<!-- _navbar.md -->

+ [En](/)
+ [中文](/zh-cn/)

2.3 封面

  • 在 ./docs 下新建文件 _coverpage.md，并修改 index.html 文件
<!-- index.html -->

<script>
  window.$docsify = {
+   // 封面
+   coverpage: true,
  }
</script>

在 _coverpage.md 文件中添加如下代码

<!-- _coverpage.md -->

![logo](https://docsify.js.org/_media/icon.svg)

**#** **docsify <small>3.5</small>**

> 一个神奇的文档网站生成器。

+ 简单、轻便 (压缩后 ~21kB)
+ 无需生成 html 文件 
+ 众多主题 

[GitHub](https://github.com/docsifyjs/docsify/) [Get Started](README)

2.4 主题选择

  • 目前提供三套主题可供选择，模仿 Vue 和 buble 官网订制的主题样式。还有 @liril-net 贡献的黑色风格的主题。
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css">

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css">

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dolphin.css">
  • 将上述主题之一加到 <head></head> 之间，并去掉官方的主题
<head>
- <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@4/lib/themes/vue.css">

+ <!-- 主题 -->
+ <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css">
    
</head>
  • 刷新网页即可看到效果

LIUのBlog

© 2024 LIUのBlog