搜索
首页web前端html教程利用 Gitbook 生成文档中心站点_html/css_WEB-ITnose

利用 Gitbook 生成文档中心站点

经过一个多月,Bugtags 最近上线了自己的文档站点(docs.bugtags.com),在这里你可以找到 Bugtags 集成、使用相关的绝大部分问题。

在这之前我们使用的是第三方提供的帮助中心产品服务,在他们网站后台上面编辑文档内容,建立自己的文档体系的;但是用久了发现还是用很多不爽的地方,起码是不符合我们的习惯;

比如:该产品文档是使用富文本形式编辑和存储在数据库的;而我们自己都非常喜欢于用 Markdown 格式编写文档;而数据库保存也注定无法使用 git 来进行文档的版本管理和控制; 帮助中心页面的样式只有默认的几套,尽管提供了模板设计功能,但其实也非常鸡肋,完全无法满足我们的自定制需求。基于此我们尝试寻找其他的方案解决这个问题。

我们的需求

我们首先想明白我们需要什么样的文档管理系统;

1、 使用 Markdown 来撰写文档,所谓「无 Markdown,不文档」;我们工程师都习惯于使用 Markdown 来撰写文档,甚至我司唯一不会技术的美女静静都表示:「文档怎么可以不是 Markdown 的呢!」就刚刚催稿时她还说:「必须是 Markdown 啊,不然我不收的」。

2、 生成的网站纯静态,这样才会速度快。在起初我们也想过两种方案,一是把 Markdown 文件下载到前端,在前端渲染成 HTML;另一种方案是在后端把所有 Markdown 生成 HTML,前端浏览时直接加载 HTML。经过考虑,还是得采取后一种。如果前一种,让每一个终端用户都要耗费资源来渲染 Markdown,实在浪费;而且速度无法保障。而后一种思路就很清晰了:首先写Markdown文档,文档写完后全部生成静态网站,这样终端用户访问的全部都是静态的 HTML 页面了。

3、 git 管理。这个应该无需多言了吧。文档的更新升级,必须要有一个强大的版本管理系统,这个非 git 莫属了。

在一系列尝试之后,我们开始采用 Gitbook 并对他进行改写,来生成起自己的文档中心站点。

Gitbook 简介

Gitbook 是一个电子书制作程序;它把组织起来的 Markdown 文件按照层次生成电子书;这个电子书的格式可以是 epub 、 mobi 、 pdf ,甚至还可以是一个网站;

它的使用也是非常简单,基本上只有两步:

  1. 使用 gitbook init 命令,会根据文件 SUMMARY.md 中的内容来生成书籍目录结构;

  2. 使用 gitbook build 把书籍生成你需要的格式。

然后所有的书籍配置都可以通过根目录下的 book.json 文件来定义。 关于 Gitbook 较详细的使用方法,可以参考 Gitbook 简明教程 ,这个网站本身也是由 Gitbook 来生成的。

采用 Gitbook 的原因

Gitbook 与我们的需要匹配较强,有以下几点:

  1. 开源。作为一个初创小企业,我们的很多项目受益于开源产品。有很多第三方的插件来推动这个产品发展;

  2. Markdown 格式撰写文档;

  3. 目录结构清晰;我们可以把所有的 Markdown 文档按照不同的主题归集到不同的目录层次下;

  4. 生成的网页纯静态。Gitbook 是可以把所有的 Markdown 文档生成静态的 HTML 页面;

  5. 由于所有的内容都是 Markdown 文件,所以就可以使用 git 来进行版本管理和控制了;

  6. 在服务器上安装 Gitbook 后,定制一个 git hook 脚本,就可以在每次文档更新提交后自动生成网站;

Gitbook 不适应我们需求的地方

Gitbook 本身的理念是把 Markdown 文件组织成一本书的概念;这与我们需要做的一个网站还是有些不太一样的;所以会有很多需要改变的地方。

你看我们的网站跟任意一个 Gitbook 默认生成的站点对比,比如 Gitbook 官方的帮助文档站点 ,会发现很多不一样;具体来说,我们修改下面这些东西:

  • 目录生成逻辑;
  • 插件使用;
  • 搜索;
  • 模板样式。

目录生成逻辑

我们在Gitbook 的模板中添加了页头、页脚。页面目录的样式也不一样:这个可不只是展现形式不一样了。细心翻阅会发现,在我们的文档网站中,有一些文档并没有出现在目录里。比如有很多繁琐的常见问题;如果每一篇都要放到目录里,目录会变得很冗长。这些就得改变 Gitbook 默认的目录菜单的生成逻辑了。

