docs/docker.github.io

Docker文档仓库

欢迎来到Docker文档仓库。此仓库是[***]

欢迎提交拉取请求和反馈问题。我们的文档完全开源，非常感谢社区的贡献！

目录

• 提供反馈
• 贡献文档
  • 不在这里编辑的文件
  • 整体文档改进
  • 特定项目的新功能
• PR的GitHub暂存
• 暂存文档
• 离线阅读文档
• 重要文件
• GitHub查看的相对链接
  • 测试更改和实践指南
  • 页面前置元数据
  • 创建标签页
  • 运行页面内JavaScript
  • 图片
• Beta内容免责声明
• 访问不受支持的归档文档
• 构建归档和实时发布文档
• 创建新归档
• 版权和许可

提供反馈

我们非常重视您的反馈，并已简化反馈流程。您可以在docs.docker.com的每一页右侧栏编辑页面或请求更改，也可以点击页脚链接对页面进行评分。

仅在此仓库提交与文档相关的问题。简单来说，如果您发现文档中缺少应有的内容，或存在错误、混淆之处，请在此提交问题。

• 如果您的问题是关于如何配置或使用Docker的一般疑问，请前往[***]
• 如果您对Docker特定方面有新功能想法、行为变更建议，或发现代码bug，请在相应项目的代码仓库中提交问题。

贡献文档

我们重视您的文档贡献，并致力于简化在此仓库的工作流程。首先需要确定基于哪个分支开展工作。如有疑问，欢迎咨询。如果审核者发现您基于错误分支开展工作，会告知您进行变基。

注意：如需为Docker项目贡献代码，请参阅贡献指南。

不在这里编辑的文件

.NOT_EDITED_HERE.yaml中path:键列出的文件和目录由其他仓库维护，不应在此仓库编辑。针对这些文件的拉取请求将被拒绝。请在YAML文件中source:键指定的仓库和路径中编辑文件。

整体文档改进

大多数提交应基于master分支，包括：

• 不特定于新功能的概念性和任务型信息
• 结构调整/重写
• 文档bug修复
• 拼写和语法错误

本项目的一个特点是master分支是实时文档的发布源，因此不能在此记录即将发布的功能。有关如何记录即将发布功能的方法，请参见特定项目的新功能。这些功能分支将定期与master合并，因此无需担心在这些分支上修复拼写和文档bug。

您喜欢创建图表吗？优质图表是优秀文档的关键，我们特别重视这方面的贡献。

特定项目的新功能

我们的文档涵盖多个项目，这些项目的发布时间不同。仅当您的拉取请求涉及某个项目当前未发布的功能时，才基于该项目的vnext分支开展工作。这些分支是通过克隆master并导入项目master分支的文档（在迁移时）创建的，同时保留了提交历史。当项目发布时，其vnext分支将合并到master，您的工作将在[***]

当前存在以下vnext分支：

• https://github.com/docker/docker.github.io/tree/vnext-engine: https://github.com/moby/moby/%E9%A1%B9%E7%9B%AE%E5%8D%B3%E5%B0%86%E5%8F%91%E5%B8%83%E5%8A%9F%E8%83%BD%E7%9A%84%E6%96%87%E6%A1%A3
• https://github.com/docker/docker.github.io/tree/vnext-compose: https://github.com/docker/compose/%E9%A1%B9%E7%9B%AE%E5%8D%B3%E5%B0%86%E5%8F%91%E5%B8%83%E5%8A%9F%E8%83%BD%E7%9A%84%E6%96%87%E6%A1%A3
• https://github.com/docker/docker.github.io/tree/vnext-distribution: https://github.com/docker/distribution/%E9%A1%B9%E7%9B%AE%E5%8D%B3%E5%B0%86%E5%8F%91%E5%B8%83%E5%8A%9F%E8%83%BD%E7%9A%84%E6%96%87%E6%A1%A3
• https://github.com/docker/docker.github.io/tree/vnext-swarm: https://github.com/docker/swarm/%E9%A1%B9%E7%9B%AE%E5%8D%B3%E5%B0%86%E5%8F%91%E5%B8%83%E5%8A%9F%E8%83%BD%E7%9A%84%E6%96%87%E6%A1%A3
• https://github.com/docker/docker.github.io/tree/vnext-toolbox: https://github.com/docker/toolbox/%E9%A1%B9%E7%9B%AE%E5%8D%B3%E5%B0%86%E5%8F%91%E5%B8%83%E5%8A%9F%E8%83%BD%E7%9A%84%E6%96%87%E6%A1%A3

PR的GitHub暂存

