推荐全局安装 docsify-cli 工具,可以方便地创建及在本地预览生成的文档。
npm i docsify-cli -g如果想在项目的 ./docs 目录里写文档,直接通过 init 初始化项目。
docsify init ./docs在 init 完成后,你可以看到 ./docs 子目录中的文件列表。
index.html入口文件README.md会做为主页内容渲染.nojekyll用于阻止 GitHub Pages 忽略掉下划线开头的文件
直接编辑 docs/README.md 就能更新文档内容,当然也可以添加更多页面。
使用 docsify serve 运行本地服务器。 你可以在 http://localhost:3000 上预览你的网站。
docsify serve docs[!TIP] 更多命令行工具用法,参考 docsify-cli 文档。
下载或使用以下代码创建一个 index.html 模板:
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">
<!-- Core Theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/core.min.css">
</head>
<body class="loading">
<div id="app"></div>
<!-- Configuration -->
<script>
window.$docsify = {
//...
};
</script>
<!-- Docsify.js -->
<script src="//cdn.jsdelivr.net/npm/docsify@5"></script>
<!-- Plugins (optional) -->
<!-- <script src="//cdn.jsdelivr.net/npm/docsify@5/dist/plugins/search.min.js"></script> -->
</body>
</html>[!TIP] 注意:在下面两个例子中,当 docsify 发布新的主要版本时,需要手动更新 docsify URL(例如,
v5.x.x=>v6.x.x)。 定期检查 docsify 网站,以查看新的主要版本是否已发布。
在 URL 中指定一个主要版本 (@5),可使你的网站自动接收非破坏性增强(即 "minor" 更新)和错误修复(即 "patch" 更新)。 这是加载 docsify 资源的推荐方式。
<!-- Core Theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5/dist/themes/core.min.css">
<!-- Docsify -->
<script src="//cdn.jsdelivr.net/npm/docsify@5"></script>如果您想确保绝对不会出现会破坏网站的更改(非主要更新可能会无意中引入破坏性更改,尽管它们的目的不是这样),请在 URL 中的 @ 符号后指定完整版本。 这是最安全的方法,可确保无论 docsify 的未来版本如何更改,你的网站都将以相同的方式显示和运行。
<!-- Core Theme -->
<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify@5.0.0/themes/core.min.css">
<!-- Docsify -->
<script src="//cdn.jsdelivr.net/npm/docsify@5.0.0"></script>JSDelivr 支持 npm-compatible semver ranges,因此也可以使用版本语法,例如 @^5.0.0 表示最新的 v5 版本,@5.0.x 表示最新的 v5.0 补丁版本(例如 你将收到 5.0.4,但不是 5.1.0),@5.x 表示最新的 v5 次版本和补丁版本(实际上与 @5 和 @^5.0.0 相同),等等。
如果你的系统上安装了 Python,你可以很容易地使用它来运行静态服务器来预览你的网站,而不是使用 docsify-cli 中的 docsify serve。
# Python 2
cd docs && python -m SimpleHTTPServer 3000# Python 3
cd docs && python -m http.server 3000