我们是这么做的:在 SUMMARY.md 文件(这个文件中的内容来定义目录结构)中专门定义一个层次,这个层次名称叫做 hide-docs ,类似于这个样子:

- [hide-docs]() - [集成 iOS SDK 看不到悬浮球?](faq/ios/icon-not-found.md) - [用 CocoaPods 集成无法获取最新版的 SDK?](faq/ios/cocoapods-sdk-update.md) - [手动集成 SDK 添加 -ObjC 导致编译出错?](faq/ios/integrate-manual-build-error.md) - [集成 SDK 后,编译产生了很多警告?](faq/ios/integrate-build-warning.md)

这个层级下的所有文档都是不需要出现在目录下的!然而,Gitbook 照样会读取这个层次下的文档,所以我们要在生成目录的逻辑中,稍微改写:判断如果是 hide-docs 这个层级下的文档,就不生成目录。 这个就得改写 Gitbook 程序中的 website.js 文件中的 _writeTemplate 方法,我们的代码是这样:

if( !this.replacedSummary){ this.replacedSummary = {chapters:[]}; if( that.book.summary && that.book.summary.chapters && that.book.summary.chapters.length ){ var chapters = that.book.summary.chapters; for(var i =0; i < chapters.length;i++){ var cur = chapters[i]; if(/hide-docs/.test(cur.title)){ continue; } this.replacedSummary.chapters.push(cur); } } }

然后将该方法返回对象的 summary 属性指定为我们筛选过的 replacedSummary 变量。这样再运行 gitbook build ,就会发现所有的 Markdown 都被生成了 HTML,然而生成的 HTML 页面中的目录不包含这些我们需要隐藏的文档。

插件禁用

Gitbook 默认启用了搜索,字体调整等 5 个插件,但是我们是不需要这些;所以需要通过在 book.json 中指定 plugins 属性为如下:

{ "plugins":["-sharing","-livereload","-search","-fontsettings"] }

用减号表示不启用这些插件(这种配置方法官方帮助文档居然没提)。

搜索

接下来重点的部分就是搜索了,因为 Gitbook 官方的搜索根本不支持中文搜索,所以我们禁用了它,尽管有开源的支持中文的搜索插件,但是搜索结果的展示都是非常不直观;这些都需要从模板以及搜索引擎两方面来改进。

文档搜索我们最后采用的是强大 elasticsearch 来提供全文搜索服务,并且配合修改模板来显示搜索结果。关于 elasticsearch,这是个更复杂的话题了;这里不单说,有兴趣的朋友可以搜索相关教程。

模板

由于 Gitbook 是把 Markdown 组织成一本书的概念;对一本书来说,除了封面就是目录以及目录组织起来的正文。

而我们需要的是一个文档网站,不仅需要文档内容页面,还需要其他的页面, 比如首页,搜索页面, 404 页面,可能还需要其他的页面。这时候我不禁非常怀念 jekyll 这个静态博客生成工具,它会把根目录所有的 HTML 文件找到其对应模板嵌套生成 HTML 页面。

然而 jekyll (以及我另外尝试过的 hexo )的缺陷是组织 Markdown 文档的方式都比较扁平;是通过在每一个 Markdown 文档的首部定义目录、标签来定义其逻辑层次,而其生成的物理层次则是通过文件名中的日期来定义的。这是个最大缺陷。

目前我是用了比较野蛮的方式来解决这个问题:

  • 首页 :Gitbook 支持多语言,并且如果定义了多语言会有一个模板页面来生成一个首页,来选择语言入口;所以我就把这个本应作为语言选择入口的页面当成我们的首页;恩,就是你现在进去看到的那个页面。
  • 404 页面 :自己写了一个 404,在每次重新生成网站的时候单独把这个文件拷到根目录下;感觉很傻呢……
  • 搜索页面 :每一个内容页都可以是搜索页;因为我是把搜索结果显示在当前页面的内容区域;这样就可以局部刷新来展示页面结果;而不需要单独做一个模板页面了。

成果

最后,我们采用了 Gitbook 符合我们需求的部分,把不适应的上面几点想方设法解决了之后,就形成了我们现在的文档中心站点。

平时发布也是非常方便;直接编写 Markdown 文件,写完提交到服务器。在服务器端设置了 git hook 钩子,每次有文档更新时,都会自动重新生成静态网站,重新生成搜索索引。你有什么关于 Bugtags 使用方面的问题,都可以先去这里查阅一下,欢迎访问哦。

声明
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn
公众号网页更新缓存难题:如何避免版本更新后旧缓存影响用户体验?公众号网页更新缓存难题:如何避免版本更新后旧缓存影响用户体验?Mar 04, 2025 pm 12:32 PM

