diff --git a/README.md b/README.md index b18cb10..5091474 100644 --- a/README.md +++ b/README.md @@ -32,3 +32,299 @@ GitHub 上有关 CWIKIUS Docker 的项目的源代码文件：[https://github.co | Docker 官方文档 | https://docs.docker.com/ | | chinese_docker | https://github.com/widuu/chinese_docker | | daocloud.io | https://guide.daocloud.io/#all-updates | + +Welcome to the repo for our documentation. This is the source for +[https://docs.docker.com/](https://docs.docker.com/). + +Feel free to send us pull requests and file issues. Our docs are completely +open source and we deeply appreciate contributions from our community! +## Table of Contents + +- [Providing feedback](#providing-feedback) +- [Contributing](#contributing) + - [Files not edited here](#files-not-edited-here) + - [Overall doc improvements](#overall-doc-improvements) +- [Per-PR staging on GitHub](#per-pr-staging-on-github) +- [Build and preview the docs locally](#build-and-preview-the-docs-locally) + - [Build the docs with deployment features enabled](#build-the-docs-with-deployment-features-enabled) +- [Important files](#important-files) +- [Relative linking for GitHub viewing](#relative-linking-for-github-viewing) + - [Testing changes and practical guidance](#testing-changes-and-practical-guidance) + - [Per-page front-matter](#per-page-front-matter) + - [Creating tabs](#creating-tabs) + - [Running in-page Javascript](#running-in-page-javascript) + - [Images](#images) +- [Copyright and license](#copyright-and-license) + + +## Providing feedback + +We really want your feedback, and we've made it easy. You can edit a page or +request changes in the right column of every page on +[docs.docker.com](https://docs.docker.com/). You can also rate each page by +clicking a link at the footer. + +**Only file issues about the documentation in this repository.** One way +to think about this is that you should file a bug here if your issue is that you +don't see something that should be in the docs, or you see something incorrect +or confusing in the docs. + +- If your problem is a general question about how to configure or use Docker, + ask in [https://forums.docker.com](https://forums.docker.com) instead. + +- If you have an idea for a new feature or behavior change in a specific aspect + of Docker, or have found a bug in part of Docker, file that issue in + the project's code repository. + +## Contributing + +We value your documentation contributions, and we want to make it as easy +as possible to work in this repository. One of the first things to decide is +which branch to base your work on. If you get confused, just ask and we will +help. If a reviewer realizes you have based your work on the wrong branch, we'll +let you know so that you can rebase it. + +>**Note**: To contribute code to Docker projects, see the +[Contribution guidelines](CONTRIBUTING.md). + +### Files not edited here + +Files and directories listed in the `path:` keys in +[`.NOT_EDITED_HERE.yaml`](.NOT_EDITED_HERE.yaml) are maintained in other +repositories and should not be edited in this one. Pull requests against these +files will be rejected. Make your edits to the files in the repository and path +in the `source:` key in the YAML file. + +### Overall doc improvements + +Pull requests should be opened against the `master` branch, this includes: + +- Conceptual and task-based information not specific to new features +- Restructuring / rewriting +- Doc bug fixing +- Typos and grammar errors + +> Do you enjoy creating graphics? Good graphics are key to great documentation, +> and we especially value contributions in this area. + +## Per-PR staging on GitHub + +For every PR against `master`, a staged version of the site is built using Netlify. +If the site builds, you will see **deploy/netlify — Deploy preview ready**. +Otherwise, you will see an error. Click **Details** to review the staged site or +the errors that prevented it from building. Review the staged site and amend your +commit if necessary. Reviewers will also check the staged site before merging the +PR, to protect the integrity of [https://docs.docker.com/](https://docs.docker.com/). + +## Build and preview the docs locally + +On your local machine, clone this repo: + +```bash +git clone --recursive https://github.com/docker/docker.github.io.git +cd docker.github.io +``` + +Then build and run the documentation with [Docker Compose](https://docs.docker.com/compose/) + +```bash +docker-compose up -d --build +``` + +> Docker Compose is included with [Docker Desktop](https://docs.docker.com/desktop/). +> If you don't have Docker Compose installed, [follow these installation instructions](https://docs.docker.com/compose/install/). + +Once the container is built and running, visit [http://localhost:4000](http://localhost:4000) +in your web browser to view the docs. + +To rebuild the docs after you made changes, run the `docker-compose up` command +again. This rebuilds the documentation, and updates the container with your changes: + +```bash +docker-compose up -d --build +``` + +Once the container is built and running, visit [http://localhost:4000](http://localhost:4000) +in your web browser to view the docs. + + +To stop the staging container, use the `docker-compose down` command: + +```bash +docker-compose down +``` + +### Build the docs with deployment features enabled + +The default configuration for local builds of the documentation disables some +features to allow for a shorter build-time. The following options differ between +local builds, and builds that are deployed to docs.docker.com: + +- search auto-completion, and generation of `js/metadata.json` +- google analytics +- page ratings +- `sitemap.xml` generation +- minification of stylesheets (css/style.css) +- adjusting "edit this page" links for content in other repositories + +If you want to contribute in these areas, you can perform a "production" build +locally. + +To preview the documentation with deployment features enabled, you need to set the +`JEKYLL_ENV` environment variable when building the documentation; + +```bash +JEKYLL_ENV=production docker-compose up --build +``` + +Once the container is built and running, visit [http://localhost:4000](http://localhost:4000) +in your web browser to view the docs. + +To rebuild the docs after you make changes, repeat the steps above. + + + +## Important files + +- `/_data/toc.yaml` defines the left-hand navigation for the docs +- `/js/docs.js` defines most of the docs-specific JS such as TOC generation and menu syncing +- `/css/style.scss` defines the docs-specific style rules +- `/_layouts/docs.html` is the HTML template file, which defines the header and footer, and includes all the JS/CSS that serves the docs content + +## Relative linking for GitHub viewing + +Feel free to link to `../foo.md` so that the docs are readable in GitHub, but keep in mind that Jekyll templating notation +`{% such as this %}` will render in raw text and not be processed. In general it's best to assume the docs are being read +directly on [https://docs.docker.com/](https://docs.docker.com/). + +### Testing changes and practical guidance + +If you want to test a style change, or if you want to see how to achieve a +particular outcome with Markdown, Bootstrap, JQuery, or something else, have +a look at `test.md` (which renders in the site at `/test/`). + +### Per-page front-matter + +The front-matter of a given page is in a section at the top of the Markdown +file that starts and ends with three hyphens. It includes YAML content. The +following keys are supported. The title, description, and keywords are required. + +| Key | Required | Description | +|------------------------|-----------|-----------------------------------------| +| title | yes | The page title. This is added to the HTML output as a `

` level header. | +| description | yes | A sentence that describes the page contents. This is added to the HTML metadata. | +| keywords | yes | A comma-separated list of keywords. These are added to the HTML metadata. | +| redirect_from | no | A YAML list of pages which should redirect to THIS page. At build time, each page listed here is created as a HTML stub containing a 302 redirect to this page. | +| notoc | no | Either `true` or `false`. If `true`, no in-page TOC is generated for the HTML output of this page. Defaults to `false`. Appropriate for some landing pages that have no in-page headings.| +| toc_min | no | Ignored if `notoc` is set to `true`. The minimum heading level included in the in-page TOC. Defaults to `2`, to show `

` headings as the minimum. | +| toc_max | no | Ignored if `notoc` is set to `false`. The maximum heading level included in the in-page TOC. Defaults to `3`, to show `

` headings. Set to the same as `toc_min` to only show `toc_min` level of headings. | +| no_ratings | no | Either `true` or `false`. Set to `true` to disable the page-ratings applet for this page. Defaults to `false`. | +| skip_read_time | no | Set to `true` to disable the 'Estimated reading time' banner for this page. | +| sitemap | no | Exclude the page from indexing by search engines. When set to `false`, the page is excluded from `sitemap.xml`, and a `` header is added to the page. | + +The following is an example of valid (but contrived) page metadata. The order of +the metadata elements in the front-matter is not important. + +```liquid +--- +description: Instructions for installing Docker on Ubuntu +keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update +redirect_from: +- /engine/installation/ubuntulinux/ +- /installation/ubuntulinux/ +- /engine/installation/linux/ubuntulinux/ +title: Get Docker for Ubuntu +toc_min: 1 +toc_max: 6 +skip_read_time: true +no_ratings: true +--- +``` + +### Creating tabs + +The use of tabs, as on pages like [https://docs.docker.com/engine/api/](/engine/api/), requires +the use of HTML. The tabs use Bootstrap CSS/JS, so refer to those docs for more +advanced usage. For a basic horizontal tab set, copy/paste starting from this +code and implement from there. Keep an eye on those `href="#id"` and `id="id"` +references as you rename, add, and remove tabs. + +```html + +
+
TAB 1 CONTENT
+
TAB 2 CONTENT
+
+``` + +For more info and a few more permutations, see `test.md`. + +### Running in-page Javascript + +If you need to run custom Javascript within a page, and it depends upon JQuery +or Bootstrap, make sure the `