docsify， 一款神奇的文档生成工具

最近，在整理项目时，总感觉文档不够全面，希望有一款能够简单配置就能书写文档的工具，通过对gitbook、docusaurus、docsify的研究发现，制作一份精致的文档，

那么使用docsify是不错的选择，docsify是一个文档生成工具，它直接加载 Markdown 文件并动态渲染，同时还可以生成封面页。所以我们只需要写完 Markdown 文档，就可以看到文档页面了。

docsify介绍

docsify 可以快速帮你生成文档网站。docsify 可以自动地将 Markdown 中的标题生成目录，并且可以配合码云（国内的访问速度比 GitHub Pages 更快）快速搭建一个小型的文档网站，整个页面的配色和布局也十分舒适，让阅读体验在不知不觉中提升了好几个档次。

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

 

特性

  • 无需构建，写完文档直接发布
  • 容易使用并且轻量 (~19kB gzipped)
  • 智能的全文搜索
  • 提供多套主题
  • 丰富的 API
  • 支持 Emoji
  • 兼容 IE10+
  • 支持 SSR (example)

 

一、快速搭建

docsify与Vue cli很相似，都依赖于Node.js，首先需要安装Node.js支持环境，开发才能正常进行。

1.全局安装docsify

#使用npm安装docsfiy-cli 脚手架
npm i docsify-cli -g

安装完成之后就可以看到如下图所示

2.查看版本

docsify -v  #查看版本

3. 初始化项目

使用命令 docsify init ./项目名初始化项目

docsify init ./项目名  #初始化项目

初始化一个名为mydocs的项目，mydocs是自己命名的项目名

 

 初始化成功后，可以看到已经生成了一个名为mydocs的项目，里面包含3个文件index.html、README.md、.nojekyll。

 

  • index.html 入口文件
  • README.md 会做为主页内容渲染
  • .nojekyll 用于阻止 GitHub Pages 会忽略掉下划线开头的文件

 

4.运行项目

在项目文件同一级目录，使用命令docsify serve 项目名启动项目

#不指定端口，默认端口是3000
docsify serve 项目名 
#指定端口
docsify serve 项目名 --port 端口

 

 

5.访问项目 

在浏览器输入项目地址http://localhost:4000/，出现如下界面，代表已经搭建成功了!!!

 

 

二、常用配置项

下面做一些常用项的介绍，如需了解更多配置，可以参考官方文档。

1. 标题与 GitHub Corner 挂件

通过设置index.html中window.$docsify的 repo 参数配置仓库地址或者 username/repo 的字符串，会在页面右上角渲染一个 GitHub Corner 挂件，点击即可跳转到Github中对应的项目地址。
<script>
    window.$docsify = {
      name: '我的文档',
      repo: 'https://github.com/Hanxueqing/Douban-Movie.git'
    }
</script>

 

 

 

 

 2.封面

通过设置index.html中window.$docsify的 coverpage 参数，即可开启渲染封面的功能。

<script>
    window.$docsify = {
    　　name: '文档中心',//标题名称
    　　repo: '',//GitHub Corner 挂件
    　　coverpage: true,//激活封面功能。如果为true，则会从中加载_coverpage.md。
    }
</script>

封面的生成同样是从 markdown 文件渲染来的。开启渲染封面功能后在文档根目录创建 _coverpage.md 文件，在文档中编写需要展示在封面的内容。

![logo](httpsdocsify.js.org_mediaicon.svg)

# 我的文档

 使用docsify搭建在线文档.