公众号网页更新缓存,这玩意儿,说简单也简单,说复杂也够你喝一壶的。你辛辛苦苦更新了公众号文章,结果用户打开还是老版本,这滋味,谁受得了?这篇文章,咱就来扒一扒这背后的弯弯绕绕,以及如何优雅地解决这个问题。读完之后,你就能轻松应对各种缓存难题,让你的用户始终体验到最新鲜的内容。先说点基础的。网页缓存,说白了就是浏览器或者服务器为了提高访问速度,把一些静态资源(比如图片、CSS、JS)或者页面内容存储起来。下次访问时,直接从缓存里取,不用再重新下载,速度自然快。但这玩意儿,也是个双刃剑。新版本上线,

如何使用HTML5表单验证属性来验证用户输入?如何使用HTML5表单验证属性来验证用户输入?Mar 17, 2025 pm 12:27 PM

本文讨论了使用HTML5表单验证属性,例如必需的,图案,最小,最大和长度限制,以直接在浏览器中验证用户输入。

HTML5中跨浏览器兼容性的最佳实践是什么?HTML5中跨浏览器兼容性的最佳实践是什么?Mar 17, 2025 pm 12:20 PM

文章讨论了确保HTML5跨浏览器兼容性的最佳实践,重点是特征检测,进行性增强和测试方法。

如何高效地在网页中为PNG图片添加描边效果?如何高效地在网页中为PNG图片添加描边效果?Mar 04, 2025 pm 02:39 PM

本文展示了使用CSS为网页中添加有效的PNG边框。 它认为,与JavaScript或库相比,CSS提供了出色的性能,详细介绍了如何调整边界宽度,样式和颜色以获得微妙或突出的效果

&lt; datalist&gt;的目的是什么。 元素?&lt; datalist&gt;的目的是什么。 元素?Mar 21, 2025 pm 12:33 PM

本文讨论了html&lt; datalist&gt;元素,通过提供自动完整建议,改善用户体验并减少错误来增强表格。Character计数:159

&lt; meter&gt;的目的是什么。 元素?&lt; meter&gt;的目的是什么。 元素?Mar 21, 2025 pm 12:35 PM

本文讨论了HTML&lt; meter&gt;元素,用于在一个范围内显示标量或分数值及其在Web开发中的常见应用。它区分了&lt; meter&gt;从&lt; progress&gt;和前

我如何使用html5&lt; time&gt; 元素以语义表示日期和时间?我如何使用html5&lt; time&gt; 元素以语义表示日期和时间?Mar 12, 2025 pm 04:05 PM

本文解释了HTML5&lt; time&gt;语义日期/时间表示的元素。 它强调了DateTime属性对机器可读性(ISO 8601格式)的重要性,并在人类可读文本旁边,增强Accessibilit

&gt; gt;的目的是什么 元素?&gt; gt;的目的是什么 元素?Mar 21, 2025 pm 12:34 PM

本文讨论了HTML&lt; Progress&gt;元素,其目的,样式和与&lt; meter&gt;元素。主要重点是使用&lt; progress&gt;为了完成任务和LT;仪表&gt;对于stati

See all articles

热AI工具

Undresser.AI Undress

Undresser.AI Undress

人工智能驱动的应用程序,用于创建逼真的裸体照片

AI Clothes Remover

AI Clothes Remover

用于从照片中去除衣服的在线人工智能工具。

Undress AI Tool

Undress AI Tool

免费脱衣服图片

Clothoff.io

Clothoff.io

AI脱衣机

AI Hentai Generator

AI Hentai Generator

免费生成ai无尽的。

热门文章

R.E.P.O.能量晶体解释及其做什么(黄色晶体)
2 周前By尊渡假赌尊渡假赌尊渡假赌
仓库:如何复兴队友
1 个月前By尊渡假赌尊渡假赌尊渡假赌
Hello Kitty Island冒险:如何获得巨型种子
4 周前By尊渡假赌尊渡假赌尊渡假赌

热工具

禅工作室 13.0.1

禅工作室 13.0.1

功能强大的PHP集成开发环境

Atom编辑器mac版下载

Atom编辑器mac版下载

最流行的的开源编辑器

ZendStudio 13.5.1 Mac

ZendStudio 13.5.1 Mac

功能强大的PHP集成开发环境

SublimeText3 Mac版

SublimeText3 Mac版

神级代码编辑软件(SublimeText3)

Dreamweaver Mac版

Dreamweaver Mac版

视觉化网页开发工具