怎么使用Docsify和GitHub Pages创建一个文档网站

技术怎么使用Docsify和GitHub Pages创建一个文档网站这篇文章主要介绍怎么使用Docsify和GitHub Pages创建一个文档网站,文中介绍的非常详细,具有一定的参考价值,感兴趣的小伙伴们一定要看完!使

本文主要介绍如何使用Docsify和GitHub Pages创建文档网站,非常详细,有一定的参考价值。感兴趣的朋友一定要看!

使用Docsify创建一个文档网页,并将其发布到GitHub Pages。

文档是帮助用户使用开源项目的一个重要部分,但它并不总是开发人员的首要任务,因为他们可能更关心让他们的应用程序变得更好,而不是帮助人们使用它们。对于开发人员来说,这就是为什么让发布文档变得更容易如此有价值的原因。在本教程中,我将向您展示一种方法:将Docsify文档生成器与GitHub Pages相结合。

默认情况下,GitHub Pages会提示用户使用Jekyll,这是一个静态网站生成器,支持HTML、CSS和其他网络技术。Jekyll可以从以markdown格式编码的文档文件中生成一个静态网站,GitHub会自动识别它们的。医学博士或。减价分机。虽然这个设定很好,但是我想尝试一下别的。

幸运的是,GitHub Pages支持HTML文件,这意味着您可以使用其他网站生成工具(如Docsify)在这个平台上创建网站。Docsify是一个拥有MIT许可的开源项目,它的功能是让你在GitHub Pages上轻松创建一个吸引人的高级文档网站。

怎么使用Docsify和GitHub  Pages创建一个文档网站

文档

00-1010安装Docsify有两种方法:

鸿蒙系统正式战略合作,打造——HarmonyOS技术社区。

通过NPM安装文档的命令行界面。

手动编写自己的index.html。

Docsify推荐NPM,但我会用第二个方案。如果您想使用NPM,请遵循快速入门指南中的说明。

00-1010我已经在这个项目的GitHub页面上发布了这个例子的源代码。您可以单独下载这些文件,也可以通过以下方式克隆存储库。

然后,gitclonehttps://github.com/bryantson/OpensourceDotComDemos光盘进入DocsifyDemo目录。

我将在下面向您介绍这些代码,它们被克隆到我的示例存储库中,以便您了解如何修改Docsify。如果您愿意,也可以从头开始创建一个新的index.html文件,就像Docsify文档中的示例一样:

!index.html!doctypehtmlhtmlhealthettp-equiv=' X-UA-Compatible ' content=' IE=edge,chrome=1 ' meta name=' viewport ' content=' width=device-width,initial-scale=1 ' metaharset=' UTF-8 ' linkrel='样式表' href='//cdn . jsdelivervr . net/NPM/docsify/themes/vue . CSS '/headsdydivided='

app"></div>  <script>    window.$docsify = {      //...    }  </script>  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script></body></html>

探索 Docsify 如何工作

如果你克隆了我的 GitHub 存储库,并切换到 DocsifyDemo 目录下,你应该看到这样的文件结构:

怎么使用Docsify和GitHub Pages创建一个文档网站

File contents in the cloned GitHub

文件/文件夹名称 内容
index.html 主要的 Docsify 初始化文件,也是最重要的文件
_sidebar.md 生成导航
README.md 你的文档根目录下的默认 Markdown 文件
images 包含了 README.md 中的示例 .jpg 图片
其它目录和文件 包含可导航的 Markdown 文件

index.html 是 Docsify 可以工作的唯一要求。打开该文件,你可以查看其内容:

<!-- index.html --> <!DOCTYPE html><html><head>  <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">  <meta name="viewport" content="width=device-width,initial-scale=1">  <meta charset="UTF-8">  <link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">  <title>Docsify Demo</title></head><body>  <div id="app"></div>  <script>    window.$docsify = {      el: "#app",      repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo',      loadSidebar: true,    }  </script>  <script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script></body></html>

这本质上只是一个普通的 HTML 文件,但看看这两行:

<link rel="stylesheet" href="//cdn.jsdelivr.net/npm/docsify/themes/vue.css">... 一些其它内容 ...<script src="//cdn.jsdelivr.net/npm/docsify/lib/docsify.min.js"></script>

这些行使用内容交付网络(CDN)的 URL 来提供 CSS 和 JavaScript 脚本,以将网站转化为 Docsify 网站。只要你包含这些行,你就可以把你的普通 GitHub 页面变成 Docsify 页面。

<body> 标签后的第一行指定了要渲染的内容:

<div id="app"></div>

Docsify 使用单页应用(SPA)的方式来渲染请求的页面,而不是刷新一个全新的页面。

最后,看看 <script> 块里面的行:

<script>    window.$docsify = {      el: "#app",      repo: 'https://github.com/bryantson/OpensourceDotComDemos/tree/master/DocsifyDemo',      loadSidebar: true,    }</script>

在这个块中:

  • el 属性基本上是说:“嘿,这就是我要找的 id,所以找到它并在那里呈现。”

  • 改变 repo 值,以确定当用户点击右上角的 GitHub 图标时,会被重定向到哪个页面。 

  • 怎么使用Docsify和GitHub Pages创建一个文档网站

  • 将 loadSideBar 设置为 true 将使 Docsify 查找包含导航链接的 _sidebar.md 文件。

你可以在 Docsify 文档的配置部分找到所有选项。

接下来,看看 _sidebar.md 文件。因为你在 index.html 中设置了 loadSidebar 属性值为 true,所以 Docsify 会查找 _sidebar.md 文件,并根据其内容生成导航文件。示例存储库中的 _sidebar.md 内容是:

<!-- docs/_sidebar.md -->  * [HOME](./) * [Tutorials](./tutorials/index)  * [Tomcat](./tutorials/tomcat/index)  * [Cloud](./tutorials/cloud/index)  * [Java](./tutorials/java/index) * [About](./about/index) * [Contact](./contact/index)

这会使用 Markdown 的链接格式来创建导航。请注意 “Tomcat”、“Cloud” 和 “Java” 等链接是缩进的;这意味着它们被渲染为父链接下的子链接。

像 README.md 和 images 这样的文件与存储库的结构有关,但所有其它 Markdown 文件都与你的 Docsify 网页有关。

根据你的需求,随意修改你下载的文件。下一步,你将把这些文件添加到你的 GitHub 存储库中,启用 GitHub Pages,并完成项目。

启用 GitHub 页面

创建一个示例的 GitHub 存储库,然后使用以下 GitHub 命令检出、提交和推送你的代码:

$ git clone 你的 GitHub 存储库位置$ cd 你的 GitHub 存储库位置$ git add .$ git commit -m "My first Docsify!"$ git push

设置你的 GitHub Pages 页面。在你的新 GitHub 存储库中,点击 “Settings”:

怎么使用Docsify和GitHub Pages创建一个文档网站

Settings link in GitHub

向下滚动直到看到 “GitHub Pages”:

怎么使用Docsify和GitHub Pages创建一个文档网站

GitHub Pages settings

查找 “Source” 部分:

怎么使用Docsify和GitHub Pages创建一个文档网站

GitHub Pages settings

点击 “Source” 下的下拉菜单。通常,你会将其设置为 “master branch”,但如果你愿意,也可以使用其他分支:

怎么使用Docsify和GitHub Pages创建一个文档网站

Setting Source to master branch

就是这样!你现在应该有一个链接到你的 GitHub Pages 的页面了。点击该链接将带你到那里,然后用 Docsify 渲染:

怎么使用Docsify和GitHub Pages创建一个文档网站

Link to GitHub Pages docs site

它应该像这样:

怎么使用Docsify和GitHub Pages创建一个文档网站

以上是“怎么使用Docsify和GitHub Pages创建一个文档网站”这篇文章的所有内容,感谢各位的阅读!希望分享的内容对大家有帮助,更多相关知识,欢迎关注行业资讯频道!

内容来源网络,如有侵权,联系删除,本文地址:https://www.230890.com/zhan/50272.html

(0)

相关推荐

  • VC++ win7下怎么实现WIFI共享工具

    技术VC++ win7下怎么实现WIFI共享工具这篇文章主要讲解了“ VC++ win7下怎么实现WIFI共享工具”,文中的讲解内容简单清晰,易于学习与理解,下面请大家跟着小编的思路慢慢深入,一起来研究和学习“ VC++

    攻略 2021年11月30日
  • angular双向绑定实现(angular 双向绑定数据校验)

    技术angular怎么实现双向数据绑定本篇内容介绍了“angular怎么实现双向数据绑定”的有关知识,在实际案例的操作过程中,不少人都会遇到这样的困境,接下来就让小编带领大家学习一下如何处理这些情况吧!希望大家仔细阅读,

    攻略 2021年12月21日
  • 如何使用GraphPad绘制箱线图

    技术如何使用GraphPad绘制箱线图本篇文章为大家展示了如何使用GraphPad绘制箱线图,内容简明扼要并且容易理解,绝对能使你眼前一亮,通过这篇文章的详细介绍希望你能有所收获。 首先是GraphPad软件的安装 i

    攻略 2021年10月28日
  • 如何理解php中echo

    技术如何理解php中echo这篇文章主要介绍“如何理解php中echo”,在日常操作中,相信很多人在如何理解php中echo问题上存在疑惑,小编查阅了各式资料,整理出简单好用的操作方法,希望对大家解答”如何理解php中e

    攻略 2021年10月22日
  • myeclipse+git push报错是怎么回事

    技术myeclipse+git push报错是怎么回事这篇文章给大家分享的是有关myeclipse+git push报错是怎么回事的内容。小编觉得挺实用的,因此分享给大家做个参考,一起跟随小编过来看看吧。原因:本地和远程

    攻略 2021年11月27日
  • 哈利波特魂器是哪七个,哈利波特中的魂器有哪七个

    技术哈利波特魂器是哪七个,哈利波特中的魂器有哪七个哈利波特中的魂器有哪七个哈利波特魂器是哪七个?這??是自造詞Horcrux   Horcrux是罗琳女士生造出来的单词。有很多分析词源的观点认为,这个单词应该被拆成hor

    生活 2021年10月22日