[GitHub](httpsgithub.comHanxueqingDouban-Movie.git)
[Get Started](#quick-start)

 展示效果如图：

 

 

目前的背景是随机生成的渐变色，我们自定义背景色或者背景图。可以参考官网文档封面这一章节自行设置。 

3.主题

直接打开 index.html 修改替换 css 地址即可切换主题，官方目前提供五套主题可供选择，模仿 Vue 和 buble 官网订制的主题样式。还有 @liril-net 贡献的黑色风格的主题。

<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/buble.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dark.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/pure.css">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/dolphin.css">

其他主题docsify-themeable又提供了三种样式（Defaults、Simple、Simple Dark）可供选择，需要使用的时候使用其中一种就可以了：

<!-- Theme: Defaults -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
<!-- Theme: Defaults -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-defaults.css">
<!-- Theme: Simple Dark -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple-dark.css">

其他样式风格

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/docsify-themeable@0/dist/css/theme-simple.css">

 

4.多页面

README.md作为主页面，如果需要创建多个页面，或者需要多级路由的网站，在 docsify 里也能很容易的实现。直接在文档目录下创建对应的 *.md 文件，例如创建一个guide.md那么对应的路由就是/#/guide。

假设你的目录结构如下：

.
└── mydocs
    ├── README.md
    ├── guide.md
    └── zh-cn
        ├── README.md
        └── guide.md

那么对应的访问页面将是:

mydocs/README.md        => http://domain.com
mydocs/guide.md         => http://domain.com/guide
mydocs/zh-cn/README.md  => http://domain.com/zh-cn/
mydocs/zh-cn/guide.md   => http://domain.com/zh-cn/guide

 

4.定制侧边栏

为了获得侧边栏，您需要创建自己的_sidebar.md，你也可以自定义加载的文件名。默认情况下侧边栏会通过 Markdown 文件自动生成，效果如当前的文档的侧边栏。

首先配置 loadSidebar 选项，在index.html里面，修改配置，具体配置规则见配置项#loadSidebar。

<script>
  window.$docsify = {
    loadSidebar: true
  }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

创建一个_sidebar.md文件，内容如下

* [首页](zh-cn/)
* [指南](zh-cn/guide)

注意：需要在 ./mydocs 目录创建 .nojekyll 命名的空文件，阻止 GitHub Pages 忽略命名是下划线开头的文件。

5.顶部导航栏

 方法一：如果项实现顶部navbar导航栏，可以开启顶部导航配置，loadNavbar: true

<script>
    window.$docsify = {
      name: '文档中心',
      repo: '',
      loadSidebar: true, //侧边栏
      loadNavbar: true,//顶部导航
    }
</script>

然后新建一个_navbar.md，文件内容如下：

* [EN](/)
* [中文](/zh-cn/)

方法二：也可以不使用上述方式，而是直接修改index.html文件，

<body>
        <!-- 顶部导航 -->
        <nav>
            <a href="#/">EN</a>
            <a href="#/zh-cn/">中文</a>
        </nav>
        <div id="app"></div>
        <script>
            window.$docsify = {
                name: '文档中心',
                repo: '',
                loadSidebar: true, //侧边栏
            }
        </script>
        <!-- Docsify v4 -->
        <script src="//cdn.jsdelivr.net/npm/docsify@4"></script>
</body>

实现效果

 

三、安装插件

1.引入emoji插件

如果在做中英文切换时，想使用中国国旗和英国国旗表示，怎么办呢？docsify为我们提供了表情插件，使用docsify的emoji插件来获取国家的国旗。

只需要在index.html配置文件中引入emoji插件就可以直接在markdown文件中直接使用了！

引入了：<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>

 

<script>
     window.$docsify = {
          name: '文档中心',
          repo: '',
          loadSidebar: true, //侧边栏
          loadNavbar: true, //顶部导航
     }
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/emoji.min.js"></script>

 

配置_navbar.md文件，修改内容如下

* [:us:, :uk:](/)
* [:cn:](/zh-cn/)

显示效果

 

 

1.PDF导出

https://blog.csdn.net/weixin_43031092/article/details/114419659

 

1.全文搜索

 https://baijiahao.baidu.com/s?id=1683928475208184783&wfr=spider&for=pc

 

搭建配置

https://www.e-learn.cn/topic/3930849

 

 

我们直接创建一个index.html文件。

有了docsify神器，从此爱上看文档

1.https://www.jianshu.com/p/4883e95aa903

2.https://baijiahao.baidu.com/s?id=1683928475208184783&wfr=spider&for=pc

3.https://juemuren4449.com/archives/docsify-deploy-and-configuration

4.https://www.e-learn.cn/topic/3930849

5.https://docsify.js.org/#/zh-cn/

6.https://www.e-learn.cn/topic/3930849

posted @ 2022-03-29 18:24  IT民工郑小江  阅读(1607)  评论(0)  编辑  收藏  举报