对于针对master和所有长期分支的每个PR，Netlify会构建网站的暂存版本。如果网站构建成功，您将看到deploy/netlify — Deploy preview ready；否则会显示错误。点击Details可查看暂存网站或构建失败的错误信息。请检查暂存网站并在必要时修改提交。审核者在合并PR前也会检查暂存网站，以确保[***]

暂存文档

您有三种选择：

1. 在本地机器上克隆此仓库并运行暂存容器：

   bash
   git clone --recursive https://github.com/docker/docker.github.io.git
   cd docker.github.io
   docker-compose up
   

   如果尚未安装Docker Compose，请按照这些安装说明操作。

   容器在后台运行，每次文件更改时都会增量重建网站。您可以保持浏览器打开http://localhost:4000/，刷新即可查看更改。容器在前台运行，可使用`CTRL+C`返回命令提示符。要停止容器，请执行以下命令：

   bash
   docker-compose down
   

2. 在本地机器上安装Jekyll和GitHub Pages。

   a. 克隆此仓库：

   bash
   git clone --recursive https://github.com/docker/docker.github.io.git
   

   b. 按照安装Ruby中的说明安装Ruby 2.3或更高版本。

   c. 安装Bundler：

   bash
   gem install bundler
   

   d. 如果使用Ubuntu，安装Nokogiri HTML解析器所需的包：

   bash
   sudo apt-get install ruby-dev zlib1g-dev liblzma-dev
   

   e. 安装Jekyll和其他所需依赖：

   bash
   bundle install
   

   注意：您可能需要手动安装一些包。

   f. 进入docker.github.io目录。

   g. 使用jekyll serve命令持续构建HTML输出。

   jekyll serve进程在前台运行，默认启动http://localhost:4000/的Web服务器。要停止它，使用`CTRL+C`。您可以在第二个终端继续工作，Jekyll会增量重建网站。刷新浏览器即可预览更改。

3. 为工作分支构建并运行Docker镜像。

   bash
   $ docker build -t docs/docker.github.io:<branch_name> .
   $ docker run --rm -it -p 4000:4000 docs/docker.github.io:<branch_name>
   

   执行docker run命令后，将容器构建输出中提供的URL（[***]

离线阅读文档

要离线阅读文档，可以使用独立容器或swarm服务。要查看所有可用标签，请访问Docker Hub。

以下示例使用latest标签：

• 运行单个容器：

  bash
  docker run -it -p 4000:4000 docs/docker.github.io:latest
  

• 运行swarm服务：

  bash
  docker service create -p 4000:4000 --name localdocs --replicas 1 docs/docker.github.io:latest
  

  此示例仅使用一个副本，但您可以根据需要运行任意数量的副本。

无论哪种方式，现在都可以通过Docker主机的4000端口访问文档。

重要文件

• /_data/toc.yaml定义文档的左侧导航
• /js/menu.js定义大多数文档特定的JS，如TOC生成和菜单同步
• /css/style.scss定义文档特定的样式规则
• /_layouts/docs.html是HTML模板文件，定义页眉和页脚，并包含所有服务文档内容的JS/CSS

GitHub查看的相对链接

可以链接到../foo.md以便在GitHub中阅读文档，但请注意Jekyll模板标记{% 例如这样 %}将以原始文本形式呈现，不会被处理。通常最好假设文档是在[***]

测试更改和实践指南

如果要测试样式更改，或想了解如何使用Markdown、Bootstrap、JQuery等实现特定效果，请查看test.md（在网站上呈现为/test/）。

页面前置元数据

页面的前置元数据位于Markdown文件顶部的部分，以三个连字符开始和结束，包含YAML内容。支持以下键。标题、描述和关键字是必需的。

以下是有效（但虚构）的页面元数据示例。前置元数据中元素的顺序不重要。

liquid
---
description: 在Ubuntu上安装Docker的说明
keywords: 要求, apt, 安装, ubuntu, 安装, 卸载, 升级, 更新
redirect_from:
- /engine/installation/ubuntulinux/
- /installation/ubuntulinux/
- /engine/installation/linux/ubuntulinux/
title: 获取适用于Ubuntu的Docker
toc_min: 1
toc_max: 6
skip_read_time: true
no_ratings: true
---

创建标签页

如[***] CSS/JS，有关更高级的用法，请参考其文档。对于基本的水平标签页集，复制粘贴以下代码并进行实现。重命名、添加和删除标签页时，请注意href="#id"和id="id"引用。

