配置项

docsify 有两种配置参数的方式。一种是配置在 window.$docsify 里,另一种是给 script 标签添加 data-* 属性。

  1. <!-- 方法 1 -->
  2. <script>
  3. window.$docsify = {
  4. repo: 'QingWei-Li/docsify',
  5. maxLevel: 3,
  6. coverpage: true
  7. }
  8. </script>
  9. <!-- 方法 2 -->
  10. <script
  11. src="//unpkg.com/docsify"
  12. data-repo="QingWei-Li/docsify"
  13. data-max-level="3"
  14. data-coverpage>
  15. </script>

两种方式可以共存,推荐第一种做法——直接配置 window.$docsify 对象——这会让你的配置更加清晰,同时也可以方便的将配置单独写到另一个文件里。

!> 通过 window.$docsify 配置属性,需要将属性改成驼峰命名法。通过 data-* 属性配置,保持短横线的命名规则。

el

  • 类型:String
  • 默认值:#app

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

  1. window.$docsify = {
  2. el: '#app'
  3. }

repo

  • 类型:String
  • 默认值: null

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

  1. window.$docsify = {
  2. repo: 'QingWei-Li/docsify',
  3. // or
  4. repo: 'https://github.com/QingWei-Li/docsify/'
  5. }

max-level

  • 类型:Number
  • 默认值: 6

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

  1. window.$docsify = {
  2. maxLevel: 4
  3. }

load-navbar

  • 类型:Boolean|String
  • 默认值: false

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

  1. window.$docsify = {
  2. // 加载 _navbar.md
  3. loadNavbar: true,
  4. // 加载 nav.md
  5. loadNavbar: 'nav.md'
  6. }

load-sidebar

  • 类型:Boolean|String
  • 默认值: false

加载自定义侧边栏,参考多页文档。设置为 true 后会加载 _sidebar.md 文件,也可以自定义加载的文件名。

  1. window.$docsify = {
  2. // 加载 _sidebar.md
  3. loadSidebar: true,
  4. // 加载 summary.md
  5. loadSidebar: 'summary.md'
  6. }

sub-max-level

  • 类型:Number
  • 默认值: 0

自定义侧边栏后默认不会再生成目录,你也可以通过设置生成目录的最大层级开启这个功能。

  1. window.$docsify = {
  2. subMaxLevel: 2
  3. }

auto2top

  • 类型:Boolean
  • 默认值: false

切换页面后是否自动跳转到页面顶部。

  1. window.$docsify = {
  2. auto2top: true
  3. }

homepage

  • 类型:String
  • 默认值: README.md

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

  1. window.$docsify = {
  2. // 入口文件改为 /home.md
  3. homepage: 'home.md',
  4. // 文档和仓库根目录下的 README.md 内容一致
  5. homepage: 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/README.md'
  6. }

base-path

  • 类型:String

文档加载的根路径,可以是二级路径或者是其他域名的路径。

  1. window.$docsify = {
  2. basePath: '/path/',
  3. // 直接渲染其他域名的文档
  4. basePath: 'https://docsify.js.org/',
  5. // 甚至直接渲染其他仓库 readme
  6. basePath: 'https://raw.githubusercontent.com/ryanmcdermott/clean-code-javascript/master/'
  7. }

coverpage

  • 类型:Boolean|String
  • 默认值: false

启用封面页。开启后是加载 _coverpage.md 文件,也可以自定义文件名。

  1. window.$docsify = {
  2. coverpage: true,
  3. // 自定义文件名
  4. coverpage: 'cover.md'
  5. }

name

  • 类型:String

文档标题,会显示在侧边栏顶部。

  1. window.$docsify = {
  2. name: 'docsify'
  3. }
  • 类型:String
  • 默认值:window.location.pathname

点击文档标题后跳转的链接地址。

  1. window.$docsify = {
  2. nameLink: '/',
  3. // 按照路由切换
  4. nameLink: {
  5. '/zh-cn/': '/zh-cn/',
  6. '/': '/'
  7. }
  8. }

markdown

  • 类型: Object|Function

参考 Markdown 配置

  1. window.$docsify = {
  2. // object
  3. markdown: {
  4. smartypants: true,
  5. renderer: {
  6. link: function() {
  7. // ...
  8. }
  9. }
  10. },
  11. // function
  12. markdown: function (marked, renderer) {
  13. // ...
  14. return marked
  15. }
  16. }

theme-color

  • 类型:String

替换主题色。利用 CSS3 支持变量的特性,对于老的浏览器有 polyfill 处理。

  1. window.$docsify = {
  2. themeColor: '#3F51B5'
  3. }

alias

  • 类型:Object

定义路由别名,可以更自由的定义路由规则。 支持正则。

  1. window.$docsify = {
  2. alias: {
  3. '/foo/(+*)': '/bar/$1', // supports regexp
  4. '/zh-cn/changelog': '/changelog',
  5. '/changelog': 'https://raw.githubusercontent.com/QingWei-Li/docsify/master/CHANGELOG',
  6. '/.*/_sidebar.md': '/_sidebar.md' // See #301
  7. }
  8. }

auto-header

  • 类型:Boolean

同时设置 loadSidebarautoHeader 后,可以根据 _sidebar.md 的内容自动为每个页面增加标题。#78

  1. window.$docsify = {
  2. loadSidebar: true,
  3. autoHeader: true
  4. }

execute-script

  • 类型:Boolean

执行文档里的 script 标签里的脚本,只执行第一个 script (demo)。 如果 Vue 存在,则自动开启。

  1. window.$docsify = {
  2. executeScript: true
  3. }
  1. ## This is test
  2. <script>
  3. console.log(2333)
  4. </script>

注意如果执行的是一个外链脚本,比如 jsfiddle 的内嵌 demo,请确保引入 external-script 插件。

no-emoji

禁用 emoji 解析。

  1. window.$docsify = {
  2. noEmoji: true
  3. }

merge-navbar

小屏设备下合并导航栏到侧边栏。

  1. window.$docsify = {
  2. mergeNavbar: true
  3. }

format-updated

我们可以显示文档更新日期通过 {docsify-updated} 变量. 并且格式化日期通过 formatUpdated
参考 https://github.com/lukeed/tinydate#patterns

  1. window.$docsify = {
  2. formatUpdated: '{MM}/{DD} {HH}:{mm}',
  3. formatUpdated: function (time) {
  4. // ...
  5. return time
  6. }
  7. }

当前默认为 _blank, 配置一下就可以:

  1. window.$docsify = {
  2. externalLinkTarget: '_self' // default: '_blank'
  3. }
  • 类型: Array

有时我们不希望 docsify 处理我们的链接。 参考 #203

  1. window.$docsify = {
  2. noCompileLinks: [
  3. '/foo',
  4. '/bar/.*'
  5. ]
  6. }