搭建一个轻量级的个人/团队文档平台-docsify

文档工具 2023-05-08 327次浏览

前言

网上关于文档的生成工具很多,像VuePress、GitBook 、Hexo这些都是一些非常优秀的文档生成工具,本文主要讲述Docsify搭建和使用。Docsify 是一个动态生成文档网站的工具,不同于 GitBook 的地方是它不会将 .md 转成 .html 文件,所有转换工作都是在运行时进行。

官方站点

https://docsify.js.org

搭建一个轻量级的个人团队文档平台-docsify

特性

  • 没有静态构建的 html 文件
  • 简单轻便
  • 智能全文搜索插件
  • 多个主题
  • 有用的插件 API
  • 表情符号支持
  • 兼容IE11
  • 支持服务端渲染

配置文件

  • index.html 网站入口文件
  • _sidebar.md 侧边栏目录文件,markdown语法编写
  • _navbar.md 导航目录文件,markdown语法编写
  • home.md 主面板默认页面,不配置则默认加载中

侧边栏配置

window.$docsify = {
    loadSidebar: true,
    alias: {
        '/.*/_sidebar.md': '/_sidebar.md', // See #301
    },
}

<script src="./docsify/docsify.js"></script>

创建:_sidebar.md

<!-- docs/_sidebar.md -->

* [Home](/)
* [Guide](guide.md)

文档化仅在当前文件夹中搜索,并使用该文件夹,否则会回回使用配置配置的文件夹。

_sidebar.mdwindow.$docsify.loadSidebar

文件结构

└── docs/
    ├── _sidebar.md
    ├── _navbar.md
    ├── index.html
    ├── home.md
    ├── _coverpage.md

边栏设置页面标题

页面的标记从选定的边栏项名称生成。为了更好的 SEO,可以通过在文件名后指定字符串来自定义标题

<!-- docs/_sidebar.md -->
* [Home](/)
* [Guide](guide.md "The greatest guide in the world")

自定义导航栏

如果需要自定义导航,可以创建一个基于 HTML 的导航栏。文档链接以 开始。#/

<!-- index.html -->

<body>
  <nav>
    <a href="#/">EN</a>
    <a href="#/zh-cn/">中文</a>
  </nav>
  <div id="app"></div>
</body>

侧边栏多级配置

可以通过缩进属于特定父项下的项来创建子列表

<!-- _sidebar.md -->

* Getting started

  * [Quick start](quickstart.md)
  * [Writing more pages](more-pages.md)
  * [Custom navbar](custom-navbar.md)
  * [Cover page](cover.md)

* Configuration
  * [Configuration](configuration.md)
  * [Themes](themes.md)

封面

设置为true,并创建 : _coverpage.md

<!-- index.html -->

<script>
  window.$docsify = {
    coverpage: true
  }
</script>
<!-- _coverpage.md -->

![logo](../images/ngxcode.svg)

# 编程驿站

> 编程驿站内部文档,项目使用docsify开源搭建

[开始](#docsify)

右上角角标GITHUB配置

window.$docsify = {
    repo: 'docs/',
    // or
    repo: 'https://www.ngxcode.com/docs',
};

隐藏侧边栏

此选项将完全隐藏侧边栏,不会呈现侧面的任何内容。

window.$docsify = {
  hideSidebar: true,
};

网页

默认情况下,home.md 将被视为网站的主页,但也可以通过配置设定主页

window.$docsify = {
    // Change to /home.md
    homepage: 'home.md',

    // Or use the readme in your repo
    homepage: 'https://www.ngxcode.com/docs.md',
};

主题颜色

自定义主题颜色

window.$docsify = {
    themeColor: '#3F51B5',
};

执行脚本

在页面上执行脚本。默认情况下会打开

window.$docsify = {
  executeScript: true,
};
## This is test

<script>
    console.log(2333)
</script>

notfoundpage

加载文件:_404.md

window.$docsify = {
    notFoundPage: true,
};

加载 404 页的自定义路径:

window.$docsify = {
    notFoundPage: 'my404.md',
};

根据本地化加载正确的 404 页

window.$docsify = {
    notFoundPage: {
        '/': '_404.md',
        '/de': 'de/_404.md',
    },
};

全文搜索

默认情况下,将识别当前页面上的超链接,并将内容保存在 中。您还可以指定文件的路径。localStorage

<script>
    window.$docsify = {
        search: {
            maxAge: 86400000, // Expiration time, the default one day
            paths: 'auto', // or 'auto'
            placeholder: 'Type to search',

            // Localization
            placeholder: {
                '/zh-cn/': '搜索',
                '/': 'Type to search'
            },

            noData: 'No Results!',

            // Localization
            noData: {
                '/zh-cn/': '找不到结果',
                '/': 'No Results'
            },
        }
    }
</script>
<script src="../docsify/search.js"></script>

嵌入文件

您可以将这些文件嵌入为视频、音频、iframe 或代码块,甚至标记文件甚至可以直接嵌入到文档中。

例如,下面是一个嵌入的标记文件。您只需这样做:

[filename](_media/example.md ':include')

然后,的内容将直接显示在这里;example.md

嵌入式文件类型

目前,文件扩展名会自动识别并以不同的方式嵌入

支持以下类型:

  • iframe ,.html.htm
  • 记价 ,.markdown.md
  • 音频 .mp3
  • 视频,.mp4.ogg
  • 代码其他文件扩展名

当然,您可以强制指定类型。例如,可以通过设置 来嵌入标记文件作为代码块。:type=code

[filename](_media/example.md ':include :type=code')

搭建一个轻量级的个人团队文档平台-docsify

喜欢 (0)
发表我的评论
取消评论
表情 贴图 加粗 删除线 居中 斜体 签到

Hi,您需要填写昵称和邮箱!

  • 昵称 (必填)
  • 邮箱 (必填)
  • 网址