Elasticsearch进阶教程：生成离线官方文档
原创Elasticsearch进阶教程：生成离线官方文档
原创
Elastic stack产品相关的文档是由专门的文档团队维护的，内容详实、更新及时，几乎能够通过查找文档的方式解决大部分平时使用上的问题，如此优秀的文档，可以被认为是业内的标杆。我的日常工作中，就需要非常频繁的访问官方文档。
国内访问的Elastic官网的障碍
然而，故事总有另外一面，虽然频率不是特别高，但仍然有不少客户或者用户会向我询问或者要求提供离线的官方文档。特别是对于一些网络受限的用户来说，访问部署在https://www.elastic.co/guide/index.html上的官方文档是一件非常痛苦，甚至是无法办到的事情。比如金融行业里的IT运维的同学，就常年处于网络受限的环境，不仅是访问国外网站走单独的低带宽、高延迟的通道，并且很多总所周知的网址是无法访问的。而偏偏elastic的官网，却有非常多的外部链接：
这些外部链接中，一旦有那么几个是访问缓慢或者无法访问的。就会造成整个页面无法正确渲染或者打开。这就使用离线访问官方文档成了一项能被理解并且应被满足的需求。
我们曾经探讨过将官方文档部署在腾讯云或者阿里云上的可能，但因为产品发布和文档更新频率，以及其他的一些阻碍，至今没能完成这一目标。
因此，我们将在本文中讨论自己构建一个特定版本的离线官方文档的方法。
构建一个特定版本的离线官方文档
作为最成功的开源项目的上市公司的工程团队，我们也有一套完整且优秀的工具和流程来自动发布产品的文档。并且，这个项目是以public的方式开放于github的：
- https://github.com/elastic/docs
- https://github.com/elastic/built-docs
这里我提供了两个github的地址，第一个（/elastic/docs）是我们修改、更新内容和构建文档的工具，而第二个（/elastic/built-docs）是构建出来的内容存放的仓库。
构建自发布的官方文档
对于需要自己更改文档内容的团队来说，可以使用第一个github仓库。
git clone https://github.com/elastic/docs然后按照HowTo里的教程进行构建和发布。
比如说，腾讯云的elasticsearch service的团队，可以将自己的内核改动、插件、高级功能的特性变成整体文档的一部分放到elasticsearch的文档当中，就可以采用/elastic/docs里描述的方式进行文档的更新、修改和生成。再讲生成好的HTML 文档进行发布即可。
获取已发布的离线官方文档
而对于我们其他的用户来说，大部分的需求以获取一份离线文档为主，则不需要这么麻烦。我们需要的是把第二个仓库保存到本地：
git clone https://github.com/elastic/built-docs这里的内容是通过运行docs 构建生成的，包含了产品的历史版本的文档。因此，如果要整个项目clone下来，体积是很庞大的（有10多个GB）。
仓库的目录结构如下：
如果我们要下载特定版本的elasticsearch的文档，一路导航即可。
然后通过svn等工具，只下载特定目录下的内容。这时，下载下来的文档中会包含一些外部链接，比如，我们看这个文档，https://github.com/elastic/built-docs/blob/master/html/en/elasticsearch/reference/7.10/_actions.html
就包含了：
- <linkrel="stylesheet" type="text/css" href="/guide/static/styles.css" />
- <spanclass="breadcrumb-link"><ahref="/guide/">Elastic Docs</a></span><spanclass="chevron-right">›</span>
- <scriptsrc="/guide/static/jquery.js"></script>
- <scripttype="text/javascript" src="/guide/static/docs.js"></script>
而目录/guide, 却并不包含在你下载的离线文档包了。因为这里的相对路径，都是按照elastic.co官网上的部署目录来进行配置的。
因此，为了能在离线文档中也能够正确的加载对应的资源，渲染出页面，我们还需要下载另外一个目录(https://github.com/elastic/built-docs/tree/master/html/static) 里的内容：
然后在所有的文档中，将/guide替换为你保存static 的位置（path_to_your_static）
使用同样的方法，我们可以获取所有产品文档的离线内容：
比如，我们下载了以下内容：
tree -L 1
.
├── elasticsearch_7.10
├── hadoop_7.10
├── index.html
├── kibana_7.10
├── ml_7.10
└── static可以构建这样的一个Index.html来访问：
<!DOCTYPE html>
<html lang="en-us">
<head>
<meta charset="UTF-8">
<title>Elastic Stack and Product Documentation | Elastic</title>
<meta name="DC.type" content="Learn/Docs/"/>
<meta name="DC.subject" content=""/>
<meta name="DC.identifier" content=""/>
<meta http-equiv="content-type" content="text/html; charset=utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<script src="https://cdn.optimizely.com/js/18132920325.js"></script>
<link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
<link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
<link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
<link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
<link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
<link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
<link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
<link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
<link rel="icon" type="image/png" href="/favicon-32x32.png" sizes="32x32">
<link rel="icon" type="image/png" href="/android-chrome-192x192.png" sizes="192x192">
<link rel="icon" type="image/png" href="/favicon-96x96.png" sizes="96x96">
<link rel="icon" type="image/png" href="/favicon-16x16.png" sizes="16x16">
<link rel="manifest" href="/manifest.json">
<meta name="apple-mobile-web-app-title" content="Elastic">
<meta name="application-name" content="Elastic">
<meta name="msapplication-TileColor" content="#ffffff">
<meta name="msapplication-TileImage" content="/mstile-144x144.png">
<meta name="theme-color" content="#ffffff">
<meta name="naver-site-verification" content="936882c1853b701b3cef3721758d80535413dbfd" />
<meta name="yandex-verification" content="d8a47e95d0972434" />
<meta name="localized" content="true" />
<meta name="st:robots" content="follow,index" />
<meta property="og:image" content="https://www.elastic.co/static/images/elastic-logo-200.png" />
<link rel="shortcut icon" href="/favicon.ico" type="image/x-icon">
<link rel="icon" href="/favicon.ico" type="image/x-icon">
<link rel="apple-touch-icon-precomposed" sizes="64x64" href="/favicon_64x64_16bit.png">
<link rel="apple-touch-icon-precomposed" sizes="32x32" href="/favicon_32x32.png">
<link rel="apple-touch-icon-precomposed" sizes="16x16" href="/favicon_16x16.png">
<!-- Give IE8 a fighting chance -->
<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.2/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->
<link rel="stylesheet" type="text/css" href="./static/styles.css" />
</head>
<!--© 2015-2021 Elasticsearch B.V. Copying, publishing and/or distributing without written permission is strictly prohibited.-->
<body>
<!-- Subnav -->
<div>
<div>
<div class="tertiary-nav d-none d-md-block">
<div class="container">
<div class="p-t-b-15 d-flex justify-content-between nav-container">
<div class="breadcrum-wrapper"><span><a href="/guide/" style="font-size: 14px; font-weight: 600; color: #000;">Docs</a></span></div>
</div>
</div>
</div>
</div>
</div>
<div class="main-container">
<section id="content" >
<div class="content-wrapper">
<section id="guide" lang="en">
<div class="container">
<div class="row">
<div class="col-xs-12 col-sm-8 col-md-8 guide-section">
<!-- start body -->
<div id="extra">
<div style="visibility: hidden;"></div>
</div>
<div class="article" lang="en">
<div class="titlepage">
<div>
<div><h1 class="title"><a id="id-1"></a>Elastic Stack and Product Documentation</h1></div>
</div>
<hr>
</div>
<div id="content">
<h3><a id="_elasticsearch_store_search_and_analyze"></a>Elasticsearch: Store, Search, and Analyze</h3>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a href="elasticsearch_7.10/index.html" class="ulink" target="_top">Elasticsearch Guide [7.10]</a>
</li>
<li class="listitem">
<a href="ml_7.10/index.html" class="ulink" target="_top">Machine Learning [7.10]</a>
</li>
<li class="listitem">
<a href="hadoop_7.10/index.html" class="ulink" target="_top">Elasticsearch for Apache Hadoop and Spark [7.10]</a>
</li>
</ul>
</div>
</div>
<h3><a id="_kibana_explore_visualize_and_share"></a>Kibana: Explore, Visualize, and Share</h3>
<div class="ulist itemizedlist">
<ul class="itemizedlist">
<li class="listitem">
<a href="kibana_7.10/index.html" class="ulink" target="_top">Kibana Guide [7.10]</a>
</li>
</ul>
</div>
</body>
</html>
显示为：
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。
原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。
如有侵权，请联系 cloudcommunity@tencent.com 删除。