如何使用Docsify编写好的文档
如何使用Docsify撰写高质量文档
文档对于一个成功的产品至关重要。没有文档，人们使用你的产品会更加困难，如果你正在运行一个开源项目，文档同样重要。
创建一个文档站点可能会具有挑战性，尤其是如果你对前端开发不熟悉。
我过去8年一直是一名前端开发者。在那段时间里，我使用过许多框架来构建文档，比如Next.js、nextra、content layer、Ghost CMS、lume（deno）、docusaurus和Mark doc。
但是，要使用其中的许多工具，你需要对JavaScript、Next.js和React有基本的了解。你可能会遇到一些挑战，比如：
- 缺乏JavaScript、React或其他必要工具的知识
- 文档版本管理
- 配置
- 部署
在本指南中，我将介绍一个功能强大的工具，它可以帮助你撰写文档，而不需要太多技术知识。
什么是Docsify？
为了帮助你解决这个问题，我推荐一个名为docsify的工具。Docsify是一个简单而轻量的文档生成器。你可以在不了解JavaScript或React的情况下开始使用它。
Docsify提供了零配置、没有静态HTML文件、多主题支持、内置插件API以及带有插件的全文搜索支持。它还可以部署在GitHub pages、GitLab Pages、Firebase Netlify、Vercel等多个平台上。
我创建了一个演示项目来展示如何使用它 – 在GitHub上可以找到源代码。你还可以查看演示网站。
如何设置和使用Docsify
你可以使用docsify-cli创建一个新项目。如果你尚未安装Node和NPM，请先安装它们。
npm install -g docsify-cli# 或者yarn add -g docsify-cli# 或者pnpm add -g docsify-cli命令输出如下：
❯ pnpm add -g docsify-cli
Packages: +198+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Progress: resolved 199, reused 114, downloaded 84, added 198, done.
pnpm/[email protected]/node_modules/docsify: Running postinstall script, done in 196ms
/home/rajdeepsingh/.local/share/pnpm/global/5:
+ docsify-cli 4.4.4
+ pnpm 8.7.0
Done in 13.9s使用docsify-cli init选项创建新项目。
➜ docsify init docs
初始化成功！请运行docsify serve ./docs你还可以指定--theme和--plugins。
➜ docsify init docs --theme buble --plugins你可以在文档页面上了解更多关于docsify-cli的信息。
接下来，使用docsify-cli启动本地开发服务器。运行以下命令：
docsify serve docs# 或者docsify serve .本地服务器运行在3000端口上。
当您在浏览器中打开网站时，应该如下所示：
Docsify 文件夹结构
Docsify 有一个简单直观的文件夹结构。默认情况下，当您使用 docsify-cli 创建一个新项目时，有三个主要文件：
├── index.html // 这是一个 HTML 入口文件。├── .nojekyll // 当您在 GitHub 页面上部署项目时很有帮助。└── README.md // 这是主页或 / 路由器如何自定义 Docsify
Docsify 提供了许多自定义选项，您不需要额外的知识来配置它 – 它非常直观，就像复制和粘贴代码一样。
在这个指南中，我们将探索一些最常见的自定义选项。要进行高级配置，可以查阅 Docsify 文档。
基本配置
在基本配置中，您可以更改或添加标志、名称、添加 GitHub 仓库链接、主题颜色等。
以下是完成这些操作的代码 – 您可以填入自己的详细信息。
<!-- index.html --> <script> window.$docsify = { logo: '/_media/icon.svg', <!-- 添加标志 --> name: "文档", <!-- 网站名称，显示在侧边栏中。 --> nameLink: '/', <!-- 名称的 URL --> repo: "officialrajdeepsingh/docsifyjs", <!--github 仓库--> maxLevel: 2, <!-- 最大目录层级 --> themeColor: '#3F51B5', <!-- 自定义主题颜色 --> };</script>加载屏幕
在典型的 JavaScript 和 React.js 生态系统中，启用加载屏幕或对话框通常非常棘手。
在 Docsify 中，您可以轻松地启用加载屏幕，不需要任何配置。您只需简单地在应用程序 ID 内书写一些文本和一个 HTML 元素，这将显示为加载屏幕。如下所示：
<!-- index.html --><div id="app">请稍候...</div><!-- 或 --><div id="app"><h1> 请稍候... </h1></div>侧边栏
默认情况下，侧边栏显示目录。但您可以非常轻松地自定义它。首先，您需要启用侧边栏。
<!-- index.html --><script> window.$docsify = { loadSidebar: true, <!-- 启用侧边栏 --> };</script>然后，在根目录下创建一个新的 _sidebar.md 文件，并粘贴以下代码：
- [首页](README.md)- [草稿文章](draft-article.md)- [指南](guide.md)- [第一](page-first.md)- [第二](page-second.md)- [第三](page-third.md)- [第四](page-four.md)您的侧边栏现在应该如下所示：
标题
默认情况下，您在Docsify网站上看不到导航栏：
但不用担心，您可以更改这个设置。要显示导航栏,您首先需要启用它，可以像这样进行设置：
<!-- index.html --> <script> window.$docsify = { loadNavbar: true, <!-- enable navbar --> }; </script> </body></html>然后，在根目录下创建一个新的_navbar.md文件，并将以下代码粘贴进去：
* 入门指南 * [快速入门](quickstart.md) * [编写更多页面](more-pages.md) * [自定义导航栏](custom-navbar.md) * [封面页面](cover.md)* 设置 * [配置指南](configuration.md) * [主题](themes.md) * [使用插件](plugins.md) * [Markdown配置](markdown.md) * [语言高亮](language-highlight.md)您的导航栏现在应该如下所示：
封面页面
首先，启用封面页面，使用以下代码：
<!-- index.html --><script> window.$docsify = { coverpage: true, <!-- enable coverpage --> };</script>下一步是创建一个新的_coverpage.md文件。
# 学习Docsify ### 学习从初学者开始的docsify.[开始学习]()[Github](#/README)您的网站封面页面应该如下所示：
封面页面和用户界面取决于主题，所以它们会根据不同的主题而有所不同。
插件
插件可以为Docsify提供额外的功能和特性，增强用户体验。
您可以根据自己的需求创建和使用插件。Docsify有许多开源插件可供使用，这些插件由各种贡献者创建。
您可以通过复制粘贴代码来使用任何插件。您甚至可以使用Docsify创建自己的插件。
如何使用第三方插件
在此示例中，我们将使用Docsify插件来启用搜索栏功能。
要启用搜索栏功能，请将以下脚本复制并粘贴到您的index.html文件中：
<script src="//cdn.jsdelivr.net/npm/docsify/lib/plugins/search.min.js"></script>现在，搜索栏将在您的站点上显示并工作。使用搜索插件，您还可以配置各种功能 – 了解更多关于它的信息，请访问搜索插件安装和配置页面。
如何使用docsify创建自己的插件
要在docsify中创建自己的插件，你需要使用内置的钩子来实现。
Docsify有六个内置的钩子：init、mounted、beforeEach、afterEach、doneEach和ready。
init：在docsify脚本初始化时调用一次。mounted：在docsify实例挂载到DOM上时调用一次。beforeEach：在每次页面加载之前，将新的markdown转换为HTML之前调用。afterEach：在每次页面加载后，markdown转换为HTML之后调用。doneEach：在每次页面加载之后，将新的HTML附加到DOM上之后调用。ready：在渲染初始页面后调用一次。
通过这些钩子，你可以创建一个插件。要了解有关创建自己插件的更多信息，请查看自定义插件文档页面。
在此示例中，我们将使用beforeEach插件钩子创建一个编辑按钮。它在每个页面上都显示”编辑文档”按钮。
<!-- index.html --> <script> window.$docsify = { plugins: [ <!-- 写自己的自定义插件 --> function editButton(hook, vm) { // 调用钩子 hook.beforeEach(function (html) { var url = "https://github.com/officialrajdeepsingh/docsifyjs/edit/master/" + vm.route.file; // 路径修复 let tempFile = url.replace("docsifyjs/README.md", "README.md",) ? url.replace("docsifyjs/README.md", "README.md") : url; // 添加编辑按钮 var editHtml = "[📝 编辑文档](" + url + ")\n"; // 在文件顶部添加编辑按钮 return editHtml + html + "\n----\n" + "最后修改 " + editHtml; }); }, ], }; </script>主题
Docsify有官方主题和社区制作的主题。你可以使用其中之一，而且切换主题时不需要编写额外的代码。
<!--vue主题 --><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css" /><!-- buble主题 --><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/buble.css" /><!-- dark主题 --><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/dark.css" /><!-- pure主题 --><link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/pure.css" />你可以选择压缩或不压缩主题CSS文件。压缩的CSS文件是主题的缩小版本，它是生产环境中的轻量级CSS文件。另一方面，非压缩的主题CSS文件对于开发很有帮助。
只需将CSS主题文件复制并粘贴到head元素内即可更改主题。
在非官方主题方面，我认为docsify-themeable主题是你的最佳选择。
部署
Docsify有多种部署选项。你可以使用GitHub Pages、GitLab Pages、Firebase Hosting、VPS（Nginx）、Netlify、Vercel、AWS Amplify和Docker来部署Docsify站点。
在一些平台上，比如GitHub pages，您可以在不编写任何配置的情况下，直接将docsify站点部署到GitHub存储库中。
下面是具体步骤：
您需要前往设置 > 页面 > 源代码 > 然后选择从分支部署 > 分支 > 选择包含文件夹的分支，并点击保存按钮。
这个过程可能需要一些时间，具体取决于您的网站大小。部署完成后，您应该会看到生成的URL。
结论
Docsify是一个用于生成文档站点的强大工具。在Docsify中，您可以专注于文档编写，而不是UI设计。
对于不太熟悉JavaScript的开发人员来说，Docsify是一个不错的选择。如果您更关注低级语言，比如C++或Rust，Docsify可以帮助您通过一条命令开始编写文档。
最近我在我的awesome-nextjs存储库中使用了Docsify。您可以轻松地在GitHub页面上部署，无需任何配置。
只需记住Docsify有两个缺点：
- Docsify不生成页面的动态SEO元标签，只生成标题和描述。
- Docsify主题没有现代化的UI风格。
但它仍然非常有用！尽情享受创建您的文档吧：）
Leave a Reply