찾다
웹 프론트엔드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으로 문의하세요.
텍스트에서 웹 사이트로 : HTML의 힘텍스트에서 웹 사이트로 : HTML의 힘Apr 13, 2025 am 12:07 AM

HTML은 웹 페이지를 작성하는 데 사용되는 언어로, 태그 및 속성을 통해 웹 페이지 구조 및 컨텐츠를 정의합니다. 1) HTML과 같은 태그를 통해 문서 구조를 구성합니다. 2) 브라우저는 HTML을 구문 분석하여 DOM을 빌드하고 웹 페이지를 렌더링합니다. 3) 멀티미디어 기능을 향상시키는 HTML5의 새로운 기능. 4) 일반적인 오류에는 탈수 된 레이블과 인용되지 않은 속성 값이 포함됩니다. 5) 최적화 제안에는 시맨틱 태그 사용 및 파일 크기 감소가 포함됩니다.

HTML, CSS 및 JavaScript 이해 : 초보자 안내서HTML, CSS 및 JavaScript 이해 : 초보자 안내서Apr 12, 2025 am 12:02 AM

WebDevelopmentReliesonHtml, CSS 및 JavaScript : 1) HtmlStructuresContent, 2) CSSSTYLESIT, 및 3) JAVASCRIPTADDSINGINTERACTIVITY, BASISOFMODERNWEBEXPERIENCES를 형성합니다.

HTML의 역할 : 웹 컨텐츠 구조HTML의 역할 : 웹 컨텐츠 구조Apr 11, 2025 am 12:12 AM

HTML의 역할은 태그 및 속성을 통해 웹 페이지의 구조와 내용을 정의하는 것입니다. 1. HTML은 읽기 쉽고 이해하기 쉽게하는 태그를 통해 컨텐츠를 구성합니다. 2. 접근성 및 SEO와 같은 시맨틱 태그 등을 사용하십시오. 3. HTML 코드를 최적화하면 웹 페이지로드 속도 및 사용자 경험이 향상 될 수 있습니다.

HTML 및 코드 : 용어를 자세히 살펴 봅니다HTML 및 코드 : 용어를 자세히 살펴 봅니다Apr 10, 2025 am 09:28 AM

"Code"는 "Code"BroadlyIncludeLugageslikeJavaScriptandPyThonforFunctureS (htMlisAspecificTypeofCodeFocudecturecturingWebContent)

HTML, CSS 및 JavaScript : 웹 개발자를위한 필수 도구HTML, CSS 및 JavaScript : 웹 개발자를위한 필수 도구Apr 09, 2025 am 12:12 AM

HTML, CSS 및 JavaScript는 웹 개발의 세 가지 기둥입니다. 1. HTML은 웹 페이지 구조를 정의하고 등과 같은 태그를 사용합니다. 2. CSS는 색상, 글꼴 크기 등과 같은 선택기 및 속성을 사용하여 웹 페이지 스타일을 제어합니다.

HTML, CSS 및 JavaScript의 역할 : 핵심 책임HTML, CSS 및 JavaScript의 역할 : 핵심 책임Apr 08, 2025 pm 07:05 PM

HTML은 웹 구조를 정의하고 CSS는 스타일과 레이아웃을 담당하며 JavaScript는 동적 상호 작용을 제공합니다. 세 사람은 웹 개발에서 의무를 수행하고 화려한 웹 사이트를 공동으로 구축합니다.

HTML은 초보자를 위해 쉽게 배우나요?HTML은 초보자를 위해 쉽게 배우나요?Apr 07, 2025 am 12:11 AM

HTML은 간단하고 배우기 쉽고 결과를 빠르게 볼 수 있기 때문에 초보자에게 적합합니다. 1) HTML의 학습 곡선은 매끄럽고 시작하기 쉽습니다. 2) 기본 태그를 마스터하여 웹 페이지를 만들기 시작하십시오. 3) 유연성이 높고 CSS 및 JavaScript와 함께 사용할 수 있습니다. 4) 풍부한 학습 리소스와 현대 도구는 학습 과정을 지원합니다.

HTML의 시작 태그의 예는 무엇입니까?HTML의 시작 태그의 예는 무엇입니까?Apr 06, 2025 am 12:04 AM

anexampleStartingtaginhtmlis, whithbeginsaparagraph.startingtagsareessentialinhtmlastheyinitiate rements, definetheirtypes, andarecrucialforstructurituringwebpages 및 smanstlingthedom.

See all articles

핫 AI 도구

Undresser.AI Undress

Undresser.AI Undress

사실적인 누드 사진을 만들기 위한 AI 기반 앱

AI Clothes Remover

AI Clothes Remover

사진에서 옷을 제거하는 온라인 AI 도구입니다.

Undress AI Tool

Undress AI Tool

무료로 이미지를 벗다

Clothoff.io

Clothoff.io

AI 옷 제거제

AI Hentai Generator

AI Hentai Generator

AI Hentai를 무료로 생성하십시오.

인기 기사

R.E.P.O. 에너지 결정과 그들이하는 일 (노란색 크리스탈)
3 몇 주 전By尊渡假赌尊渡假赌尊渡假赌
R.E.P.O. 최고의 그래픽 설정
3 몇 주 전By尊渡假赌尊渡假赌尊渡假赌
R.E.P.O. 아무도들을 수없는 경우 오디오를 수정하는 방법
3 몇 주 전By尊渡假赌尊渡假赌尊渡假赌
WWE 2K25 : Myrise에서 모든 것을 잠금 해제하는 방법
4 몇 주 전By尊渡假赌尊渡假赌尊渡假赌

뜨거운 도구

Atom Editor Mac 버전 다운로드

Atom Editor Mac 버전 다운로드

가장 인기 있는 오픈 소스 편집기

ZendStudio 13.5.1 맥

ZendStudio 13.5.1 맥

강력한 PHP 통합 개발 환경

SublimeText3 중국어 버전

SublimeText3 중국어 버전

중국어 버전, 사용하기 매우 쉽습니다.

WebStorm Mac 버전

WebStorm Mac 버전

유용한 JavaScript 개발 도구

VSCode Windows 64비트 다운로드

VSCode Windows 64비트 다운로드

Microsoft에서 출시한 강력한 무료 IDE 편집기