<ul class="nav nav-tabs">
  <li class="active"><a data-toggle="tab" data-target="#tab1">标签页1标题</a></li>
  <li><a data-toggle="tab" data-target="#tab2">标签页2标题</a></li>
</ul>
<div class="tab-content">
  <div id="tab1" class="tab-pane fade in active">标签页1内容</div>
  <div id="tab2" class="tab-pane fade">标签页2内容</div>
</div>

有关更多信息和更多排列方式，请参见test.md。

运行页面内JavaScript

如果需要在页面内运行依赖JQuery或Bootstrap的自定义JavaScript，请确保<script>标签位于页面的最末尾，在所有内容之后。否则脚本可能会在JQuery和Bootstrap JS加载之前尝试运行。

注意：通常，这不是一个好主意。

图片

不要忘记删除不再使用的图片。将图片按名称在本地images/目录中排序，使相关图片按字母顺序自然分组。例如，优先使用settings-file-share.png和settings-proxies.png，而不是file-share-settings.png和proxies-settings.png。您也可以使用数字，特别是在序列情况下，例如run-only-the-images-you-trust-1.svg、run-only-the-images-you-trust-2.png、run-only-the-images-you-trust-3.png。

在适用情况下，捕获窗口而不是矩形区域。这可以消除令人不快的背景，并节省编辑者的裁剪需求。

在Mac上，捕获窗口时不要包含阴影。为此，按下Command-Shift-4后，按住Option键并点击窗口。要永久禁用阴影，请运行：

bash
$ defaults write com.apple.screencapture disable-shadow -bool TRUE
$ killall SystemUIServer  # 重启它。

之后可以使用-bool FALSE恢复阴影。

为保持Git仓库轻量化，请务必（无损）压缩图片。在Mac上，您可以使用ImageOptim等工具。请确保在将图片添加到仓库之前进行压缩，之后压缩实际上会增加对Git仓库的影响（但仍能优化浏览时的带宽）。

Beta内容免责声明

bash
> BETA免责声明
>
> 这是Beta内容。尚未完成，应视为正在进行的工作。此内容可能会随时更改，恕不另行通知。

访问不受支持的归档文档

受支持的文档包括当前版本以及之前的五个版本。

如果您使用的文档版本不再受支持（即版本号未在站点下拉列表中列出），仍可以通过以下方式访问该文档：

• 输入您的版本号并从本仓库的分支选择列表中选择
• 直接访问您版本的GitHub URL。例如，v1.9的URL为https://github.com/docker/docker.github.io/tree/v1.9
• 在Docker Hub中运行特定https://hub.docker.com/r/docs/docker.github.io/tags%E7%9A%84%E5%AE%B9%E5%99%A8%E3%80%82%E4%BE%8B%E5%A6%82%EF%BC%8C%E8%BF%90%E8%A1%8C%E4%BB%A5%E4%B8%8B%E5%91%BD%E4%BB%A4%E8%AE%BF%E9%97%AE%60v1.9%60%EF%BC%9A

bash
 docker run -it -p 4000:4000 docs/docker.github.io:v1.9

构建归档和实时发布文档

以下所有镜像均通过Docker Hub自动构建。要手动从头开始构建站点（包括所有实用工具和归档镜像），请参见https://github.com/docker/docker.github.io/blob/publish-tools/README.md%E3%80%82

• 一些实用工具镜像从publish-tools分支中的Dockerfile构建。有关详细信息，请参见其https://github.com/docker/docker.github.io/blob/publish-tools/README.md%E3%80%82
• 每个归档分支在更改合并到该分支时，会自动构建标记为docs/docker.github.io:v<VERSION>的镜像。
• master分支有一个Dockerfile，它使用每个归档镜像的静态HTML，结合master中的Markdown文件和构建时获取的一些上游资源，创建[[***]](/）上的完整站点。所有长期运行的分支（如vnext-engine、vnext-compose等）都使用相同的逻辑。

创建新归档

当Docker Engine - Community Stable的新版本发布时，master的先前状态会归档到特定版本的分支（如v17.09），步骤如下：

1. 基于新版本发布前的提交哈希创建分支。

   bash
   $ git checkout <哈希值>
   $ git checkout -b v17.09
   

2. 运行_scripts/fetch-upstream-resources.sh脚本。这会将master构建通常在每次构建时获取的文件的静态副本放置到位。

   bash
   $ _scripts/fetch-upstream/resources.sh
   

3. 用Dockerfile.archive覆盖Dockerfile（使用cp而不是mv，以免意外删除任一文件）。编辑生成的Dockerfile，将VER构建参数设置为适当的值，如v17.09。

   bash
   $