docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #13909 from usha-mandya/engdocs-542 

Consolidate Docs contribution guidelines and demo test page
This commit is contained in:
Sebastiaan van Stijn 2022-01-14 09:38:00 +01:00 committed by GitHub
parent 23028ed0ec 67a6194283
commit fcaa6eb8fa
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 361 additions and 444 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

275
CONTRIBUTING.md
View File

@ -1,43 +1,113 @@
## Contributing
# Contributing to Docker Documentation
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.
We deeply value documentation contributions from the Docker community. We'd like to make it as easy
as possible for you to work in this repository. The documentation for Docker is published at [https://docs.docker.com/](https://docs.docker.com/). The following sections guide you through the process of contributing to Docker documentation.
>**Note**: To contribute code to Docker projects, see the
[Contribution guidelines](/opensource/index.md).
## Table of Contents
### Quickstart
- [Contribution guidelines](#contribution-guidelines)
- [Files not edited here](#files-not-edited-here)
- [Important files](#important-files)
- [Per-page front-matter](#per-page-front-matter)
- [Pull request guidelines](#pull-request-guidelines)
- [Collaborate on a pull request](#collaborate-on-a-pull-request)
- [Per-PR staging on GitHub](#per-pr-staging-on-github)
- [Relative linking for GitHub viewing](#relative-linking-for-github-viewing)
- [Testing changes and practical guidance](#testing-changes-and-practical-guidance)
- [Creating tabs](#creating-tabs)
- [Running in-page Javascript](#running-in-page-javascript)
- [Images](#images)
- [Style guide](#style-guide)
- [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)
- [Copyright and license](#copyright-and-license)
If you spot a problem while reading the documentation and want to try to fix it
yourself, click the **Edit this page** link at the bottom of that page. The
page will open in the Github editor, which means you don't need to know a lot
about Git, or even about Markdown.
## Contribution guidelines
When you save, you will be prompted to create a fork if you don't already have
one, and to create a branch in your fork and submit the pull request. We hope
you give it a try!
The live docs are published from the `master` branch. Therefore, you must create pull requests against the `master` branch for all content updates. This includes:
### Overall doc improvements
Most commits will be made against the `master` branch. This includes:
- Conceptual and task-based information not specific to new features
- Conceptual and task-based information
- Restructuring / rewriting
- Doc bug fixing
- Typos and grammar errors
- Fixing typos, broken links, and any grammar errors
One quirk of this project is that the `master` branch is where the live docs are
published from, so upcoming features can't be documented there. See
[Specific new features for a project](#specific-new-features-for-a-project)
for how to document upcoming features. These feature branches will be periodically
merged with `master`, so don't worry about fixing typos and documentation bugs
there.
There are two ways to contribute a pull request to the docs repository:
>Do you enjoy creating graphics? Good graphics are key to great documentation,
and we especially value contributions in this area.
1. You can click **Edit this page** option in the right column of every page on [https://docs.docker.com/](https://docs.docker.com/).
This opens the GitHub editor, which means you don't need to know a lot about Git, or even about Markdown. When you save, Git prompts you to create a fork if you don't already have one, and to create a branch in your fork and submit the pull request.
2. Fork the [docs GitHub repository](https://github.com/docker/docker.github.io). Suggest changes or add new content on your local branch, and submit a pull request (PR) to the `master` branch.
This is the manual, more advanced version of clicking 'Edit this page' on a published docs page. Initiating a docs changes in a PR from your own branch gives you more flexibility, as you can submit changes to multiple pages or files under a single pull request, and even create new topics.
For a demo of the components, tags, Markdown syntax, styles, etc we use at [https://docs.docker.com/](https://docs.docker.com/), see [test.md](/test.md).
### Important files
Here’s a list of some of the 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 the table of contents (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
### Files not edited here
Some files and directories are maintained in the upstream repositories. You can find a list of such files in [`_config_production.yml`](_config_production.yml#L52). Pull requests against these files will be rejected.
### 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 `<h1>` 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 the current page. At build time, each page listed here is created as an 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 `<h2>` 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 `<h3>` headings. Set to the same as `toc_min` to only show `toc_min` level of headings. |
| 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 `<meta name="robots" content="noindex"/>` header is added to the page. |
Here's an example of a valid (but contrived) page metadata. The order of
the metadata elements in the front-matter isn't important.
```liquid
---
description: Instructions for installing Docker Engine on Ubuntu
keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update
title: Install Docker Engine on Ubuntu
redirect_from:
- /ee/docker-ee/ubuntu/
- /engine/installation/linux/docker-ce/ubuntu/
- /engine/installation/linux/docker-ee/ubuntu/
- /engine/installation/linux/ubuntu/
- /engine/installation/linux/ubuntulinux/
- /engine/installation/ubuntulinux/
- /install/linux/docker-ce/ubuntu/
- /install/linux/docker-ee/ubuntu/
- /install/linux/ubuntu/
- /installation/ubuntulinux/
toc_max: 4
---
```
## Pull request guidelines
Help us review your PRs more quickly by following these guidelines.
- Try not to touch a large number of files in a single PR if possible.
- Don't change whitespace or line wrapping in parts of a file you are not
editing for other reasons. Make sure your text editor is not configured to
automatically reformat the whole file when saving.
- We highly recommend that you build the docs locally and verify your changes before submitting a PR. See the section [Build and preview the docs locally](#build-and-preview-the-docs-locally).
- A Netlify test runs for each PR that is against the `master` branch, and deploys the result of your PR to a staging site. The URL will be available at in the **Conversation** tab. Check the staging site to verify how your changes look and fix issues, if necessary.
- Use relative linking to link to other topics. See [Relative linking for GitHub viewing](#relative-linking-for-GitHub-viewing).
## Collaborate on a pull request
@ -49,29 +119,138 @@ given file in the **Files** view.
If a PR consists of multiple small addendum commits on top of a more significant
one, the commit will usually be "squash-merged", so that only one commit is
merged in. On occasion this is not appropriate and all commits will be kept
separate when merging.
merged into the `master` branch. In some scenarios where a squash and merge isn't appropriate, all commits are kept separate when merging.
## Pull request guidelines
## Per-PR staging on GitHub
Help us review your PRs more quickly by following these guidelines.
A Netlify test runs for each PR created against the `master` branch and deploys the result of your PR to a staging site. When the site builds successfully, you will see a comment in the **Conversation** tab in the PR stating **Deploy Preview for docsdocker ready!**. Click the **Browse the preview** URL and check the staging site to verify how your changes look and fix issues, if necessary. Reviewers also check the staged site before merging the PR to protect the integrity of the docs site.
- Try not to touch a large number of files in a single PR if possible.
## Relative linking for GitHub viewing
- Don't change whitespace or line wrapping in parts of a file you are not
editing for other reasons. Make sure your text editor is not configured to
automatically reformat the whole file when saving.
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 %}` renders in raw text and will 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/).
- A Netlify test runs for each PR that is against one of our long-lived
branches like `master` and the `vnext` branches, and deploys the result of
your PR to a staging site. The URL will be available at the bottom of the PR
in the **Conversation** view. Check the staging site for problems and fix them
if necessary. Reviewers will check the staging site too.
## Testing changes and practical guidance
If you can think of other ways we could streamline the review process, let us
know.
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/`).
## Style guide
### Creating tabs
Docker does not currently maintain a style guide. Use your best judgment, and
try to follow the example set by the existing documentation.
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
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab1">TAB 1 HEADER</a></li>
<li><a data-toggle="tab" data-target="#tab2">TAB 2 HEADER</a></li>
</ul>
<div class="tab-content">
<div id="tab1" class="tab-pane fade in active">TAB 1 CONTENT</div>
<div id="tab2" class="tab-pane fade">TAB 2 CONTENT</div>
</div>
```
For more info and a few more permutations, see [test.md](/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 `<script>` tags are at the very end of the page,
after all the content. Otherwise, the script may try to run before JQuery and
Bootstrap JS are loaded.
### Images
Don't forget to remove images that are no longer used. Keep the images sorted
in the local `images/` directory, with names that naturally group related images
together in alphabetical order. For example, use `settings-file-share.png`
and `settings-proxies.png` instead of `file-share-settings.png` and
`proxies-settings.png`.
You may also use numbers, especially in the case of a
sequence, for example, `run-only-the-images-you-trust-1.svg`,
`run-only-the-images-you-trust-2.png`, `run-only-the-images-you-trust-3.png`.
When applicable, capture windows rather than the rectangular regions. This
eliminates unpleasant background and saves the editors the need to crop images.
On Mac, capture windows without shadows. To do this, when you press
<kbd>Command-Shift-4</kbd>, press <kbd>Option</kbd> while clicking on the window. To disable shadows completely, run:
```bash
$ defaults write com.apple.screencapture disable-shadow -bool TRUE
$ killall SystemUIServer # restart it.
```
You can restore the shadows later using `-bool FALSE`.
To keep the Git repository light, _please_ compress the images
(losslessly). On Mac, you can use [ImageOptim](https://imageoptim.com) for
instance. Be sure to compress the images **before** adding them to the
repository. Compressing images after adding them to the repository actually worsens the impact on the Git repo (however, ut still optimizes the bandwidth during browsing).
### Style guide
Docker does not currently maintain a style guide. Follow the examples set by the existing documentation and use your best judgment.
## Build and preview the docs locally
On your local machine, clone the docs repository:
```bash
git clone --recursive https://github.com/docker/docker.github.io.git
cd docker.github.io
```
Then, build and run the documentation using [Docker Compose](https://docs.docker.com/compose/)
```bash
docker compose up -d --build
```
> You need Docker Compose to build and run the docs locally. Docker Compose is included with [Docker Desktop](https://docs.docker.com/desktop/).
> If you don't have Docker Desktop installed, follow the [instructions](https://docs.docker.com/compose/install/) to install Docker Compose.
When 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 docs, and updates the container with your changes:
```bash
docker compose up -d --build
```
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](https://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, set the `JEKYLL_ENV` environment variable when building the documentation:
```bash
JEKYLL_ENV=production docker compose up --build
```
When 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.
## Copyright and license
Copyright 2013-2021 Docker, inc, released under the Apache 2.0 license.

310
README.md
View File

@ -1,295 +1,47 @@
# Docs @ Docker
Welcome to the repo for our documentation. This is the source for
<img src="images/docker-docs.png" alt="Welcome to Docker Documentation" style="max-width: 50%;">
Welcome to the Docker Documentation repository. 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
Feel free to send us pull requests and file issues. Our docs are completely
open source and we deeply appreciate contributions from the Docker community!
- [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)
## Provide feedback
We’d love to hear your feedback. Please file documentation issues only in the
docs GitHub repository. You can file a new issue to suggest improvements or if
you see any errors in the existing documentation.
## Providing feedback
Before submitting a new issue, check whether the issue has already been
reported. You can join the discussion using an emoji, or by adding a comment to
an existing issue. If possible, we recommend that you suggest a fix to the issue
by creating a pull request.
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.
You can ask general questions and get community support through the [Docker
Community Slack](http://dockr.ly/slack). Personalized support is available
through the Docker Pro, Team, and Business subscriptions. See [Docker
Pricing](https://www.docker.com/pricing) for details.
**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 you have an idea for a new feature or behavior change in a specific aspect of
Docker, or have found a product bug, file that issue in the project's code
repository.
- 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.
We've made it really easy for you to file new issues.
- 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.
- Click **New issue** on the docs repository and fill in the details, or
- Click **Request docs changes** in the right column of every page on
docs.docker.com and add the details.
## Contributing
![Docs feedback on each page](/opensource/images/docs-site-feedback.png)
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.
## Contribute to Docker docs
>**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](https://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.
<!--
TODO re-enable auto-builds, or push master builds to Docker hub
## Read these docs offline
To read the docs offline, you can use either a standalone container or a swarm service.
To see all available tags, go to [Docker Hub](https://docs.docker.com/docker-hub/).
The following examples use the `latest` tag:
- Run a single container:
```bash
docker run -it -p 4000:4000 docs/docker.github.io:latest
```
- Run a swarm service:
```bash
docker service create -p 4000:4000 --name localdocs --replicas 1 docs/docker.github.io:latest
```
This example uses only a single replica, but you could run as many replicas as you'd like.
Either way, you can now access the docs at port 4000 on your Docker host.
-->
## 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 `<h1>` 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 `<h2>` 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 `<h3>` 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 `<meta name="robots" content="noindex"/>` 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
<ul class="nav nav-tabs">
<li class="active"><a data-toggle="tab" data-target="#tab1">TAB 1 HEADER</a></li>
<li><a data-toggle="tab" data-target="#tab2">TAB 2 HEADER</a></li>
</ul>
<div class="tab-content">
<div id="tab1" class="tab-pane fade in active">TAB 1 CONTENT</div>
<div id="tab2" class="tab-pane fade">TAB 2 CONTENT</div>
</div>
```
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 `<script>` tags are at the very end of the page,
after all the content. Otherwise the script may try to run before JQuery and
Bootstrap JS are loaded.
> **Note**: In general, this is a bad idea.
### Images
Don't forget to remove images that are no longer used. Keep the images sorted
in the local `images/` directory, with names that naturally group related images
together in alphabetical order. For instance prefer `settings-file-share.png`
and `settings-proxies.png` to `file-share-settings.png` and
`proxies-settings.png`. You may also use numbers, especially in the case of a
sequence, e.g., `run-only-the-images-you-trust-1.svg`
`run-only-the-images-you-trust-2.png` `run-only-the-images-you-trust-3.png`.
When applicable, capture windows rather than rectangular regions. This
eliminates unpleasant background and saves the editors the need to crop.
On Mac, capture windows without shadows. To this end, once you pressed
<kbd>Command-Shift-4</kbd>, press <kbd>Option</kbd> while clicking on the window. To disable
shadows once for all, run:
```bash
$ defaults write com.apple.screencapture disable-shadow -bool TRUE
$ killall SystemUIServer # restart it.
```
You can restore shadows later with `-bool FALSE`.
In order to keep the Git repository light, _please_ compress the images
(losslessly). On Mac you may use [ImageOptim](https://imageoptim.com) for
instance. Be sure to compress the images *before* adding them to the
repository, doing it afterwards actually worsens the impact on the Git repo (but
still optimizes the bandwidth during browsing).
We value your contribution. We'd like to make it as easy as possible to submit
your contributions to the Docker docs repository. Changes to the docs are
handled through pull requests against the `master` branch. To learn how to
contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
## Copyright and license

10
_data/toc.yaml
View File

@ -373,14 +373,8 @@ guides:
title: Use the VFS storage driver
- path: /get-started/resources/
title: "Educational resources"
- sectiontitle: Open source at Docker
section:
- path: /opensource/
title: Contribute to documentation
- path: /opensource/ways/
title: Other ways to contribute
- path: /docsarchive/
title: Documentation archive
- path: /opensource/
title: "Contribute to documentation"
reference:
- path: /reference/
title: Reference documentation

BIN
images/docker-docs.png Normal file
View File

Binary file not shown.
Side by Side

After

Width:  |  Height:  |  Size: 127 KiB

BIN
images/important-admonition-example.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 14 KiB

BIN
images/note-admonition-example.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 39 KiB

BIN
images/warning-admonition-example.png
View File

Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 25 KiB

BIN
opensource/images/docs-site-feedback.png
View File

Binary file not shown.
Side by Side Swipe Overlay

Before

Width:  |  Height:  |  Size: 248 KiB

After

Width:  |  Height:  |  Size: 479 KiB

97
opensource/index.md
View File

@ -1,6 +1,6 @@
---
description: Overview of contributing
keywords: open, source, contributing, overview
description: Contribute to Docker documentation
keywords: Docker documentation, contributing, overview
title: Contribute to documentation
redirect_from:
- /contributing/
@ -34,75 +34,46 @@ redirect_from:
Contributing to the Docker documentation can be a rewarding experience. When you
offer feedback, questions, edits, or new content, you help us, the projects you
work on, and the larger Docker community.
work on, and the larger Docker community. Feel free to create pull requests and
file issues. Our docs are completely open source and we deeply appreciate
contributions from the Docker community!
We welcome your participation to help make the documentation better!
## Provide feedback
> Looking for the open source Moby project?
>
> See [Looking for Moby?](#looking-for-moby) below.
We’d love to hear your feedback. Please file documentation issues only in the
docs GitHub repository. You can file a new issue to suggest improvements or if
you see any errors in the existing documentation.
## How to contribute to the docs
Before submitting a new issue, check whether the issue has already been
reported. You can join the discussion using an emoji, or by adding a comment to
an existing issue. If possible, we recommend that you suggest a fix to the issue
by creating a pull request.
The documentation for Docker is published at
[docs.docker.com](https://docs.docker.com/).
You can ask general questions and get community support through the [Docker
Community Slack](http://dockr.ly/slack). Personalized support is available
through the Docker Pro, Team, and Business subscriptions. See [Docker
Pricing](https://www.docker.com/pricing) for details.
There are many ways to contribute:
If you have an idea for a new feature or behavior change in a specific aspect of
Docker, or have found a product bug, file that issue in the project's code
repository.
- Edit, rate, or file an issue or question directly on the site by
using the links available on the right-side menu on every page
at [docs.docker.com](/).
We've made it really easy for you to file new issues.
![Docs feedback links](images/docs-site-feedback.png)
- Click **New issue** on the docs repository and fill in the details, or
- Click **Request docs changes** in the right column of every page on
docs.docker.com and add the details.
- File a documentation issue on GitHub at
[https://github.com/docker/docker.github.io/issues](https://github.com/docker/docker.github.io/issues).
![Docs feedback on each page](/opensource/images/docs-site-feedback.png)
This is similar to clicking **Request doc changes** on a published docs
page, but if you manually file an issue you need to fill in links to
the related pages.
## Contribute to Docker docs
- Fork the documentation, make changes or add new content on your local
branch, and submit a pull request (PR) to the master branch for the docs.
We value your contribution. We'd like to make it as easy as possible to submit
your contributions to the Docker docs repository. Changes to the docs are
handled through pull requests against the `master` branch. To learn how to
contribute, see
[CONTRIBUTING.md](https://github.com/docker/docker.github.io/blob/master/CONTRIBUTING.md).
This is the manual, more advanced version of clicking **Edit this page**
on a published docs page. Initiating a docs changes in a PR from your
own branch gives you more flexibility, as you can submit changes to
multiple pages or files under a single pull request, and even create
new topics.
## Resources and guidance
We are here to help. If you are interested in contributing, but don't feel ready
to dive in on more complex updates, we can help get you up and running.
You might start by using the right-side menus on published pages:
* Click **Request doc changes** on a page to automatically log an issue.
* Click **Edit this page** to make a change to content, which automatically creates a PR.
The issue and PR pages on GitHub give us a community space to discuss
things, and answer any questions you might have about the problem or topic you
are reporting on.
To learn more about working on the documentation, see these topics:
- [README on docker/docker.github.io](https://github.com/docker/docker.github.io/blob/master/README.md)
- [Docs Test page](../test.md) - This is on the
published site. It explains how to use Docs components, resources, and
formats, and gives us a way to test and demo them.
## Looking for meetups and Docker Community?
Go to the [Docker Community GitHub repository](https://github.com/docker/community/blob/master/README.md){:target="_blank" rel="noopener" class="_"}
for resources and information on the community.
The topics in this guide on [Other ways to contribute](/opensource/ways/)
provide some additional information, but the community
information you are looking for is probably available on the GitHub repository.
## Looking for Moby?
{% include content/moby.md %}
For a demo of the components, tags, Markdown syntax, styles, used in Docker
documentation, see
[test.md](https://github.com/docker/docker.github.io/blob/master/test.md).

113
test.md
View File

@ -37,7 +37,7 @@ topics).
By default, this is the highest heading included in the right navigation bar. To
include more heading levels, set `toc_min: 1` in the page's front-matter (as is
done on this `test.md` page). You can go all the way to 6, but if `toc_min` is
geater than `toc_max` then no headings are shown.
greater than `toc_max` then no headings are shown.
### Heading 3
@ -91,7 +91,6 @@ culpa qui officia deserunt mollit anim id est laborum.
### Links
- [a markdown link](https://docker.com/)
https://github.com/docker/docker.github.io/tree/master/docker-cloud/images
- [a markdown link that opens in a new window](https://docker.com/){: target="_blank" rel="noopener" class="_" }
(the `class="_"` trick prevents Atom from italicizing the whole rest of the file until it encounters another underscore.)
@ -113,7 +112,7 @@ https://github.com/docker/docker.github.io/tree/master/docker-cloud/images
- If you can't find a reference page in the `docker.github.io`
GitHub repository, but see it out on `docs.docker.com`, you can
surmise that it's probably auto-generated from the codebase.
(FYI, to view the markdown source for the file, just click
(FYI, to view the Markdown source for the file, just click
**Edit this page** on `docs.docker.com`. But don't use that URL in your docs.)
- Go to the file in a web browser, grab everything after the domain name
@ -125,6 +124,7 @@ https://github.com/docker/docker.github.io/tree/master/docker-cloud/images
{: id="custom-target-id"}
#### Using a custom target ID
This topic has a custom target ID above its heading that can be used to link to
it, in addition to, or instead of, the default concatenated heading style. The
format of this ID is `{: id="custom-target-id"}`.
@ -135,7 +135,7 @@ target.
An example of a custom target ID in the documentation is the topic on
[Compose file version 2 topic on CPU and other resources](compose/compose-file/compose-file-v2.md#cpu-and-other-resources).
It has a long heading that breaks the normal markdown linking mechanism,
It has a long heading that breaks the normal Markdown linking mechanism,
so we added a custom ID above the target heading.
### Images
@ -151,7 +151,7 @@ so we added a custom ID above the target heading.
- The same as above but using HTML: <img src="/images/banner_image_24512.png" alt="a pretty wide image using HTML"/>
[Some Bootstrap image classes](https://v4-alpha.getbootstrap.com/content/images/)
[Some Bootstrap image classes](https://getbootstrap.com/docs/3.4/css/#images){: target="_blank" rel="noopener" class="_" }
might be interesting. You can use them with Markdown or HTML images.
- An image using the Bootstrap "thumbnail" class: ![an image as a thumbnail](/images/footer_moby_icon.png){: class="img-thumbnail" }
@ -160,7 +160,16 @@ might be interesting. You can use them with Markdown or HTML images.
## Videos
You can add a link to a YouTube video like this:
To embed a YouTube video on a docs page, open the video on YouTube, click
**Share** > **Embed** and then copy the code displayed.
For example, the video embedded on the Get Started page has the following code:
```html
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/iqqDU2crIEQ?start=30" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
```
You can also add a link to a YouTube video like this:
[Docker 101: Introduction to Docker](https://www.youtube.com/watch?v=V9IJj4MzZBc "Docker 101: Introduction to Docker"){:target="_blank" rel="noopener" class="_"}
@ -205,7 +214,6 @@ For the overlay, you can use the play button at
| Thing 1 | Thing 2 |
| Thing 3 | Thing 4 |
## Tables
Some tables in markdown and html.
@ -216,7 +224,7 @@ Some tables in markdown and html.
| | Previous cell is empty. A `--flag` in mono text. |
| Read | Pull |
| Read/Write | Pull, push |
| Admin | All of the above, plus update description, create and delete |
| Admin | All of the above, plus update description, create, and delete |
The alignment of the cells in the source doesn't really matter. The ending pipe
character is optional (unless the last cell is supposed to be empty). The header
@ -318,12 +326,6 @@ You can nest captures within each other to represent more complex logic with Liq
- In-line variables set via `assign` or `capture` are available for the remainder of the page after they are set.
- If you include a file, you can pass key-value pairs at the same time. These are available as include variables, like `{{ include.toc_min }}`.
### Image formatting
This image was originally created on a white background and converted to a transparent background (or so it seems). In night-mode, the text still shows traces of the white and looks garbled. To fix this, we apply a white background inline with a class defined in _scss/_night-mode.css (and incorporated into style.css): `img.white-bg { background-color: white; }`.
![alt_text](https://github.com/docker/docker.github.io/blob/423f6d58b2f301d01163241099f0346f2ecf1019/machine/img/provision-use-case.png){: .white-bg}
## Bootstrap and CSS tricks
Here are cool components you can include on Docs pages using
@ -356,6 +358,7 @@ as an attribute in the HTML for the `<div>` so that Kramdown renders it.
</ul>
<div class="tab-content">
<div id="tab3" class="tab-pane fade in active" markdown="1">
#### A Markdown header
- list item 1
@ -363,6 +366,7 @@ as an attribute in the HTML for the `<div>` so that Kramdown renders it.
<hr>
</div>
<div id="tab4" class="tab-pane fade" markdown="1">
#### Another Markdown header
- list item 3
@ -402,7 +406,6 @@ And some content between the two sets, just for fun...
<div id="python-2" class="tab-pane fade in">Python content here<hr></div>
</div>
### Cards
In a Bootstrap row, your columns need to add up to 12. Here are three cards in
@ -460,30 +463,31 @@ to see another example.
$ docker run hello-world
Unable to find image 'hello-world:latest' locally
latest: Pulling from library/hello-world
b04784fba78d: Pull complete
Digest: sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f
2db29710123e: Pull complete
Digest: sha256:cc15c5b292d8525effc0f89cb299f1804f3a725c8d05e158653a563f15e4f685
Status: Downloaded newer image for hello-world:latest
Hello from Docker!
This message shows that your installation appears to be working correctly.
To generate this message, Docker took the following steps:
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
3. The Docker daemon created a new container from that image which runs the
executable that produces the output you are currently reading.
4. The Docker daemon streamed that output to the Docker client, which sent it
1. The Docker client contacted the Docker daemon.
2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
(amd64)
3. The Docker daemon created a new container from that image which runs the
4. The Docker daemon streamed that output to the Docker client, which sent it
to your terminal.
To try something more ambitious, you can run an Ubuntu container with:
$ docker run -it ubuntu bash
$ docker run -it ubuntu bash
Share images, automate workflows, and more with a free Docker ID:
https://hub.docker.com/
For more examples and ideas, visit:
https://docs.docker.com/engine/userguide/
https://docs.docker.com/get-started/
</code></pre>
</div>
<div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample2" style="cursor: pointer"> Another Sample <i class="chevron fa fa-fw"></i></div>
@ -578,15 +582,13 @@ or Bootstrap, make sure the `<script>` tags are at the very end of the page,
after all the content. Otherwise the script may try to run before JQuery and
Bootstrap JS are loaded.
> **Note**: In general, this is a bad idea.
## Admonitions (notes)
Current styles for admonitions in
[`_scss/_notes.scss`](https://github.com/docker/docker.github.io/blob/master/_scss/_notes.scss)
support these broad categories of admonitions:
- Notes (no Liquid tag required) (deprecated)
- Notes (no Liquid tag required)
- Important, which use the `{: .important}` tag
- Warning , which use the `{: .warning}` tag
@ -597,13 +599,11 @@ notes in your published documents are not adversely affected.
Examples are shown in the following sections.
### Note (Deprecated)
Notes are deprecated and should not longer be used. Use important or warning instead.
### Note
A standard note is formatted like this:
```
```markdown
> Handling transient errors
>
> Note the way the `get_hit_count` function is written. This basic retry
@ -615,38 +615,50 @@ A standard note is formatted like this:
> nodes.
```
It renders like this with a colored sidebar and icon:
A note renders as follows:
![note admonition example](/images/note-admonition-example.png)
> Handling transient errors
>
> Note the way the `get_hit_count` function is written. This basic retry
> loop lets us attempt our request multiple times if the redis service is
> not available. This is useful at startup while the application comes
> online, but also makes our application more resilient if the Redis
> service needs to be restarted anytime during the app's lifetime. In a
> cluster, this also helps handling momentary connection drops between
> nodes.
Notes were previously formatted like this:
Notes are also formatted like this:
```markdown
> **Note**
>
> This is another way to format a note.
```
> **Note**: This is a note using the old note style.
```
These will still render as a note with a colored sidebar to the left but no icon will be added.
### Important
Add the `important` class to your blockquotes if you want to tell users to be careful about something:
```
```markdown
> Pssst, wanna know something?
>
> You include a small description here telling users to be on the lookout
{: .important}
```
It renders like this with a colored sidebar and icon:
The 'important' class renders as follows:
![important admonition example](/images/important-admonition-example.png)
> **Important**
>
> Treat access tokens like your password and keep them secret. Store your
> tokens securely (for example, in a credential manager).
{: .important}
### Warning
Use the `warning` class to let people know this is dangerous or they should pay close attention to this part of the road before moving on:
```
```markdown
> Ouch, don't do that!
>
> Sticking your finger in an electrical outlet can result in an electric shock.
@ -655,9 +667,18 @@ Use the `warning` class to let people know this is dangerous or they should pay
{: .warning}
```
It will render like this with a colored sidebar and icon:
The 'warning' class renders as follows:
![warning admonition example](/images/warning-admonition-example.png)
> **Warning**
>
> Removing Volumes
>
> By default, named volumes in your compose file are NOT removed when running
> `docker-compose down`. If you want to remove the volumes, you will need to add
> the `--volumes` flag.
>
> The Docker Dashboard does _not_ remove volumes when you delete the app stack.
{: .warning}
## Upgrade CTA
@ -778,7 +799,7 @@ syntax for comments in JSON!
### Markdown
```md
```markdown
# Hello
```