* Add homepage option, fixed #30 * Add custom basePath support, resolve #31
6.4 KiB
无需构建快速生成文档页
特性
- 无需构建,写完 markdown 直接发布
- 支持自定义主题
- 容易使用并且轻量 (~12kb gzipped)
快速上手
创建项目
新建一个空项目,接着创建一个 docs
目录并进入到 docs 目录下
mkdir my-project && cd my-project
mkdir docs && cd docs
创建入口文件
创建一个 404.html
文件,内容为
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<link rel="stylesheet" href="//unpkg.com/docsify/themes/vue.css">
</head>
<body>
<div id="app"></div>
</body>
<script src="//unpkg.com/docsify"></script>
</html>
新建 README.md
文件,作为主页面
# Title
## balabala
部署!
将项目 push
到 GitHub 仓库后到设置页面开启 GitHub Pages 功能,选择 docs/
选项
命令行工具
方便快速创建文档目录,会读取项目的 package.json
里的选项作为 docsify 的配置,支持本地预览。
安装
npm i docsify-cli -g
初始化文档
默认初始化在当前目录,推荐将文档放在 docs
目录下
docsify init docs
启动本地服务
启动一个 server 方便预览,打开 http://localhost:3000
docsify serve docs
更多选项参考 docsify-cli
主题
目前提供 vue.css 和 buble.css,直接修改 404.html
里的 cdn 地址即可
<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/lib/themes/vue.css">
<link rel="stylesheet" href="//unpkg.com/docsify/lib/themes/buble.css">
更多功能
多页面
README.md
作为主页面,如果需要其他页面,直接在文档目录下创建对应的 *.md
文件,例如创建一个 guide.md
那么对应的路由就是 /guide
。
导航
导航需要自己写在 404.html
文件里,效果参考本文档
<nav>
<a href="/docsify/">En</a>
<a href="/docsify/zh-cn">中文</a>
</nav>
CDN
配置参数
repo
参考本文档的右上角的 GitHub 图标,如果要开启的话,将 404.html
里的 script 改成
<script src="//unpkg.com/docsify" data-repo="your/repo"></script>
max-level
目录最大展开层级,默认值为 6
<script src="//unpkg.com/docsify" data-max-level="6"></script>
el
替换节点元素,默认为 #app
<script src="//unpkg.com/docsify" data-el="#app"></script>
sidebar-toggle
Sidebar 开关按钮
<script src="//unpkg.com/docsify" data-sidebar-toggle></script>
sidebar
设置后 TOC 功能将不可用,适合导航较多的文档,data-sidebar
传入全局变量名。
<script>
window.sidebar = [
{ slug: '/', title: 'Home' },
{
slug: '/pageA',
title: 'page A',
children: [
{ slug: '/pageA/childrenB', title: 'children B' }
]
},
{ slug: '/PageC', title: 'Page C' }
]
</script>
<script src="/lib/docsify.js" data-sidebar="sidebar"></script>
load-sidebar
读取侧边栏配置文件,如果配置,默认加载当前目录下的 _sidebar.md
。如果文件不存在,会显示 TOC 作为侧边栏内容。如果你有二级目录,也应该放置一份配置文件。
如果用 _
开头作为文件名,你应该在文档目录下添加 .nojekyll
,阻止 GitHub Pages 忽略下划线开头的文件。
<script src="/lib/docsify.js" data-load-sidebar></script>
你可以指定侧边栏文件名
<script src="/lib/docsify.js" data-load-sidebar="_sidebar.md"></script>
_sidebar.md
的内容可以是这样的
- [Home](/)
- [Installation](/installation)
- Essentials
- [Getting Started](/getting-started)
- [Dynamic Route Matching](/dynamic-matching)
- [Nested Routes](/nested-routes)
- [Programmatic Navigation](/navigation)
- [Named Routes](/named-routes)
- [Named Views](/named-views)
- [Redirect and Alias](/redirect-and-alias)
- [HTML5 History Mode](/history-mode)
load-navbar
读取导航配置文件,如果配置,默认加载当前目录下的 _navbar.md
。如果文件不存在,会显示 html 里定义的导航栏。
<script src="/lib/docsify.js" data-load-navbar></script>
你可以指定导航栏文件名
<script src="/lib/docsify.js" data-load-navbar="_navbar.md"></script>
_navbar.md
的内容可以是这样
- [en](/)
- [中文](/zh-cn)
当然也支持二级列表,将生成一个下拉列表
- [download](/download)
- language
- [en](/)
- [中文](/zh-cn)
router
开启 hash router 功能,此时可以创建 index.html
作为入口文件,同时多页面切换不会重新加载资源。资源路径会被替换成 /#/
的形式。
<script src="/lib/docsify.js" data-router></script>
auto2top
切换路由时自动跳转到页面顶部
<script src="/lib/docsify.js" data-auto2top></script>
homepage
默认情况下网站会将根目录下 README.md
作为首页渲染,但是有些时候我们想指定其他文件,甚至想直接将 repo 下的 README 作为首页。你可以这样做:
<script src="/lib/docsify.js" data-homepage="https://raw.githubusercontent.com/QingWei-Li/docsify/master/README.md"></script>
<!-- 或者将 Welcome.md 作为首页 -->
<script src="/lib/docsify.js" data-homepage="Welcome.md"></script>
basePath
指定加载文档的路径,如果你的 HTML 入口文件和文档是放在不同地方,你可以设置:
<script src="/lib/docsify.js" data-base-path="/base/"></script>
<!-- 甚至文档是在其他站点下 😄 -->
<script src="/lib/docsify.js" data-base-path="https://docsify.js.org/"></script>