mirror of
https://github.com/docker/docs.git
synced 2026-03-27 06:18:55 +07:00
Addition of a 'Contribute' section with our Style Guide (#15350)
* SG test.
* moved some content around
* editing
* broken links fix
* formatting changes
* fixes
* fixes
* edits after review
* fix broken links
* broken link fix
* a few more edits
* removed contributing page
* Revert "removed contributing page"
This reverts commit 5822cd516b.
* add redirect
This commit is contained in:
Allie Sadler
@@ -41,7 +41,7 @@ We've made it really easy for you to file new issues.
|
||||
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).
|
||||
contribute, see our [Contribute section](contribute/overview.md).
|
||||
|
||||
## Copyright and license
|
||||
|
||||
|
||||
@@ -15,6 +15,9 @@ horizontalnav:
|
||||
- title: Samples
|
||||
path: /samples/
|
||||
node: samples
|
||||
- title: Contribute
|
||||
path: /contribute/overview/
|
||||
node: contribute
|
||||
# TODO unify navbbar links: homepage currently has a custom "articles" link
|
||||
hide_home: true
|
||||
|
||||
@@ -1641,3 +1644,48 @@ manuals:
|
||||
title: Get Support
|
||||
- path: /release-lifecycle/
|
||||
title: Product release lifecycle
|
||||
contribute:
|
||||
- path: /contribute/overview/
|
||||
title: Contribute to Docker's docs
|
||||
- path: /contribute/contribute-guide/
|
||||
title: Contribution guidelines
|
||||
- sectiontitle: Style guide
|
||||
section:
|
||||
- path: /contribute/style/grammar/
|
||||
title: Grammar and style
|
||||
- path: /contribute/style/formatting/
|
||||
title: Formatting
|
||||
- path: /contribute/style/recommended-words/
|
||||
title: Recommended word list
|
||||
- path: /contribute/style/terminology/
|
||||
title: Docker terminology
|
||||
- path: /contribute/style/voice-tone/
|
||||
title: Voice and tone
|
||||
- path: /contribute/file-conventions/
|
||||
title: Source file conventions
|
||||
- sectiontitle: Useful components
|
||||
section:
|
||||
- path: /contribute/components/accordions/
|
||||
title: Accordions
|
||||
- path: /contribute/components/badges/
|
||||
title: Badges
|
||||
- path: /contribute/components/call-outs/
|
||||
title: Call outs
|
||||
- path: /contribute/components/cards/
|
||||
title: Cards
|
||||
- path: /contribute/components/images/
|
||||
title: Images
|
||||
- path: /contribute/components/links/
|
||||
title: Links
|
||||
- path: /contribute/components/lists/
|
||||
title: Lists
|
||||
- path: /contribute/components/tables/
|
||||
title: Tables
|
||||
- path: /contribute/components/tabs/
|
||||
title: Tabs
|
||||
- path: /contribute/components/tooltips/
|
||||
title: Tooltips
|
||||
- path: /contribute/components/videos/
|
||||
title: Videos
|
||||
- path: /contribute/checklist/
|
||||
title: Writing checklist
|
||||
|
||||
@@ -22,7 +22,8 @@
|
||||
{%- if entry.hide_home -%}{% continue %}{%- endif -%}
|
||||
<li{% if entry.node == "home" %} class=active{% endif %}><a href="{{ entry.path }}" id="{{ entry.node }}">{{ entry.title }}</a></li>
|
||||
{%- endfor -%}
|
||||
<li><a href="https://www.docker.com/blog/">Articles</a></li>
|
||||
<li><a href="https://www.docker.com/blog/">Articles</a></li>
|
||||
<li><a href="/contribute/overview/">Contribute</a></li>
|
||||
</ul>
|
||||
<ul class="nav navbar-nav navbar-right">
|
||||
<li>{% include theme-switch.html %}</li>
|
||||
|
||||
136
components.md
136
components.md
@@ -1,136 +0,0 @@
|
||||
---
|
||||
description: Components page
|
||||
title: Components
|
||||
sitemap: false
|
||||
---
|
||||
|
||||
For components and controls we are using [Bootstrap](https://getbootstrap.com)
|
||||
|
||||
### Tooltips
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="left" title="Tooltip on left">Tooltip on left</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="top" title="Tooltip on top">Tooltip on top</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">Tooltip on bottom</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="right" title="Tooltip on right">Tooltip on right</button>
|
||||
|
||||
|
||||
|
||||
#### HTML
|
||||
|
||||
```html
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="left" title="Tooltip on left">Tooltip on left</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="top" title="Tooltip on top">Tooltip on top</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">Tooltip on bottom</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="right" title="Tooltip on right">Tooltip on right</button>
|
||||
```
|
||||
|
||||
<hr>
|
||||
|
||||
<!-- ### Popover
|
||||
|
||||
<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>
|
||||
|
||||
<hr> -->
|
||||
|
||||
|
||||
### Accordion
|
||||
[Bootstrap docs](https://getbootstrap.com/docs/3.4/javascript/)
|
||||
<div class="panel-group" id="accordion" role="tablist" aria-multiselectable="true">
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading" role="tab" id="headingOne">
|
||||
<h5 class="panel-title">
|
||||
<a role="button" data-toggle="collapse" data-parent="#accordion" href="#collapseOne" aria-expanded="true" aria-controls="collapseOne">
|
||||
Collapsible Group Item #1
|
||||
</a>
|
||||
</h5>
|
||||
</div>
|
||||
<div id="collapseOne" class="panel-collapse collapse" role="tabpanel" aria-labelledby="headingOne">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading" role="tab" id="headingTwo">
|
||||
<h5 class="panel-title">
|
||||
<a class="collapsed" role="button" data-toggle="collapse" data-parent="#accordion" href="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
|
||||
Collapsible Group Item #2
|
||||
</a>
|
||||
</h5>
|
||||
</div>
|
||||
<div id="collapseTwo" class="panel-collapse collapse" role="tabpanel" aria-labelledby="headingTwo">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading" role="tab" id="headingThree">
|
||||
<h5 class="panel-title">
|
||||
<a class="collapsed" role="button" data-toggle="collapse" data-parent="#accordion" href="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
|
||||
Collapsible Group Item #3
|
||||
</a>
|
||||
</h5>
|
||||
</div>
|
||||
<div id="collapseThree" class="panel-collapse collapse" role="tabpanel" aria-labelledby="headingThree">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
#### HTML
|
||||
|
||||
```html
|
||||
<div class="panel-group" id="accordion" role="tablist" aria-multiselectable="true">
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading" role="tab" id="headingOne">
|
||||
<h5 class="panel-title">
|
||||
<a role="button" data-toggle="collapse" data-parent="#accordion" href="#collapseOne" aria-expanded="true" aria-controls="collapseOne">
|
||||
Collapsible Group Item #1
|
||||
</a>
|
||||
</h5>
|
||||
</div>
|
||||
<div id="collapseOne" class="panel-collapse collapse in" role="tabpanel" aria-labelledby="headingOne">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading" role="tab" id="headingTwo">
|
||||
<h5 class="panel-title">
|
||||
<a class="collapsed" role="button" data-toggle="collapse" data-parent="#accordion" href="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
|
||||
Collapsible Group Item #2
|
||||
</a>
|
||||
</h5>
|
||||
</div>
|
||||
<div id="collapseTwo" class="panel-collapse collapse" role="tabpanel" aria-labelledby="headingTwo">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading" role="tab" id="headingThree">
|
||||
<h5 class="panel-title">
|
||||
<a class="collapsed" role="button" data-toggle="collapse" data-parent="#accordion" href="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
|
||||
Collapsible Group Item #3
|
||||
</a>
|
||||
</h5>
|
||||
</div>
|
||||
<div id="collapseThree" class="panel-collapse collapse" role="tabpanel" aria-labelledby="headingThree">
|
||||
<div class="panel-body">
|
||||
Anim pariatur cliche reprehenderit, enim eiusmod high life accusamus terry richardson ad squid. 3 wolf moon officia aute, non cupidatat skateboard dolor brunch. Food truck quinoa nesciunt laborum eiusmod. Brunch 3 wolf moon tempor, sunt aliqua put a bird on it squid single-origin coffee nulla assumenda shoreditch et. Nihil anim keffiyeh helvetica, craft beer labore wes anderson cred nesciunt sapiente ea proident. Ad vegan excepteur butcher vice lomo. Leggings occaecat craft beer farm-to-table, raw denim aesthetic synth nesciunt you probably haven't heard of them accusamus labore sustainable VHS.
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
55
contribute/checklist.md
Normal file
55
contribute/checklist.md
Normal file
@@ -0,0 +1,55 @@
|
||||
---
|
||||
title: Writing checklist
|
||||
description: A helpful writing checklist when creating documentation
|
||||
keywords: checklist, documentation, style guide, contribute
|
||||
---
|
||||
|
||||
Use this checklist to communicate in a way that is clear, helpful, and consistent with the rest of Docker Docs.
|
||||
|
||||
##### Used active voice
|
||||
|
||||
Active voice is specific and removes ambiguity.
|
||||
|
||||
In active voice, the subject of the sentence (the customer or the system) does the action.
|
||||
|
||||
Sentences that use active voice are easier to read. Active voice makes it clear who has done what and to whom. Plus, active voice keeps sentences direct and more concise.
|
||||
|
||||
Helping verbs such as is, was, or would may indicate that you're writing in passive voice. And, if you can add the phrase 'by zombies' after the verb, you're writing in the passive voice.
|
||||
|
||||
|Correct| Incorrect|
|
||||
|:--|:--|
|
||||
|Increase productivity with Docker Desktop.| Productivity can be increased (by zombies) with Docker Desktop.|
|
||||
|If you remove items from a grid, charts automatically refresh to display the change. | If items are removed (by zombies) from a grid, charts automatically refresh to display the change.|
|
||||
|
||||
##### Written clear sentences that get to the point
|
||||
|
||||
Write short, concise sentences. Punchy sentences are faster to read and easier to understand.
|
||||
|
||||
##### Used subheadings and bulleted lists to break up the page
|
||||
|
||||
This helps ‘scanners’ find the information they need quickly and easily.
|
||||
|
||||
For more information, see the [formtatting](style/formatting.md#headings-and-subheadings) page, or see the [components](components/lists.md) for examples.
|
||||
|
||||
##### Started the title of your page with a verb
|
||||
|
||||
For example, 'Install Docker Desktop'.
|
||||
|
||||
##### Checked that the left-hand table of contents title in docs.docker.com, matches the title displayed on the page
|
||||
|
||||
##### Checked for broken links and images
|
||||
|
||||
Use relative links to link to other pages or images within the docker.github.io repository.
|
||||
|
||||
For more information, see the [formatting](style/formatting.md#links) page, or see the [components](components/links.md) for examples.
|
||||
|
||||
##### Checked that any redirects you may have added, work
|
||||
|
||||
For information on how to add redirects, see [Source file conventions](file-conventions.md#frontmatter).
|
||||
|
||||
##### Used bold on any UI elements you refer to in your content
|
||||
|
||||
##### Completed a final spelling, punctuation, and grammar check
|
||||
|
||||
For more in-depth information on our Style Guide, explore the [Grammar](style/grammar.md) or [Formatting](style/formatting.md) guides.
|
||||
|
||||
135
contribute/components/accordions.md
Normal file
135
contribute/components/accordions.md
Normal file
@@ -0,0 +1,135 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Accordions
|
||||
toc_max: 3
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
<i class="fa fa-caret-down" aria-hidden="true"></i> (fa-caret-down) and
|
||||
<i class="fa fa-caret-up" aria-hidden="true"></i> (fa-caret-up).
|
||||
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample1" style="cursor: pointer">
|
||||
Docker hello-world example
|
||||
<i class="chevron fa fa-fw"></i></div>
|
||||
<div class="collapse block" id="collapseSample1">
|
||||
<pre>
|
||||
<code>
|
||||
$ docker run hello-world
|
||||
Unable to find image 'hello-world:latest' locally
|
||||
latest: Pulling from library/hello-world
|
||||
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.
|
||||
(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
|
||||
|
||||
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/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>
|
||||
<div class="collapse block" id="collapseSample2">
|
||||
<p>
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
|
||||
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
|
||||
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
|
||||
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
|
||||
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
|
||||
culpa qui officia deserunt mollit anim id est laborum.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
## HTML
|
||||
|
||||
```
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample1" style="cursor: pointer">
|
||||
Docker hello-world example
|
||||
<i class="chevron fa fa-fw"></i></div>
|
||||
<div class="collapse block" id="collapseSample1">
|
||||
<pre>
|
||||
<code>
|
||||
$ docker run hello-world
|
||||
Unable to find image 'hello-world:latest' locally
|
||||
latest: Pulling from library/hello-world
|
||||
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.
|
||||
(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
|
||||
|
||||
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/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>
|
||||
<div class="collapse block" id="collapseSample2">
|
||||
<p>
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
|
||||
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
|
||||
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
|
||||
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
|
||||
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
|
||||
culpa qui officia deserunt mollit anim id est laborum.</p>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
This implementation makes use of the `.panel-heading` classes in
|
||||
`_utilities.scss.md`,
|
||||
along with [FontAwesome icons](http://fontawesome.io/cheatsheet/){: target="_blank" rel="noopener" class="_" }
|
||||
|
||||
> Note
|
||||
>
|
||||
>Make sure `data-target`'s and `id`'s match, and are unique.
|
||||
>
|
||||
>For each drop-down, the value for `data-target` and
|
||||
`collapse` `id` must match, and id's must be unique per page. In this example,
|
||||
we name these `collapseSample1` and `collapseSample2`.
|
||||
|
||||
Adding `block` to the `div` class `collapse` gives you some padding around the
|
||||
sample content. This works nicely for standard text. If you have a code sample,
|
||||
the padding renders as white space around the code block grey background.
|
||||
|
||||
The `style="cursor: pointer"` tag enables the expand/collapse functionality to
|
||||
work on mobile. (You can use the [Xcode iPhone simulator](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/iOS_Simulator_Guide/GettingStartedwithiOSSimulator/GettingStartedwithiOSSimulator.html#//apple_ref/doc/uid/TP40012848-CH5-SW4){: target="_blank" rel="noopener" class="_" } to test on mobile.)
|
||||
28
contribute/components/badges.md
Normal file
28
contribute/components/badges.md
Normal file
@@ -0,0 +1,28 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Badges
|
||||
toc_max: 3
|
||||
---
|
||||
### Examples
|
||||
|
||||
<span class="badge badge-info">badges</span>
|
||||
<span class="badge badge-warning">yellow badges</span>
|
||||
<span class="badge badge-danger">red badges</span>
|
||||
|
||||
You can make a badge a link.
|
||||
|
||||
<a href="/contribute/overview/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" >Badge with link</span></a>
|
||||
|
||||
### HTML
|
||||
|
||||
|
||||
```html
|
||||
<span class="badge badge-info">badges</span>.
|
||||
|
||||
<span class="badge badge-warning">yellow badges</span>
|
||||
|
||||
<span class="badge badge-danger">red badges</span>
|
||||
|
||||
<a href="/contribute/overview/" target="_blank" rel="noopener" class="_"><span class="badge badge-info">Test</span></a>
|
||||
```
|
||||
|
||||
72
contribute/components/call-outs.md
Normal file
72
contribute/components/call-outs.md
Normal file
@@ -0,0 +1,72 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Call outs
|
||||
toc_max: 3
|
||||
---
|
||||
|
||||
We support these broad categories of call outs:
|
||||
|
||||
- Notes (no Liquid tag required)
|
||||
- Important, which use the `{: .important}` tag
|
||||
- Warning , which use the `{: .warning}` tag
|
||||
|
||||
## Examples
|
||||
|
||||
> **Note**
|
||||
>
|
||||
> 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.
|
||||
|
||||
> **Important**
|
||||
>
|
||||
> Treat access tokens like your password and keep them secret. Store your
|
||||
> tokens securely (for example, in a credential manager).
|
||||
{: .important}
|
||||
|
||||
|
||||
> **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}
|
||||
|
||||
## HTML
|
||||
|
||||
```html
|
||||
> **Note**
|
||||
>
|
||||
> 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.
|
||||
|
||||
> **Important**
|
||||
>
|
||||
> Treat access tokens like your password and keep them secret. Store your
|
||||
> tokens securely (for example, in a credential manager).
|
||||
{: .important}
|
||||
|
||||
> **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}
|
||||
```
|
||||
31
contribute/components/cards.md
Normal file
31
contribute/components/cards.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Cards
|
||||
toc_max: 3
|
||||
---
|
||||
## Example
|
||||
|
||||
In a Bootstrap row, your columns need to add up to 12. Here are three cards in
|
||||
a row, each of which takes up 1/3 (4/12) of the row.
|
||||
|
||||
<div class="row">
|
||||
<div class="panel col-xs-12 col-md-4">This takes up 1/3 of the row unless the screen is small,
|
||||
then it takes up the whole row.</div>
|
||||
<div class="panel col-xs-12 col-md-4">This takes up 1/3 of the row unless the screen is small,
|
||||
then it takes up the whole row.</div>
|
||||
<div class="panel col-xs-12 col-md-4">This takes up 1/3 of the row unless the screen is small,
|
||||
then it takes up the whole row.</div>
|
||||
</div>
|
||||
|
||||
## HTML
|
||||
|
||||
```html
|
||||
<div class="row">
|
||||
<div class="panel col-xs-12 col-md-4">This takes up 1/3 of the row unless the screen is small,
|
||||
then it takes up the whole row.</div>
|
||||
<div class="panel col-xs-12 col-md-4">This takes up 1/3 of the row unless the screen is small,
|
||||
then it takes up the whole row.</div>
|
||||
<div class="panel col-xs-12 col-md-4">This takes up 1/3 of the row unless the screen is small,
|
||||
then it takes up the whole row.</div>
|
||||
</div>
|
||||
```
|
||||
165
contribute/components/code-blocks.md
Normal file
165
contribute/components/code-blocks.md
Normal file
@@ -0,0 +1,165 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Code blocks
|
||||
toc_max: 3
|
||||
---
|
||||
|
||||
# Code blocks
|
||||
|
||||
Rouge provides lots of different code block "hints". If you leave off the hint,
|
||||
it tries to guess and sometimes gets it wrong. These are just a few hints that
|
||||
we use often.
|
||||
|
||||
#### Raw, no highlighting
|
||||
|
||||
The raw markup is needed to keep Liquid from interpreting the things with double
|
||||
braces as templating language.
|
||||
|
||||
{% raw %}
|
||||
```none
|
||||
none with raw
|
||||
$ some command with {{double braces}}
|
||||
$ some other command
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
#### Raw, Bash
|
||||
|
||||
{% raw %}
|
||||
```bash
|
||||
bash with raw
|
||||
$ some command with {{double braces}}
|
||||
$ some other command
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
#### Bash
|
||||
|
||||
```bash
|
||||
$ echo "deb https://packages.docker.com/1.12/apt/repo ubuntu-trusty main" | sudo tee /etc/apt/sources.list.d/docker.list
|
||||
```
|
||||
|
||||
#### Go
|
||||
|
||||
```go
|
||||
incoming := map[string]interface{}{
|
||||
"asdf": 1,
|
||||
"qwer": []interface{}{},
|
||||
"zxcv": []interface{}{
|
||||
map[string]interface{}{},
|
||||
true,
|
||||
int(1e9),
|
||||
"tyui",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
#### PowerShell
|
||||
|
||||
```powershell
|
||||
Install-Module DockerMsftProvider -Force
|
||||
Install-Package Docker -ProviderName DockerMsftProvider -Force
|
||||
[System.Environment]::SetEnvironmentVariable("DOCKER_FIPS", "1", "Machine")
|
||||
Expand-Archive docker-18.09.1.zip -DestinationPath $Env:ProgramFiles -Force
|
||||
```
|
||||
|
||||
#### Python
|
||||
|
||||
```python
|
||||
return html.format(name=os.getenv('NAME', "world"), hostname=socket.gethostname(), visits=visits)
|
||||
```
|
||||
|
||||
#### Ruby
|
||||
|
||||
```ruby
|
||||
docker_service 'default' do
|
||||
action [:create, :start]
|
||||
end
|
||||
```
|
||||
|
||||
#### JSON
|
||||
|
||||
```json
|
||||
"server": {
|
||||
"http_addr": ":4443",
|
||||
"tls_key_file": "./fixtures/notary-server.key",
|
||||
"tls_cert_file": "./fixtures/notary-server.crt"
|
||||
}
|
||||
```
|
||||
|
||||
#### HTML
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Welcome to nginx!</title>
|
||||
</head>
|
||||
</html>
|
||||
```
|
||||
|
||||
#### Markdown
|
||||
|
||||
```markdown
|
||||
# Hello
|
||||
```
|
||||
|
||||
#### ini
|
||||
|
||||
```ini
|
||||
[supervisord]
|
||||
nodaemon=true
|
||||
|
||||
[program:sshd]
|
||||
command=/usr/sbin/sshd -D
|
||||
```
|
||||
|
||||
#### Dockerfile
|
||||
|
||||
```dockerfile
|
||||
# syntax=docker/dockerfile:1
|
||||
|
||||
#
|
||||
# example Dockerfile for https://docs.docker.com/examples/postgresql_service/
|
||||
#
|
||||
|
||||
FROM ubuntu
|
||||
|
||||
RUN apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys B97B0AFCAA1A47F044F244A07FCC7D46ACCC4CF8
|
||||
|
||||
RUN echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main" > /etc/apt/sources.list.d/pgdg.list
|
||||
|
||||
RUN apt-get update && apt-get install -y python-software-properties software-properties-common postgresql-9.3 postgresql-client-9.3 postgresql-contrib-9.3
|
||||
|
||||
# Note: The official Debian and Ubuntu images automatically ``apt-get clean``
|
||||
# after each ``apt-get``
|
||||
|
||||
USER postgres
|
||||
|
||||
RUN /etc/init.d/postgresql start &&\
|
||||
psql --command "CREATE USER docker WITH SUPERUSER PASSWORD 'docker';" &&\
|
||||
createdb -O docker docker
|
||||
|
||||
RUN echo "host all all 0.0.0.0/0 md5" >> /etc/postgresql/9.3/main/pg_hba.conf
|
||||
|
||||
RUN echo "listen_addresses='*'" >> /etc/postgresql/9.3/main/postgresql.conf
|
||||
|
||||
EXPOSE 5432
|
||||
|
||||
VOLUME ["/etc/postgresql", "/var/log/postgresql", "/var/lib/postgresql"]
|
||||
|
||||
CMD ["/usr/lib/postgresql/9.3/bin/postgres", "-D", "/var/lib/postgresql/9.3/main", "-c", "config_file=/etc/postgresql/9.3/main/postgresql.conf"]
|
||||
```
|
||||
|
||||
#### YAML
|
||||
|
||||
```yaml
|
||||
authorizedkeys:
|
||||
image: dockercloud/authorizedkeys
|
||||
deployment_strategy: every_node
|
||||
autodestroy: always
|
||||
environment:
|
||||
- AUTHORIZED_KEYS=ssh-rsa AAAAB3Nsomelongsshkeystringhereu9UzQbVKy9o00NqXa5jkmZ9Yd0BJBjFmb3WwUR8sJWZVTPFL
|
||||
volumes:
|
||||
/root:/user:rw
|
||||
```
|
||||
35
contribute/components/images.md
Normal file
35
contribute/components/images.md
Normal file
@@ -0,0 +1,35 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Images
|
||||
toc_max: 3
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
- A small image: 
|
||||
|
||||
- A small image that is a link. The extra newline here makes it not show inline:
|
||||
|
||||
[](https://www.docker.com/)
|
||||
|
||||
- Set the size of an image: {:width="750px"}
|
||||
|
||||
- A big wide image: 
|
||||
|
||||
- The same as above but using HTML: <img src="/images/banner_image_24512.png" alt="a wide image using HTML"/>
|
||||
|
||||
## HTML and Markdown
|
||||
|
||||
```html
|
||||
- A small image: 
|
||||
|
||||
- A small image that is a link. The extra newline here makes it not show inline:
|
||||
|
||||
[](https://www.docker.com/)
|
||||
|
||||
- Set the size of an image: {:width="750px"}
|
||||
|
||||
- A big wide image: 
|
||||
|
||||
- The same as above but using HTML: <img src="/images/banner_image_24512.png" alt="a wide image using HTML"/>
|
||||
```
|
||||
38
contribute/components/links.md
Normal file
38
contribute/components/links.md
Normal file
@@ -0,0 +1,38 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Links
|
||||
toc_max: 3
|
||||
---
|
||||
## Examples
|
||||
|
||||
It is best practice if [a link opens in a new window](https://docker.com/){: target="_blank" rel="noopener" class="_" }
|
||||
|
||||
#### Links to auto-generated content
|
||||
|
||||
An example of a link to an auto-generated reference page that we pull in during docs builds:
|
||||
[/engine/reference/builder/#env](/engine/reference/builder/#env).
|
||||
|
||||
- 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
|
||||
**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
|
||||
from the URL, and use that as the link in your docs file.
|
||||
|
||||
- Keep in mind that this link doesn't resolve until you merge the PR and
|
||||
your docs are published on [docs.docker.com](/).
|
||||
|
||||
## HTML
|
||||
|
||||
```html
|
||||
|
||||
It is best practice if [a link opens in a new window](https://docker.com/){: target="_blank" rel="noopener" class="_" }
|
||||
|
||||
You can also have [a markdown link to a custom target ID](#formatting-examples)
|
||||
|
||||
An example of a link to an auto-generated reference page that we pull in during docs builds:
|
||||
[/engine/reference/builder/#env](/engine/reference/builder/#env).
|
||||
|
||||
```
|
||||
75
contribute/components/lists.md
Normal file
75
contribute/components/lists.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Lists
|
||||
toc_max: 3
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
- Bullet list item 1
|
||||
- Bullet list item 2
|
||||
* Bullet list item 3
|
||||
|
||||
1. Numbered list item 1. Two spaces between the period and the first letter
|
||||
helps with alignment.
|
||||
|
||||
2. Numbered list item 2. Let's put a note in it.
|
||||
|
||||
>**Note**: We did it!
|
||||
|
||||
3. Numbered list item 3 with a code block in it. You need the blank line before
|
||||
the code block happens.
|
||||
|
||||
```bash
|
||||
$ docker run hello-world
|
||||
```
|
||||
|
||||
4. Numbered list item 4 with a bullet list inside it and a numbered list
|
||||
inside that.
|
||||
|
||||
- Sub-item 1
|
||||
- Sub-item 2
|
||||
1. Sub-sub-item 1
|
||||
2. Sub-sub-item-2 with a table inside it because we like to party!
|
||||
Indentation is super important.
|
||||
|
||||
|Header 1 | Header 2 |
|
||||
|---------|----------|
|
||||
| Thing 1 | Thing 2 |
|
||||
| Thing 3 | Thing 4 |
|
||||
|
||||
## Markdown
|
||||
|
||||
```html
|
||||
- Bullet list item 1
|
||||
- Bullet list item 2
|
||||
* Bullet list item 3
|
||||
|
||||
1. Numbered list item 1. Two spaces between the period and the first letter
|
||||
helps with alignment.
|
||||
|
||||
2. Numbered list item 2. Let's put a note in it.
|
||||
|
||||
>**Note**: We did it!
|
||||
|
||||
3. Numbered list item 3 with a code block in it. You need the blank line before
|
||||
the code block happens.
|
||||
|
||||
```bash
|
||||
$ docker run hello-world
|
||||
```
|
||||
|
||||
4. Numbered list item 4 with a bullet list inside it and a numbered list
|
||||
inside that.
|
||||
|
||||
- Sub-item 1
|
||||
- Sub-item 2
|
||||
1. Sub-sub-item 1
|
||||
2. Sub-sub-item-2 with a table inside it.
|
||||
Indentation is super important.
|
||||
|
||||
|Header 1 | Header 2 |
|
||||
|---------|----------|
|
||||
| Thing 1 | Thing 2 |
|
||||
| Thing 3 | Thing 4 |
|
||||
```
|
||||
31
contribute/components/tables.md
Normal file
31
contribute/components/tables.md
Normal file
@@ -0,0 +1,31 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Tables
|
||||
toc_max: 3
|
||||
---
|
||||
|
||||
## Example
|
||||
|
||||
| Permission level | Access |
|
||||
|:-------------------------------------------------------------------------|:-------------------------------------------------------------|
|
||||
| **Bold** or _italic_ within a table cell. Next cell is empty on purpose. | |
|
||||
| | 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 |
|
||||
|
||||
## Markdown
|
||||
|
||||
```
|
||||
| Permission level | Access |
|
||||
|:-------------------------------------------------------------------------|:-------------------------------------------------------------|
|
||||
| **Bold** or _italic_ within a table cell. Next cell is empty on purpose. | |
|
||||
| | 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 |
|
||||
```
|
||||
|
||||
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
|
||||
row and separator row are optional.
|
||||
107
contribute/components/tabs.md
Normal file
107
contribute/components/tabs.md
Normal file
@@ -0,0 +1,107 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Tabs
|
||||
toc_max: 3
|
||||
---
|
||||
|
||||
## Examples
|
||||
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#tab3">TAB 1 HEADER</a></li>
|
||||
<li><a data-toggle="tab" data-target="#tab4">TAB 2 HEADER</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="tab3" class="tab-pane fade in active" markdown="1">
|
||||
|
||||
##### A Markdown header
|
||||
|
||||
- list item 1
|
||||
- list item 2
|
||||
<hr>
|
||||
</div>
|
||||
<div id="tab4" class="tab-pane fade" markdown="1">
|
||||
|
||||
##### Another Markdown header
|
||||
|
||||
- list item 3
|
||||
- list item 4
|
||||
<hr>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
#### Synchronizing multiple tab groups
|
||||
|
||||
Consider an example where you have something like one tab per language, and
|
||||
you have multiple tab sets like this on a page. You might want them to all
|
||||
toggle together. In the following example, selecting `Go` or `Python` in one tab set toggles the
|
||||
other tab set to match. We have Javascript that loads on every page that lets you
|
||||
do this by setting the `data-group` attributes to be the same. The
|
||||
`data-target` attributes still need to point to unique div IDs.
|
||||
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#go" data-group="go">Go</a></li>
|
||||
<li><a data-toggle="tab" data-target="#python" data-group="python">Python</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="go" class="tab-pane fade in active">Go content here<hr></div>
|
||||
<div id="python" class="tab-pane fade in">Python content here<hr></div>
|
||||
</div>
|
||||
|
||||
And some content between the two sets, just for fun...
|
||||
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#go-2" data-group="go">Go</a></li>
|
||||
<li><a data-toggle="tab" data-target="#python-2" data-group="python">Python</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="go-2" class="tab-pane fade in active">Go content here<hr></div>
|
||||
<div id="python-2" class="tab-pane fade in">Python content here<hr></div>
|
||||
</div>
|
||||
|
||||
## HTML
|
||||
|
||||
```html
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#tab3">TAB 1 HEADER</a></li>
|
||||
<li><a data-toggle="tab" data-target="#tab4">TAB 2 HEADER</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="tab3" class="tab-pane fade in active" markdown="1">
|
||||
|
||||
##### A Markdown header
|
||||
|
||||
- list item 1
|
||||
- list item 2
|
||||
<hr>
|
||||
</div>
|
||||
<div id="tab4" class="tab-pane fade" markdown="1">
|
||||
|
||||
##### Another Markdown header
|
||||
|
||||
- list item 3
|
||||
- list item 4
|
||||
<hr>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
```html
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#go" data-group="go">Go</a></li>
|
||||
<li><a data-toggle="tab" data-target="#python" data-group="python">Python</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="go" class="tab-pane fade in active">Go content here<hr></div>
|
||||
<div id="python" class="tab-pane fade in">Python content here<hr></div>
|
||||
</div>
|
||||
|
||||
And some content between the two sets, just for fun...
|
||||
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#go-2" data-group="go">Go</a></li>
|
||||
<li><a data-toggle="tab" data-target="#python-2" data-group="python">Python</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="go-2" class="tab-pane fade in active">Go content here<hr></div>
|
||||
<div id="python-2" class="tab-pane fade in">Python content here<hr></div>
|
||||
```
|
||||
39
contribute/components/tooltips.md
Normal file
39
contribute/components/tooltips.md
Normal file
@@ -0,0 +1,39 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Tooltips
|
||||
toc_max: 3
|
||||
---
|
||||
Tooltips are not visible on mobile devices or touchscreens, so don't rely on them as the
|
||||
only way to communicate important info.
|
||||
|
||||
## Examples
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="left" title="Tooltip on left">Tooltip on left</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="top" title="Tooltip on top">Tooltip on top</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">Tooltip on bottom</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="right" title="Tooltip on right">Tooltip on right</button>
|
||||
|
||||
This is a paragraph that has a tooltip. We position it to the left so it doesn't align with the middle top of the paragraph (that looks weird).
|
||||
{:data-toggle="tooltip" data-placement="left" title="Markdown tooltip example"}
|
||||
|
||||
<a href="/contribute/components/tooltips" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="Open the test page (in a new window)">Test</span></a>
|
||||
|
||||
## HTML
|
||||
|
||||
```html
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="left" title="Tooltip on left">Tooltip on left</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="top" title="Tooltip on top">Tooltip on top</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">Tooltip on bottom</button>
|
||||
|
||||
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="right" title="Tooltip on right">Tooltip on right</button>
|
||||
|
||||
This is a paragraph that has a tooltip. We position it to the left so it doesn't align with the middle top of the paragraph (that looks weird).
|
||||
{:data-toggle="tooltip" data-placement="left" title="Markdown tooltip example"}
|
||||
|
||||
<a href="/contribute/components" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="Open the test page (in a new window)">Test</span></a>
|
||||
```
|
||||
14
contribute/components/videos.md
Normal file
14
contribute/components/videos.md
Normal file
@@ -0,0 +1,14 @@
|
||||
---
|
||||
description: components and formatting examples used in Docker's docs
|
||||
title: Videos
|
||||
toc_max: 3
|
||||
---
|
||||
|
||||
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>
|
||||
```
|
||||
124
contribute/contribute-guide.md
Normal file
124
contribute/contribute-guide.md
Normal file
@@ -0,0 +1,124 @@
|
||||
---
|
||||
title: Contributing guidelines
|
||||
description: Guidelines for contributing to Docker's docs
|
||||
keywords: contribute, guide, style guide
|
||||
---
|
||||
|
||||
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:
|
||||
|
||||
- Conceptual and task-based information
|
||||
- Restructuring / rewriting
|
||||
- Doc bug fixing
|
||||
- Fixing typos, broken links, and any grammar errors
|
||||
|
||||
There are two ways to contribute a pull request to the docs repository:
|
||||
|
||||
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 the Usefule components section.
|
||||
|
||||
### 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`. Pull requests against these files will be rejected.
|
||||
|
||||
## 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.
|
||||
|
||||
## Collaborate on a pull request
|
||||
|
||||
Unless the PR author specifically disables it, you can push commits into another
|
||||
contributor's PR. You can do it from the command line by adding and fetching
|
||||
their remote, checking out their branch, and adding commits to it. Even easier,
|
||||
you can add commits from the Github web UI, by clicking the pencil icon for a
|
||||
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 into the `master` branch. In some scenarios where a squash and merge isn't appropriate, all commits are kept separate when merging.
|
||||
|
||||
## Per-PR staging on GitHub
|
||||
|
||||
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.
|
||||
|
||||
## 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-2022 Docker, inc, released under the Apache 2.0 license.
|
||||
63
contribute/file-conventions.md
Normal file
63
contribute/file-conventions.md
Normal file
@@ -0,0 +1,63 @@
|
||||
---
|
||||
title: Source file conventions
|
||||
description: How new .md files should be formatted
|
||||
keywords: source file, contribute, style guide
|
||||
---
|
||||
|
||||
## File name
|
||||
|
||||
When you create a new .md file for new content, make sure:
|
||||
- File names are as short as possible
|
||||
- Try to keep the file name to one word or two words
|
||||
- Use a dash to separate words. For example:
|
||||
- `add-seats.md` and `remove-seats.md`.
|
||||
- `multiplatform-images` preferred to `multi-platform-images`.
|
||||
|
||||
## Frontmatter
|
||||
|
||||
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. It’s not rendered on the page. |
|
||||
| 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
|
||||
---
|
||||
```
|
||||
|
||||
## Body
|
||||
|
||||
The body of the page (with the exception of keywords) starts after the frontmatter
|
||||
|
||||
### Text length
|
||||
|
||||
Splitting long lines (preferably up to 80 characters) can make it easier to provide feedback on small chunks of text.
|
||||
80
contribute/overview.md
Normal file
80
contribute/overview.md
Normal file
@@ -0,0 +1,80 @@
|
||||
---
|
||||
title: Contribute to Docker's docs
|
||||
toc_max: 1
|
||||
redirect_from:
|
||||
- /CONTRIBUTING/
|
||||
---
|
||||
|
||||
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 following sections guide you through the process of contributing to Docker documentation.
|
||||
|
||||
<div class="component-container">
|
||||
<!--start row-->
|
||||
<div class="row">
|
||||
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||
<div class="component">
|
||||
<div class="component-icon">
|
||||
<img src="/images/contribute.svg" alt="Docker Desktop for Mac" width="45" height="45">
|
||||
</div>
|
||||
<h2 id="docker-for-mac"><a href="/contribute/contribute-guide/">Contribution guidelines </a></h2>
|
||||
<p>Learn about the process of contributing to our docs. </p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||
<div class="component">
|
||||
<div class="component-icon">
|
||||
<img src="/images/grammar.svg" alt="Docker Desktop for Mac" width="45" height="45">
|
||||
</div>
|
||||
<h2 id="docker-for-mac"><a href="/contribute/style/grammar/">Grammar guide</a></h2>
|
||||
<p>Explore Docker's grammar guide</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||
<div class="component">
|
||||
<div class="component-icon">
|
||||
<img src="/images/formatting.svg" alt="Docker for Linux" width="45" height="45">
|
||||
</div>
|
||||
<h2 id="docker-for-linux"><a href="/contribute/style/formatting/">Formatting guidelines</a></h2>
|
||||
<p>Format your content to match the rest of our documentation.</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
<!--start row-->
|
||||
<div class="row">
|
||||
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||
<div class="component">
|
||||
<div class="component-icon">
|
||||
<img src="/images/check.svg" alt="Docker Desktop for Mac" width="45" height="45">
|
||||
</div>
|
||||
<h2 id="docker-for-linux"><a href="/contribute/style/recommended-words/">Recommended word list</a></h2>
|
||||
<p>Choose the right words for you content</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||
<div class="component">
|
||||
<div class="component-icon">
|
||||
<img src="/images/new-page.svg" alt="Docker Desktop for Mac" width="45" height="45">
|
||||
</div>
|
||||
<h2 id="docker-for-windows/install/"><a href="/contribute/file-conventions/">Source file conventions</a></h2>
|
||||
<p>Guidelines for creating a new page</p>
|
||||
</div>
|
||||
</div>
|
||||
<div class="col-xs-12 col-sm-12 col-md-12 col-lg-4 block">
|
||||
<div class="component">
|
||||
<div class="component-icon">
|
||||
<img src="/images/terminology.svg" alt="Docker Desktop for Windows" width="45" height="45">
|
||||
</div>
|
||||
<h2 id="docker-for-windows/install/"><a href="/contribute/style/terminology/">Docker terminology</a></h2>
|
||||
<p>Explore commonly-used Docker terms</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
### Additional resources
|
||||
|
||||
We also provide:
|
||||
|
||||
- A section of useful components you can add to your documentation. For components and controls we are using [Bootstrap](https://getbootstrap.com)
|
||||
- Information on Docker's [tone and voice](style/voice-tone.md).
|
||||
- A [writing checklist](checklist.md) to help you when you're contributing to Docker's documenation.
|
||||
136
contribute/style/formatting.md
Normal file
136
contribute/style/formatting.md
Normal file
@@ -0,0 +1,136 @@
|
||||
---
|
||||
title: Formatting guide
|
||||
description: Formatting guidelines for technical documentation
|
||||
keywords: formatting, style guide, contribute
|
||||
toc_max: 2
|
||||
---
|
||||
|
||||
## Headings and subheadings
|
||||
|
||||
Readers pay fractionally more attention to headings, bulleted lists and links, so it's important to ensure the first two to three words in those items "front load" information as much as possible.
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Headings and subheadings should let the reader know what they will find on the page.
|
||||
- They should describe succinctly and accurately what the content is about.
|
||||
- Headings should be short (no more than eight words), to the point and written in plain, active language.
|
||||
- You should avoid puns, teasers and cultural references.
|
||||
- Skip leading articles (a, the, etc.)
|
||||
|
||||
## Page title
|
||||
|
||||
Page titles should be action orientated. For example:
|
||||
- _Enable SCIM_
|
||||
- _Install Docker Desktop_
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Make sure the title of your page and the TOC entry matches
|
||||
- If you want to use a ‘:’ in a page title in the table of contents (_toc.yaml), you must wrap the entire title in “” to avoid breaking the build.
|
||||
|
||||
## Images
|
||||
|
||||
Images, including screenshots, can help a reader better understand a concept. However, they should be used sparingly as they tend to go out-of-date quickly.
|
||||
|
||||
### Best practice:
|
||||
- When you take screenshots:
|
||||
- Don’t use lorem ipsum text. Try to replicate how the feature would be used in a real-world scenario, and use realistic text.
|
||||
- Capture only the relevant UI. Don’t include unnecessary white space or areas of the UI that don’t help illustrate the point.
|
||||
- Keep it small. If you don’t need to show the full width of the screen, don’t.
|
||||
- Review how the image renders on the page. Make sure the image isn’t blurry or overwhelming.
|
||||
- Be consistent. Coordinate screenshots with the other screenshots already on a documentation page for a consistent reading experience.
|
||||
- To keep the Git repository light, compress the images (losslessly). 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, it still optimizes the bandwidth during browsing).
|
||||
- Don't forget to remove images from the repo that are no longer used.
|
||||
|
||||
For information on how to add images to your content, see [Useful component and formatting examples](../components/images.md).
|
||||
|
||||
## Links
|
||||
|
||||
Be careful not to create too many links, especially within body copy. Excess links can be distracting or send readers away from the current page.
|
||||
|
||||
When people follow links, they can often lose their train of thought and fail to return to the original page, despite not having absorbed all the information it contains.
|
||||
|
||||
The best links offer readers another way to scan information.
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Use plain language that does not mislead or promise too much.
|
||||
- Be short and descriptive (around five words is best).
|
||||
- Allow people to predict (with a fair degree of confidence) what they will get if they click mirror the heading text on the destination page in links whenever possible.
|
||||
- Front-load user-and-action-oriented terms at the beginning of the link (Download our app).
|
||||
- Avoid generic calls to action (such as click here, find out more).
|
||||
- Do not include any end punctuation when you hyperlink text (for example, periods, question marks, or exclamation points).
|
||||
- Do not make link text italics or bold, unless it would be so as normal body copy.
|
||||
- Make sure your link opens in a new tab so it doesn't interrupt the user-flow.
|
||||
|
||||
For information on how to add links to your content, see [Useful component and formatting examples](../components/links.md).
|
||||
|
||||
## Code and code samples
|
||||
|
||||
Format the following as code: docker commands, instructions and filenames (package names).
|
||||
|
||||
To apply inline code style, wrap the text in a single backtick (`).
|
||||
|
||||
For information on how to add codeblocks to your content, see [Useful component and formatting examples](../components/code-blocks.md).
|
||||
|
||||
## Callouts
|
||||
|
||||
Use callouts to emphasize selected information in a page.
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Format the word Warning, Important, or Note in bold. Do not bold the content within the callout.
|
||||
- It's good practice to avoid placing a lot of text callouts on one page. They can create a cluttered appearance if used to excess, and you'll diminish their impact.
|
||||
|
||||
| Text callout | Use case scenario | Color or callout box |
|
||||
| --- | --- | --- |
|
||||
| Warning | Use a Warning tag to signal to the reader where actions may cause damage to hardware or software loss of data. | Red |
|
||||
| | ✅ Example: Warning: When you use the docker login command, your credentials are stored in your home directory in .docker/config.json. The password is base64-encoded in this file. | |
|
||||
| Important | Use an Important tag to signal to the reader where actions may cause issues of a lower magnitude. | Yellow |
|
||||
| | ✅ Example: Update to the Docker Desktop terms | |
|
||||
| Note | Use the Note tag for information that may not apply to all readers, or if the information is tangential to a topic. | Blue |
|
||||
| | ✅ Example: Deleting a repository deletes all the images it contains and its build settings. This action cannot be undone.|
|
||||
|
||||
For information on how to add call outs to your content, see [Useful component and formatting examples](../components/call-outs.md).
|
||||
|
||||
## Navigation
|
||||
|
||||
When documenting how to navigate through the Docker Desktop or Docker Hub UI:
|
||||
|
||||
- Always use location, then action. For example:
|
||||
_From the **Visibility** dropdown list (location), select Public (action)._
|
||||
- Be brief and specific. For example:
|
||||
Do: _Select **Save**._
|
||||
Do not: _Select **Save** for the changes to take effect._
|
||||
- If a step must include a reason, start the step with it. This helps the user scan more quickly.
|
||||
Do: _To view the changes, in the merge request, select the link._
|
||||
Do not: _Select the link in the merge request to view the changes_
|
||||
|
||||
## Optional steps
|
||||
|
||||
If a step is optional, start the step with the word Optional followed by a period.
|
||||
|
||||
For example:
|
||||
|
||||
_1. Optional. Enter a description for the job._
|
||||
|
||||
## Placeholder text
|
||||
|
||||
You might want to provide a command or configuration that uses specific values.
|
||||
|
||||
In these cases, use < and > to call out where a reader must replace text with their own value. For example:
|
||||
|
||||
`docker extension install <name-of-your-extension>`
|
||||
|
||||
## Tables
|
||||
|
||||
Tables should be used to describe complex information in a straightforward manner.
|
||||
|
||||
Note that in many cases, an unordered list is sufficient to describe a list of items with a single, simple description per item. But, if you have data that’s best described by a matrix, tables are the best choice.
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Use sentence case for table headings.
|
||||
- To keep tables accessible and scannable, tables should not have any empty cells. If there is no otherwise meaningful value for a cell, consider entering N/A for ‘not applicable’ or None.
|
||||
|
||||
For information on how to add tables to your content, see [Useful component and formatting examples](../components/tables.md).
|
||||
159
contribute/style/grammar.md
Normal file
159
contribute/style/grammar.md
Normal file
@@ -0,0 +1,159 @@
|
||||
---
|
||||
title: Grammar and style
|
||||
description: Grammar and style guidelines for technical documentation
|
||||
keywords: grammar, style, contribute
|
||||
toc_max: 2
|
||||
---
|
||||
|
||||
## Acronyms and initialisms
|
||||
|
||||
An acronym is an abbreviation you would speak as a word, for example, ROM (for read only memory). Other examples include radar and scuba, which started out as acronyms but are now considered words in their own right.
|
||||
|
||||
An initialism is a type of acronym that comprises a group of initial letters used as an abbreviation for a name or expression. If you were using the acronym in a spoken conversation, you would enunciate each letter: H-T-M-L for Hypertext Markup Language.
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Spell out lesser-known acronyms or initialisms on first use, then follow with the acronym or initialism in parentheses. After this, throughout the rest of your page or document, use the acronym or initialism alone.
|
||||
> ‘You can use single sign-on (SSO) to sign in to Notion. You may need to ask your administrator to enable SSO.’
|
||||
- Where the acronym or initialism is more commonly used than the full phrase, for example, URL, HTML, you do not need to follow this spell-it-out rule.
|
||||
- Use all caps for acronyms of file types (a JPEG file).
|
||||
- Don't use apostrophes for plural acronyms. ✅URLs ❌URL’S
|
||||
- Avoid using an acronym for the first time in a title or heading. If the first use of the acronym is in a title or heading, introduce the acronym (in parentheses, following the spelled-out term) in the first body text that follows.
|
||||
|
||||
## Bolds and italics
|
||||
|
||||
Unless you're referring to Ul text or user-defined text, you should not add emphasis to text. Clear, front-loaded wording makes the subject of a sentence clear.
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Don't use bold to refer to a feature name.
|
||||
- Use italics sparingly, as this type of formatting can be difficult to read in digital experiences.
|
||||
Notable exceptions are titles of articles, blog posts, or specifcation documents.
|
||||
|
||||
## Capitalization
|
||||
|
||||
Use sentence case for just about everything. Sentence case means capitalizing only the first word, as you would in a standard sentence.
|
||||
|
||||
The following content elements should use sentence case:
|
||||
|
||||
- Titles of webinars and events
|
||||
- Headings and subheadings in all content types
|
||||
- Calls to action
|
||||
- Headers in boxed text
|
||||
- Column and row headers in tables
|
||||
- Links
|
||||
- Sentences (of course)
|
||||
- Anything in the Ul including navigation labels, buttons, headings
|
||||
|
||||
### Best practice
|
||||
|
||||
- As a general rule, it's best to avoid the use of ALL CAPITALS in most content types. They are more difficult to scan and take up more space. While all caps can convey emphasis, they can also give the impression of shouting.
|
||||
- If a company name is all lowercase or all uppercase letters, follow their style, even at the beginning of sentences: DISH and bluecrux. When in doubt, check the company's website.
|
||||
- Use title case for Docker solutions : Docker Extensions, Docker Hub.
|
||||
- Capitalize a job title if it immediately precedes a name (Chief Executive Officer Scott Johnston).
|
||||
- Do not capitalize a job title that follows a name or is a generic reference (Scott Johnston, chief executive officer of Docker).
|
||||
- Capitalize department names when you refer to the name of a department, but use lower case if you are talking about the field of work and not the actual department.
|
||||
- When referring to specific user interface text, like a button label or menu item, use the same capitalization that’s displayed in the user interface.
|
||||
|
||||
## Contractions
|
||||
|
||||
A contraction results from letters being left out from the original word or phrase, such as you're for you are or it's for it is.
|
||||
|
||||
Following our conversational approach, it's acceptable to use contractions in almost all content types. Just don't get carried away. Too many contractions in a sentence can make it difficult to read.
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Stay consistent - don't switch between contractions and their spelled-out equivalents in body copy or Ul text.
|
||||
- Avoid negative contractions (can't, don't, wouldn't, and shouldn't) whenever possible. Try to rewrite your sentence to align with our helpful approach that puts the focus on solutions, not problems.
|
||||
- Never contract a noun with is, does, has, or was as this can make it look like the noun is possessive. Your container is ready. Your container’s ready.
|
||||
|
||||
## Dates
|
||||
|
||||
You should use the U.S. format of month day, year format for dates: June 26, 2021.
|
||||
|
||||
When possible, use the month's full name (October 1, 2022). If there are space constraints, use 3-letter abbreviations followed by a period (Oct. 1. 2022).
|
||||
|
||||
## Decimals and fractions
|
||||
|
||||
In all UI content and technical documentation, use decimals instead of fractions.
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Always carry decimals to at least the hundredth place (33.76).
|
||||
|
||||
- In tables, align decimals on the decimal point.
|
||||
|
||||
- Add a zero before the decimal point for decimal fractions less than one (0.5 cm).
|
||||
|
||||
## Lists
|
||||
|
||||
Lists are a great way to break down complex ideas and make them easier to read and scan.
|
||||
|
||||
### Best practice:
|
||||
|
||||
- Bulleted lists should contain relatively few words or short phrases. For most content types, limit the number of items in a list to five.
|
||||
- Don’t add commas (,) or semicolons (;) to the ends of list items.
|
||||
- Some content types may use bulleted lists that contain 10 items, but it's preferable to break longer lists into several lists, each with its own subheading or introduction.
|
||||
- Never create a bulleted list with only one bullet, and never use a dash to indicate a bulleted list.
|
||||
- If your list items are fragments, capitalize the list items for ease of scanning but do not use terminal punctuation.
|
||||
Example:
|
||||
|
||||
I went to the shops to buy:
|
||||
|
||||
- Milk
|
||||
- Flour
|
||||
- Eggs
|
||||
- Make sure all your list items are parallel. This means you should structure each list item in the same way. They should all be fragments, or they should all be complete sentences. If you start one list item with a verb, then start every list item with a verb.
|
||||
- Every item in your list should start with a capital letter unless they’re parameters or commands.
|
||||
- Nested sequential lists are labelled with lowercase letters. For example:
|
||||
1. Top level
|
||||
2. Top level
|
||||
1. Child step
|
||||
2. Child step
|
||||
|
||||
|
||||
## Numbers
|
||||
|
||||
When you work with numbers in content, the best practices include:
|
||||
|
||||
- Spell out the numbers one to nine, except in units of measure such as 4 MB.
|
||||
- Represent numbers with two or more digits as numerals (10, 625, 773,925).
|
||||
- Recast a sentence, rather than begin it with a number (unless it's a year).
|
||||
- When you cite numbers in an example, write them out as they appear in any accompanying screenshots.
|
||||
- Write numbers out as they appear on the platform when you cite them in an example.
|
||||
- To refer to large numbers in abstract (such as thousands, millions, and billions), use a combination of words and numbers. Do not abbreviate numeric signifiers.
|
||||
- Avoid using commas in numbers because they can represent decimals in different cultures. For numbers that are five digits or more, use a space to separate.
|
||||
|
||||
|
||||
| Correct | Incorrect |
|
||||
| --- | --- |
|
||||
| 1000 | 1,000 |
|
||||
| 14 586 | 14,586 |
|
||||
| 1 390 680 | 1,390,680 |
|
||||
|
||||
### Versions
|
||||
|
||||
When writing version numbers for release notes, follow the example below:
|
||||
|
||||
Version 4.8.2
|
||||
|
||||
## Punctuation
|
||||
|
||||
### Colons and semicolons
|
||||
|
||||
- Use colons to: introduce a list inline in a sentence; introduce a bulleted or numbered list; and provide an explanation.
|
||||
- Do not use semicolons. Use two sentences instead.
|
||||
|
||||
### Commas
|
||||
|
||||
- Use the serial or Oxford comma - a comma before the coordinating conjunction (and, or) in a list of three or more things.
|
||||
- If a series contains more than three items or the items are long, consider a bulleted list to improve readability.
|
||||
|
||||
### Dashes and hyphens
|
||||
|
||||
- Use the em dash (-) sparingly when you want the reader to pause, to create parenthetical statements, or to emphasize specific words or phrases. Always put a space on either side of the em dash.
|
||||
- Use an en dash (-) to indicate spans of numbers, dates, or time.
|
||||
- Use a hyphen to join two or more words to form compound adjectives that precede a noun. The purpose of joining words to form a compound adjective is to differentiate the meaning from the adjectives used separately (for example, ‘up-to-date documentation’ ‘lump-sum payment’, and ‘well-stocked cupboard’. You can also use a hyphen to:
|
||||
- Avoid awkward doubling of vowels. For example ‘semi-independence*’,* or ‘re-elect’.
|
||||
- Prevent misreading of certain words. For example ‘Re-collect’ means to collect again; without a hyphen the word recollect has a different meaning.
|
||||
|
||||
107
contribute/style/recommended-words.md
Normal file
107
contribute/style/recommended-words.md
Normal file
@@ -0,0 +1,107 @@
|
||||
---
|
||||
title: Recommended word list
|
||||
description: Recommended word list for Technical documentation
|
||||
keywords: recommended word list, style guide, contribute
|
||||
---
|
||||
|
||||
To help ensure consistency across our documentation, the Technical Writing team recommends these wording choices.
|
||||
|
||||
#### above
|
||||
Try to avoid using `above` when referring to an example or table in a documentation page. If required, use `previous` instead.
|
||||
|
||||
For example:
|
||||
|
||||
_In the previous example, the dog had fleas._
|
||||
|
||||
#### below
|
||||
Try to avoid `below` when referring to an example or table in a documentation page. If required, use `following` instead.
|
||||
|
||||
For example:
|
||||
|
||||
_In the following example, the dog had fleas._
|
||||
|
||||
#### checkbox
|
||||
|
||||
Use one word for `checkbox`. Do not use `check box`.
|
||||
|
||||
You select (not check or enable) and clear (not deselect or disable) checkboxes.
|
||||
|
||||
#### click
|
||||
|
||||
Do not use `click`. Instead, use `select` with buttons, links, menu items, and lists.
|
||||
|
||||
Select applies to more devices, while click is more specific to a mouse.
|
||||
|
||||
#### currently
|
||||
|
||||
Do not use `currently` when talking about the product or its features. The documentation describes the product as it is today.
|
||||
|
||||
#### deselect
|
||||
|
||||
Don’t use `deselect`. Instead, use `clear`.
|
||||
|
||||
#### earlier
|
||||
|
||||
Use `earlier` when talking about version numbers.
|
||||
|
||||
Use:
|
||||
|
||||
_In Docker Desktop 4.1 and earlier._
|
||||
|
||||
Instead of:
|
||||
|
||||
_In Docker Desktop 4.1 and lower._
|
||||
|
||||
#### execute
|
||||
|
||||
Avoid where possible. Use `run` instead.
|
||||
|
||||
#### later
|
||||
Use `later` when talking about version numbers.
|
||||
|
||||
Use:
|
||||
|
||||
_In GitLab 14.1 and later._
|
||||
|
||||
Instead of:
|
||||
|
||||
_In GitLab 14.1 and higher…_ or _In GitLab 14.1 and above…_
|
||||
|
||||
#### register
|
||||
Use `register` instead of sign up when talking about creating an account.
|
||||
|
||||
#### respectively
|
||||
Avoid `respectively` and be more precise instead.
|
||||
|
||||
#### scroll
|
||||
|
||||
Avoid. Use a verb phrase such as _move through_ or _navigate to_ instead, if the context is clear.
|
||||
|
||||
#### sign in
|
||||
Use `sign in` instead of `sign on` or `log on` or `log in`. If the user interface has different words, use those.
|
||||
|
||||
|
||||
#### sign up
|
||||
Use `register` or `create account` instead of `sign up` when talking about creating an account.
|
||||
|
||||
#### toggle
|
||||
|
||||
You turn on or turn off a toggle. For example:
|
||||
|
||||
_Turn on the dark mode toggle._
|
||||
|
||||
#### upgrade
|
||||
Use `upgrade` for when describing a higher subscription tier
|
||||
|
||||
#### we
|
||||
|
||||
Try to avoid `we` and focus instead on how the user can accomplish something in Docker.
|
||||
|
||||
Use:
|
||||
|
||||
_Use widgets when you have work you want to organize._
|
||||
|
||||
Instead of:
|
||||
|
||||
_We created a feature for you to add widgets.
|
||||
One exception: You can use we recommend instead of it is recommended or GitLab recommends._
|
||||
60
contribute/style/terminology.md
Normal file
60
contribute/style/terminology.md
Normal file
@@ -0,0 +1,60 @@
|
||||
---
|
||||
title: Docker terminology
|
||||
description: Docker specific terminology and definitions
|
||||
keywords: terminology, style guide, contribute
|
||||
---
|
||||
|
||||
#### `compose.yaml`
|
||||
|
||||
The current designation for the Compose file, as it is a file, format as code.
|
||||
|
||||
#### Compose plugin
|
||||
|
||||
The compose app as an add-on (for Docker CLI) that can be enabled/disabled.
|
||||
|
||||
#### Digest
|
||||
|
||||
The long number that’s automatically created every time you push an image. You can pull an image by Digest or by Tag.
|
||||
|
||||
#### Docker Compose
|
||||
|
||||
Use when we talk about the application, or all the functionality associated with the application.
|
||||
|
||||
#### `docker compose`
|
||||
|
||||
Use code formatting) for referring to the commands in text and command usage examples/code samples.
|
||||
|
||||
#### Docker Compose CLI
|
||||
|
||||
Use when referring to family of Compose commands as offered from the Docker CLI.
|
||||
|
||||
#### Multi-platform
|
||||
|
||||
(broad meaning) Mac vs Linux vs Microsoft but also pair of platform architecture such as in Linux/amd64 and Linux/arm64; (narrow meaning) windows/linux/mac.
|
||||
|
||||
#### Multi-architecture / multi-arch
|
||||
|
||||
To use when referring specifically to CPU architecture or something that is hardware-architecture-based. Avoid using it as meaning the same as multi-platform.
|
||||
|
||||
#### Member
|
||||
|
||||
A user of Docker Hub that is a part of an organization
|
||||
|
||||
#### Namespace
|
||||
|
||||
Organization or User name. Every image needs a namespace to live under.
|
||||
|
||||
#### Node
|
||||
|
||||
A node is a physical or virtual machine running an instance of the Docker Engine in swarm mode.
|
||||
Manager nodes perform swarm management and orchestration duties. By default manager nodes are also worker nodes.
|
||||
Worker nodes execute tasks.
|
||||
|
||||
#### Registry
|
||||
|
||||
Online storage for Docker images.
|
||||
|
||||
#### Repository
|
||||
|
||||
Lets users share container images with their team, customers, or Docker community.
|
||||
|
||||
49
contribute/style/voice-tone.md
Normal file
49
contribute/style/voice-tone.md
Normal file
@@ -0,0 +1,49 @@
|
||||
---
|
||||
title: Voice and tone
|
||||
description: Docker's voice and tone
|
||||
keywords: style guide, voice, tone, content standards
|
||||
---
|
||||
|
||||
# Voice
|
||||
|
||||
At Docker, we've been the customer. We're developers developing for developers. We speak with experience and knowledge and without arrogance or ego. We want to inform and empower people without being confusing or pushy.
|
||||
|
||||
We're not afraid to use a bit of cheeky humor to lighten the conversation (and because we don't take ourselves too seriously) but we're always respectful. We communicate with clarity, empathy, and wit; everything we say should inform and encourage.
|
||||
|
||||
We align our tone of voice and content with our virtues. The most important principles we follow when we write are the 4Cs:
|
||||
|
||||
1. **Correct**
|
||||
2. **Concise**
|
||||
3. **Complete**
|
||||
4. **Clear**
|
||||
|
||||
We ensure the information is accurate, succinct, thorough, and easy to understand. We keep sentences as simple as possible, but include enough detail for the user to complete the intended task.
|
||||
|
||||
All of this means that when we write documentation and UI copy:
|
||||
|
||||
1. **We are honest.** We give you all the facts and we don't use misdirection or make ambiguous statements. We don't always have all the answers, but we're doing our best to make life better for developers and we'll tell you how it's going.
|
||||
2. **We are concise.** We understand the industry of complex and detailed messaging our users live in because we come from the same world. Docker doesn't bulk up our communication with fluffy words or complex metaphors. We're clear and to the point.
|
||||
3. **We are relaxed.** Our demeanor is casual but not lazy, smart but not arrogant, and focused but not cold. Our voice should be welcoming and warm.
|
||||
4. **We are inclusive.** Developers are developers no matter how much code they've written. Every person is as much a part of our community as the next. We are accepting of all developers from all industries and experience levels.
|
||||
|
||||
# Tone
|
||||
|
||||
Docker's tone is usually informal, but we believe it's always more important to be clear over comical. We're relaxed, but we're not inappropriate or unprofessional.
|
||||
|
||||
## Friendly tone
|
||||
|
||||
Use a tone that's natural, friendly, and respectful without being overly colloquial or full of jargons. Write to inform and empower developers without being confusing or pushy. It’s OK to use contractions as long as the sentence doesn’t become too slangy or informal.
|
||||
|
||||
**Avoid overdoing the politeness.** It is good to be friendly and polite, but using ‘please’ in technical documentation or UI copy might be overdoing the politeness.
|
||||
|
||||
## Positive language
|
||||
|
||||
Use a positive language. Instead of highlighting the limitations and what the users cannot do, emphasize on the positive outcomes.
|
||||
|
||||
For example, **instead of**:
|
||||
|
||||
“*Features such as Single Sign-on (SSO), Image Access Management, Registry Access Management are not available in Docker Team subscription.”*
|
||||
|
||||
**Use**:
|
||||
|
||||
“*Features such as Single Sign-on (SSO), Image Access Management, Registry Access Management are available in Docker Business subscription*.”
|
||||
4
images/check.svg
Normal file
4
images/check.svg
Normal file
@@ -0,0 +1,4 @@
|
||||
<!-- License: CC Attribution. Made by AkashRajDahal: https://dribbble.com/AkashRajDahal -->
|
||||
<svg width="24px" height="24px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M9.55 19.91C9.10487 19.9068 8.67832 19.7312 8.36 19.42L2.16 13.21C2.08924 13.1411 2.03301 13.0586 1.99461 12.9676C1.95621 12.8766 1.93643 12.7788 1.93643 12.68C1.93643 12.5812 1.95621 12.4834 1.99461 12.3924C2.03301 12.3014 2.08924 12.2189 2.16 12.15L4.57 9.73C4.89374 9.41061 5.33023 9.23153 5.785 9.23153C6.23978 9.23153 6.67626 9.41061 7 9.73L9.78 12.52C9.81356 12.5524 9.85837 12.5705 9.905 12.5705C9.95163 12.5705 9.99645 12.5524 10.03 12.52L17.38 5.17C17.7002 4.86318 18.1265 4.69189 18.57 4.69189C19.0135 4.69189 19.4398 4.86318 19.76 5.17L21.21 6.62C21.5233 6.93482 21.6991 7.36088 21.6991 7.805C21.6991 8.24913 21.5233 8.67518 21.21 8.99L10.74 19.42C10.4217 19.7312 9.99513 19.9068 9.55 19.91ZM3.75 12.68L9.42 18.35C9.45356 18.3824 9.49837 18.4005 9.545 18.4005C9.59163 18.4005 9.63645 18.3824 9.67 18.35L20.1 7.93C20.1324 7.89645 20.1505 7.85163 20.1505 7.805C20.1505 7.75837 20.1324 7.71356 20.1 7.68L18.65 6.23C18.6148 6.19696 18.5683 6.17857 18.52 6.17857C18.4717 6.17857 18.4252 6.19696 18.39 6.23L11 13.58C10.6803 13.8839 10.2561 14.0533 9.815 14.0533C9.37392 14.0533 8.9497 13.8839 8.63 13.58L5.89 10.79C5.87519 10.7694 5.85567 10.7525 5.83306 10.7409C5.81046 10.7293 5.78541 10.7233 5.76 10.7233C5.73459 10.7233 5.70955 10.7293 5.68694 10.7409C5.66433 10.7525 5.64482 10.7694 5.63 10.79L3.75 12.68Z" fill="black"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 1.5 KiB |
6
images/contribute.svg
Normal file
6
images/contribute.svg
Normal file
@@ -0,0 +1,6 @@
|
||||
<!-- License: CC Attribution. Made by remartwork: https://dribbble.com/remartwork -->
|
||||
<svg width="24px" height="24px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M8.12903 15.0769C8.12903 14.6521 8.47565 14.3077 8.90323 14.3077H13.0323C13.4598 14.3077 13.8065 14.6521 13.8065 15.0769C13.8065 15.5018 13.4598 15.8462 13.0323 15.8462H8.90323C8.47565 15.8462 8.12903 15.5018 8.12903 15.0769Z" fill="#030D45"/>
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M10.9677 17.8974C10.5402 17.8974 10.1935 17.553 10.1935 17.1282V13.0256C10.1935 12.6008 10.5402 12.2564 10.9677 12.2564C11.3953 12.2564 11.7419 12.6008 11.7419 13.0256V17.1282C11.7419 17.553 11.3953 17.8974 10.9677 17.8974Z" fill="#030D45"/>
|
||||
<path fill-rule="evenodd" clip-rule="evenodd" d="M12 3.53846C10.4751 3.53846 8.42753 3.70582 6.99542 3.8447C6.40117 3.90233 5.93741 4.3731 5.89141 4.96993C5.749 6.81754 5.54839 9.81282 5.54839 12C5.54839 14.1872 5.749 17.1825 5.89141 19.0301C5.93741 19.6269 6.40117 20.0977 6.99542 20.1553C8.42753 20.2942 10.4751 20.4615 12 20.4615C13.5249 20.4615 15.5725 20.2942 17.0046 20.1553C17.5988 20.0977 18.0626 19.6269 18.1086 19.0301C18.251 17.1825 18.4516 14.1872 18.4516 12C18.4516 11.2947 18.4307 10.5036 18.3975 9.69231H15.0976L15.0968 8.92308L15.0968 8.15385H18.321C18.1302 5.71619 16.228 3.7745 13.8065 3.59594V6.8718C13.8065 7.57985 14.3842 8.15385 15.0968 8.15385L15.0968 8.92308L15.0976 9.69231C13.5298 9.69231 12.2581 8.42952 12.2581 6.8718V3.53997C12.1705 3.53898 12.0844 3.53846 12 3.53846ZM13.0569 2.02069C12.6911 2.00756 12.3351 2 12 2C10.3935 2 8.28091 2.17427 6.84502 2.31351C5.49709 2.44423 4.45055 3.51605 4.34754 4.85245C4.20508 6.70071 4 9.74813 4 12C4 14.2519 4.20508 17.2993 4.34754 19.1475C4.45055 20.484 5.49709 21.5558 6.84502 21.6865C8.28091 21.8257 10.3935 22 12 22C13.6065 22 15.7191 21.8257 17.155 21.6865C18.5029 21.5558 19.5495 20.484 19.6525 19.1475C19.7949 17.2993 20 14.2519 20 12C20 11.0519 19.9637 9.9656 19.9114 8.8902C19.9112 8.88689 19.911 8.88359 19.9109 8.8803C19.8996 8.64894 19.8876 8.41812 19.875 8.1893C19.6948 4.90999 17.1178 2.22743 13.7827 2.05298C13.5417 2.04037 13.3017 2.02954 13.0659 2.02102" fill="#030D45"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 2.2 KiB |
4
images/formatting.svg
Normal file
4
images/formatting.svg
Normal file
@@ -0,0 +1,4 @@
|
||||
<!-- License: Apache. Made by grommet: https://github.com/grommet/grommet-icons -->
|
||||
<svg width="24px" height="24px" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
|
||||
<path fill="none" stroke="#000" stroke-width="2" d="M17,10 L24,10 L17,10 L17,10 Z M1,14 L14,14 L14,2 L1,2 L1,14 Z M6,6 C6,6.5525 5.5525,7 5,7 C4.4475,7 4,6.5525 4,6 C4,5.4475 4.4475,5 5,5 C5.5525,5 6,5.4475 6,6 M17,6 L24,6 L17,6 L17,6 Z M17,2 L24,2 L17,2 L17,2 Z M17,14 L24,14 L17,14 L17,14 Z M0,18 L24,18 L0,18 L0,18 Z M0,22 L24,22 L0,22 L0,22 Z M14,14 L14,13 L10,8 L7,11 L6,10 L2,14 L14,14 Z"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 578 B |
12
images/grammar.svg
Normal file
12
images/grammar.svg
Normal file
@@ -0,0 +1,12 @@
|
||||
<?xml version="1.0" encoding="UTF-8"?>
|
||||
<!-- License: MIT. Made by Microsoft: https://github.com/microsoft/fluentui-system-icons -->
|
||||
<svg width="24px" height="24px" viewBox="0 0 24 24" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink">
|
||||
<!-- Uploaded to SVGRepo https://www.svgrepo.com -->
|
||||
<title>ic_fluent_text_grammar_options_24_filled</title>
|
||||
<desc>Created with Sketch.</desc>
|
||||
<g id="🔍-System-Icons" stroke="none" stroke-width="1" fill="none" fill-rule="evenodd">
|
||||
<g id="ic_fluent_text_grammar_options_24_filled" fill="#212121" fill-rule="nonzero">
|
||||
<path d="M13.7803,16.2161 C14.0732,16.509 14.0732,16.9839 13.7803,17.2768 L9.28033,21.7768 C8.98744,22.0697 8.51256,22.0697 8.21967,21.7768 C7.92678,21.4839 7.92678,21.009 8.21967,20.7161 L12.7197,16.2161 C13.0126,15.9232 13.4874,15.9232 13.7803,16.2161 Z M10.5216,17 L8.52157,19 L3,19 C2.44772,19 2,18.5523 2,18 C2,17.4872 2.38604,17.0645 2.88338,17.0067 L3,17 L10.5216,17 Z M16.5,8 C16.8788,8 17.1981,8.28243 17.2444,8.65837 L17.3834,9.78797 C17.5656,11.2682 18.7318,12.4344 20.212,12.6166 L21.3416,12.7556 C21.7176,12.8019 22,13.1212 22,13.5 C22,13.8788 21.7176,14.1981 21.3416,14.2444 L20.212,14.3834 C18.7318,14.5656 17.5656,15.7318 17.3834,17.212 L17.2444,18.3416 C17.1981,18.7176 16.8788,19 16.5,19 C16.1212,19 15.8019,18.7176 15.7556,18.3416 L15.6166,17.212 C15.4344,15.7318 14.2682,14.5656 12.788,14.3834 L11.6584,14.2444 C11.2824,14.1981 11,13.8788 11,13.5 C11,13.1212 11.2824,12.8019 11.6584,12.7556 L12.788,12.6166 C14.2682,12.4344 15.4344,11.2682 15.6166,9.78797 L15.7556,8.65837 C15.8019,8.28243 16.1212,8 16.5,8 Z M10.0726,13 C10.0253,13.1588 10,13.3268 10,13.5 C10,14.0786917 10.2825854,14.5979757 10.7238993,14.9178198 L10.8481,15 L3,15 C2.44772,15 2,14.5523 2,14 C2,13.5266462 2.32893349,13.1300639 2.77071002,13.0263909 L2.88338,13.0067 L3,13 L10.0726,13 Z M13,9 C13.5523,9 14,9.44772 14,10 C14,10.5128 13.614,10.9355 13.1166,10.9933 L13,11 L3,11 C2.44772,11 2,10.5523 2,10 C2,9.48716 2.38604,9.06449 2.88338,9.00673 L3,9 L13,9 Z M21,5 C21.5523,5 22,5.44772 22,6 C22,6.47339077 21.6711006,6.8699503 21.2292821,6.97358813 L21.1166,6.99327 L21,7 L3,7 C2.44772,7 2,6.55228 2,6 C2,5.52660923 2.32893349,5.1300497 2.77071002,5.02641187 L2.88338,5.00673 L3,5 L21,5 Z" id="🎨-Color"></path>
|
||||
</g>
|
||||
</g>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 2.3 KiB |
6
images/new-page.svg
Normal file
6
images/new-page.svg
Normal file
@@ -0,0 +1,6 @@
|
||||
<!-- License: MIT. Made by iconoir: https://iconoir.com/ -->
|
||||
<svg width="24px" height="24px" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
|
||||
<path d="M9 12H12M15 12H12M12 12V9M12 12V15" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<path d="M4 21.4V2.6C4 2.26863 4.26863 2 4.6 2H16.2515C16.4106 2 16.5632 2.06321 16.6757 2.17574L19.8243 5.32426C19.9368 5.43679 20 5.5894 20 5.74853V21.4C20 21.7314 19.7314 22 19.4 22H4.6C4.26863 22 4 21.7314 4 21.4Z" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
<path d="M16 5.4V2.35355C16 2.15829 16.1583 2 16.3536 2C16.4473 2 16.5372 2.03725 16.6036 2.10355L19.8964 5.39645C19.9628 5.46275 20 5.55268 20 5.64645C20 5.84171 19.8417 6 19.6464 6H16.6C16.2686 6 16 5.73137 16 5.4Z" fill="currentColor" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/>
|
||||
</svg>
|
||||
|
After Width: | Height: | Size: 940 B |
16
images/terminology.svg
Normal file
16
images/terminology.svg
Normal file
@@ -0,0 +1,16 @@
|
||||
<!-- License: Apache. Made by Carbon Design: https://github.com/carbon-design-system/carbon -->
|
||||
<svg width="32px" height="32px" viewBox="0 0 32 32" id="icon" xmlns="http://www.w3.org/2000/svg">
|
||||
<defs>
|
||||
<style>
|
||||
.cls-1 {
|
||||
fill: none;
|
||||
}
|
||||
</style>
|
||||
</defs>
|
||||
<title>string-text</title>
|
||||
<path d="M29,22H24a2.0027,2.0027,0,0,1-2-2V14a2.0023,2.0023,0,0,1,2-2h5v2H24v6h5Z"/>
|
||||
<path d="M18,12H14V8H12V22h6a2.0027,2.0027,0,0,0,2-2V14A2.0023,2.0023,0,0,0,18,12Zm-4,8V14h4v6Z"/>
|
||||
<path d="M8,12H3v2H8v2H4a2,2,0,0,0-2,2v2a2,2,0,0,0,2,2h6V14A2.0023,2.0023,0,0,0,8,12Zm0,8H4V18H8Z"/>
|
||||
<rect id="_Transparent_Rectangle_" data-name="<Transparent Rectangle>" class="cls-1" width="32" height="32"/>
|
||||
</svg>
|
||||
|
||||
|
After Width: | Height: | Size: 727 B |
867
test.md
867
test.md
@@ -1,867 +0,0 @@
|
||||
---
|
||||
description: Smoketest page
|
||||
title: Testing page
|
||||
sitemap: false
|
||||
toc_min: 1
|
||||
---
|
||||
|
||||
Welcome to the Docker documentation test page!
|
||||
|
||||
This is a demo of components, tags, styles, tools, and strategies we use for the
|
||||
docs. We explain the code behind the published page and demo the effects. So, if
|
||||
you want to see, for example, how admonitions and notes are coded in markdown,
|
||||
read the section on [Admonitions (notes)](test.md#admonitions-notes) on the web
|
||||
published page and study the pre-processed `test.md` to see how they are
|
||||
implemented. The Docker documentation team uses this page as "note to self"
|
||||
reminders. Since we invite docs suggestions and contributions from the
|
||||
community, we've always made the test page generally available.
|
||||
|
||||
If you want to understand how something in the docs is coded, use this page is
|
||||
as a resource.
|
||||
|
||||
If, in the course of making docs updates and suggestions, you develop a new
|
||||
strategy or component for the docs, feel free to add a demo and explanation to
|
||||
this test page and submit a PR for it so we can review and discuss it.
|
||||
|
||||
Cool? Let's dive in!
|
||||
|
||||
# Heading 1
|
||||
|
||||
Most pages don't actually have a H1 heading. The page title from the metadata is
|
||||
automatically inserted. We have included it here to show all heading levels, and
|
||||
set front matter as `toc_min: 1` so that it shows in the navigation bar (on-page
|
||||
topics).
|
||||
|
||||
## Heading 2
|
||||
|
||||
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
|
||||
greater than `toc_max` then no headings are shown.
|
||||
|
||||
### Heading 3
|
||||
|
||||
This is the lowest heading included in the right-nav, by default. To include
|
||||
more heading levels, set `toc_max: 4` in the page's front-matter. You can go all
|
||||
the way to 6.
|
||||
|
||||
#### Heading 4
|
||||
|
||||
This heading is not included in the right-nav. To include it set `toc_max: 4` in
|
||||
the page's front-matter.
|
||||
|
||||
##### Heading 5
|
||||
|
||||
This heading is not included in the right-nav. To include it set `toc_max: 5` in
|
||||
the page's front-matter.
|
||||
|
||||
###### Heading 6
|
||||
|
||||
This is probably too many headings. Try to avoid it.
|
||||
|
||||
This heading is not included in the right-nav. To include it set `toc_max: 6` in
|
||||
the page's front-matter.
|
||||
|
||||
## Typography
|
||||
|
||||
Plain block of text.
|
||||
|
||||
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
|
||||
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
|
||||
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
|
||||
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
|
||||
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
|
||||
culpa qui officia deserunt mollit anim id est laborum.
|
||||
|
||||
**Inline text styles**:
|
||||
|
||||
- **bold**
|
||||
- _italic_
|
||||
- ***bold italic***
|
||||
- ~~strikethrough~~
|
||||
- <u>underline</u>
|
||||
- _<u>underline italic</u>_
|
||||
- **<u>underline bold</u>**
|
||||
- ***<u>underline bold italic</u>***
|
||||
- `monospace text`
|
||||
- **`monospace bold`**
|
||||
|
||||
## Links and images
|
||||
|
||||
### Links
|
||||
|
||||
- [a markdown link](https://docker.com/)
|
||||
- [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.)
|
||||
|
||||
- [a markdown link to a custom target ID](#custom-target-id)
|
||||
|
||||
- <a href="https://docker.com/">an HTML link</a>
|
||||
|
||||
- <a href="https://docker.com/" target="_blank" rel="noopener" class="_">an HTML link that opens in a new window</a>
|
||||
|
||||
- A link to a Github PR in `docker/docker`: {% include github-pr.md pr=28199 %}
|
||||
|
||||
- A link to a Github PR in `docker/docker.github.io`: {% include github-pr.md repo=docker.github.io pr=9999 %}
|
||||
|
||||
- You can specify `org=foo` to use a Github organization other than Docker
|
||||
|
||||
- A link to an auto-generated reference page that we pull in during docs builds:
|
||||
[/engine/reference/builder/#env](/engine/reference/builder/#env).
|
||||
|
||||
- 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
|
||||
**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
|
||||
from the URL, and use that as the link in your docs file.
|
||||
|
||||
- Keep in mind that this link doesn't resolve until you merge the PR and
|
||||
your docs are published on [docs.docker.com](/).
|
||||
|
||||
{: 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"}`.
|
||||
|
||||
You can use custom targets to link to headings or even paragraphs. You link to
|
||||
it as you would any other link, using `#custom-target-id` as the ultimate
|
||||
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,
|
||||
so we added a custom ID above the target heading.
|
||||
|
||||
### Images
|
||||
|
||||
- A small cute image: 
|
||||
|
||||
- A small cute image that is a link. The extra newline here makes it not show
|
||||
inline:
|
||||
|
||||
[](https://www.docker.com/)
|
||||
|
||||
- A big wide image: 
|
||||
|
||||
- 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://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: {: class="img-thumbnail" }
|
||||
|
||||
- The same one, but using HTML: <img class="img-thumbnail" src="/images/footer_moby_icon.png" alt="a pretty wide image as a thumbnail, using HTML"/>
|
||||
|
||||
## Videos
|
||||
|
||||
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="_"}
|
||||
|
||||
To make the `.png` shown above, first take a screen snap of the YouTube video
|
||||
you want to use, then use a graphics app to overlay a play button onto the
|
||||
image.
|
||||
|
||||
For the overlay, you can use the play button at
|
||||
[/docker-cloud/images/](https://github.com/docker/docker.github.io/tree/master/docker-cloud/images).
|
||||
|
||||
## Lists
|
||||
|
||||
- Bullet list item 1
|
||||
- Bullet list item 2
|
||||
* Bullet list item 3
|
||||
|
||||
1. Numbered list item 1. Two spaces between the period and the first letter
|
||||
helps with alignment.
|
||||
|
||||
2. Numbered list item 2. Let's put a note in it.
|
||||
|
||||
>**Note**: We did it!
|
||||
|
||||
3. Numbered list item 3 with a code block in it. You need the blank line before
|
||||
the code block happens.
|
||||
|
||||
```bash
|
||||
$ docker run hello-world
|
||||
```
|
||||
|
||||
4. Numbered list item 4 with a bullet list inside it and a numbered list
|
||||
inside that.
|
||||
|
||||
- Sub-item 1
|
||||
- Sub-item 2
|
||||
1. Sub-sub-item 1
|
||||
2. Sub-sub-item-2 with a table inside it because we like to party!
|
||||
Indentation is super important.
|
||||
|
||||
|Header 1 | Header 2 |
|
||||
|---------|----------|
|
||||
| Thing 1 | Thing 2 |
|
||||
| Thing 3 | Thing 4 |
|
||||
|
||||
## Tables
|
||||
|
||||
Some tables in markdown and html.
|
||||
|
||||
| Permission level | Access |
|
||||
|:-------------------------------------------------------------------------|:-------------------------------------------------------------|
|
||||
| **Bold** or _italic_ within a table cell. Next cell is empty on purpose. | |
|
||||
| | 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 |
|
||||
|
||||
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
|
||||
row and separator row are optional.
|
||||
|
||||
If you need block-level HTML within your table cells, such as multiple
|
||||
paragraphs, lists, sub-tables, etc, then you need to make a HTML table.
|
||||
This is also the case if you need to use rowspans or colspans. Try to avoid
|
||||
setting styles directly on your tables! If you set the width on a `<td>`, you
|
||||
only need to do it on the first one. If you have a `<th>`, set it there.
|
||||
|
||||
> **Note**: If you need to have **markdown** in a **HTML** table, add
|
||||
> `markdown="span"` to the HTML for the `<td>` cells that contain the Markdown.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<th width="50%">Left channel</th>
|
||||
<th>Right channel</th>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>This is some test text. <br><br>This is more <b>text</b> on a new line. <br><br>Lorem ipsum dolor <tt>sit amet</tt>, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.
|
||||
</td>
|
||||
<td>This is some more text about the right hand side. There is a <a href="https://github.com/docker/docker-ce/blob/master/components/cli/experimental/README.md" target="_blank" rel="noopener" class="_">link here to the Docker Experimental Features README</a> on GitHub. In tables, links need to be `<a href="/"></a>`. <br><br>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua.</td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td>
|
||||
<p><a class="button primary-btn" href="/">Go to the docs!</a></p>
|
||||
<p><a href="/"><font color="#BDBDBD" size="-1">It is dark here. You are likely to be eaten by a grue.</font></a></p>
|
||||
</td>
|
||||
<td>
|
||||
<p><a class="button primary-btn" href="/">Go to the docs!</a></p>
|
||||
<p><a href="/"><font color="#BDBDBD" size="-1">It is dark here. You are likely to be eaten by a grue.</font></a></p>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
## Glossary links and content
|
||||
|
||||
The glossary source lives in the documentation repository
|
||||
[docker.github.io](https://github.com/docker/docker.github.io) in
|
||||
`_data/glossary.yaml`. The glossary publishes to
|
||||
[https://docs.docker.com/glossary/](/glossary/).
|
||||
|
||||
To update glossary content, edit `_data/glossary.yaml`.
|
||||
|
||||
To link to a glossary term, link to `glossary.md#YourGlossaryTerm` (for
|
||||
example, [swarm](glossary.md#swarm)).
|
||||
|
||||
## Site-wide variables
|
||||
|
||||
Look in the top-level `_config.yml` for site-wide variables, such as
|
||||
`site.docker_ce_version`. To use them, use Liquid like:
|
||||
|
||||
```liquid
|
||||
{% raw %}{{ site.docker_ce_version }}{% endraw %}
|
||||
```
|
||||
|
||||
The current value of `site.docker_ce_version` is
|
||||
{{ site.docker_ce_version }}.
|
||||
|
||||
## Mixing Markdown and HTML
|
||||
|
||||
You can use <b>span-level</b> HTML tags within Markdown.
|
||||
|
||||
You can use a `<br />` tag to impose an extra newline like here:<br />
|
||||
|
||||
You can use entities like ` ` to keep a bunch of words together .
|
||||
|
||||
<center>
|
||||
You can use block-level HTML tags too. This paragraph is centered.
|
||||
</center>
|
||||
|
||||
Keep reading for more examples, such as creating tabbed content within the
|
||||
page or displaying content as "cards".
|
||||
|
||||
## Jekyll / Liquid tricks
|
||||
|
||||
### Assignment
|
||||
|
||||
This paragraph is centered and colored green by setting CSS directly on the element.
|
||||
**Even though you can do this and it's sometimes the right way to go, remember that if
|
||||
we re-skin the site, any inline styles need to be dealt with manually!**
|
||||
{: style="text-align:center; color: green" }
|
||||
|
||||
{% assign my-text="foo" %}
|
||||
|
||||
The Liquid assignment just before this line fills in the following token {{ my-text }}.
|
||||
This is effective for the rest of this file unless the token is reset.
|
||||
|
||||
{% capture my-other-text %}foo{% endcapture %}
|
||||
Here is another way: {{ my-other-text }}
|
||||
|
||||
You can nest captures within each other to represent more complex logic with Liquid.
|
||||
|
||||
### Liquid variable scope
|
||||
|
||||
- Things set in the top level of `_config.yml` are available as site variables, like `{{ site.debug }}`.
|
||||
- Things set in the page's metadata, either via the defaults in `_config.yml` or per page, are available as page variables, like `{{ page.title }}`.
|
||||
- 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 }}`.
|
||||
|
||||
## Bootstrap and CSS tricks
|
||||
|
||||
Here are cool components you can include on Docs pages using
|
||||
[Bootstrap](https://getbootstrap.com) and [CSS](https://developer.mozilla.org/en-US/docs/Web/CSS).
|
||||
|
||||
### Tabs
|
||||
|
||||
Here are some tabs:
|
||||
|
||||
<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<hr></div>
|
||||
<div id="tab2" class="tab-pane fade">TAB 2 CONTENT<hr></div>
|
||||
</div>
|
||||
|
||||
You need to adjust the `id` and `data-target` values to match your use case.
|
||||
|
||||
The `<hr>`'s are included simply to add visual separation between tabbed content
|
||||
and the other topics on the page.
|
||||
|
||||
If you have Markdown inside the content of the `<div>`, just add `markdown="1"`
|
||||
as an attribute in the HTML for the `<div>` so that Kramdown renders it.
|
||||
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#tab3">TAB 1 HEADER</a></li>
|
||||
<li><a data-toggle="tab" data-target="#tab4">TAB 2 HEADER</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="tab3" class="tab-pane fade in active" markdown="1">
|
||||
|
||||
#### A Markdown header
|
||||
|
||||
- list item 1
|
||||
- list item 2
|
||||
<hr>
|
||||
</div>
|
||||
<div id="tab4" class="tab-pane fade" markdown="1">
|
||||
|
||||
#### Another Markdown header
|
||||
|
||||
- list item 3
|
||||
- list item 4
|
||||
<hr>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
#### Synchronizing multiple tab groups
|
||||
|
||||
Consider an example where you have something like one tab per language, and
|
||||
you have multiple tab sets like this on a page. You might want them to all
|
||||
toggle together. We have Javascript that loads on every page that lets you
|
||||
do this by setting the `data-group` attributes to be the same. The
|
||||
`data-target` attributes still need to point to unique div IDs.
|
||||
|
||||
In this example, selecting `Go` or `Python` in one tab set toggles the
|
||||
other tab set to match.
|
||||
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#go" data-group="go">Go</a></li>
|
||||
<li><a data-toggle="tab" data-target="#python" data-group="python">Python</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="go" class="tab-pane fade in active">Go content here<hr></div>
|
||||
<div id="python" class="tab-pane fade in">Python content here<hr></div>
|
||||
</div>
|
||||
|
||||
And some content between the two sets, just for fun...
|
||||
|
||||
<ul class="nav nav-tabs">
|
||||
<li class="active"><a data-toggle="tab" data-target="#go-2" data-group="go">Go</a></li>
|
||||
<li><a data-toggle="tab" data-target="#python-2" data-group="python">Python</a></li>
|
||||
</ul>
|
||||
<div class="tab-content">
|
||||
<div id="go-2" class="tab-pane fade in active">Go content here<hr></div>
|
||||
<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
|
||||
a row, each of which takes up 1/3 (4/12) of the row. You need a couple `<br />`s
|
||||
to clear the row before.<br /><br />
|
||||
|
||||
<div class="row">
|
||||
<div class="panel col-xs-12 col-md-4">This takes up 1/3 of the row unless the screen is small,
|
||||
then it takes up the whole row.</div>
|
||||
<div class="panel col-xs-12 col-md-4">This takes up 1/3 of the row unless the screen is small,
|
||||
then it takes up the whole row.</div>
|
||||
<div class="panel col-xs-12 col-md-4">This takes up 1/3 of the row unless the screen is small,
|
||||
then it takes up the whole row.</div>
|
||||
</div>
|
||||
|
||||
### Expand/Collapse accordions
|
||||
|
||||
You can use the Bootstrap and CSS to add expand/collapse accordions. This
|
||||
implementation makes use of the `.panel-heading` classes in
|
||||
[`_utilities.scss`](https://github.com/docker/docker.github.io/blob/master/_scss/_utilities.scsss),
|
||||
along with [FontAwesome icons](http://fontawesome.io/cheatsheet/){: target="_blank" rel="noopener" class="_" }
|
||||
<i class="fa fa-caret-down" aria-hidden="true"></i> (fa-caret-down) and
|
||||
<i class="fa fa-caret-up" aria-hidden="true"></i> (fa-caret-up).
|
||||
|
||||
Adding `block` to the `div` class `collapse` gives you some padding around the
|
||||
sample content. This works nicely for standard text. If you have a code sample,
|
||||
the padding renders as white space around the code block grey background. If we
|
||||
don't like this effect, we can remove `block` for code samples.
|
||||
|
||||
The `style="cursor: pointer"` tag enables the expand/collapse functionality to
|
||||
work on mobile. (You can use the [Xcode iPhone simulator](https://developer.apple.com/library/content/documentation/IDEs/Conceptual/iOS_Simulator_Guide/GettingStartedwithiOSSimulator/GettingStartedwithiOSSimulator.html#//apple_ref/doc/uid/TP40012848-CH5-SW4){: target="_blank" rel="noopener" class="_" } to test on mobile.)
|
||||
|
||||
There are a lot of samples out there for Bootstrap accordions. This is the model
|
||||
we used: [PPxOJX accordion sample with HTML and
|
||||
CSS](https://codepen.io/anon/pen/PPxOJX){: target="_blank" rel="noopener" class="_" }. (Here is
|
||||
another example, but it uses Javascript, whereas the implementation shown
|
||||
[here](https://www.bootply.com/89084){: target="_blank" rel="noopener" class="_" } is Bootstrap
|
||||
and CSS only.)
|
||||
|
||||
> Make sure `data-target`'s and `id`'s match, and are unique
|
||||
>
|
||||
>For each drop-down, the value for `data-target` and
|
||||
`collapse` `id` must match, and id's must be unique per page. In this example,
|
||||
we name these `collapseSample1` and `collapseSample2`. Check out the
|
||||
[Compose file structure example](compose/compose-file/compose-file-v3.md#compose-file-structure-and-examples)
|
||||
to see another example.
|
||||
{: .important-vanilla}
|
||||
|
||||
<div class="panel panel-default">
|
||||
<div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample1" style="cursor: pointer">
|
||||
Docker hello-world example
|
||||
<i class="chevron fa fa-fw"></i></div>
|
||||
<div class="collapse block" id="collapseSample1">
|
||||
<pre><code>
|
||||
$ docker run hello-world
|
||||
Unable to find image 'hello-world:latest' locally
|
||||
latest: Pulling from library/hello-world
|
||||
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.
|
||||
(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
|
||||
|
||||
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/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>
|
||||
<div class="collapse block" id="collapseSample2">
|
||||
<p>
|
||||
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor
|
||||
incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis
|
||||
nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
|
||||
Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu
|
||||
fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in
|
||||
culpa qui officia deserunt mollit anim id est laborum.</p>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
### Columnar text
|
||||
|
||||
You can use the CSS `column-count` to flow your text into multiple columns.
|
||||
You need a couple `<br />`s to clear the row before.<br /><br />
|
||||
|
||||
<div style="column-count: 3">
|
||||
This example uses a HTML div. This example uses a HTML div. This example uses a HTML div.
|
||||
This example uses a HTML div. This example uses a HTML div. This example uses a HTML div.
|
||||
This example uses a HTML div. This example uses a HTML div. This example uses a HTML div.
|
||||
This example uses a HTML div. This example uses a HTML div. This example uses a HTML div.
|
||||
This example uses a HTML div. This example uses a HTML div. This example uses a HTML div.
|
||||
This example uses a HTML div. This example uses a HTML div. This example uses a HTML div.
|
||||
This example uses a HTML div. This example uses a HTML div. This example uses a HTML div.
|
||||
This example uses a HTML div. This example uses a HTML div. This example uses a HTML div.
|
||||
This example uses a HTML div. This example uses a HTML div. This example uses a HTML div.
|
||||
</div>
|
||||
|
||||
This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up.
|
||||
This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up.
|
||||
This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up.
|
||||
This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up.
|
||||
This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up.
|
||||
This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up.
|
||||
This example does it with Markdown. You can't have any blank lines or it breaks the Markdown block up.
|
||||
{: style="column-count: 3 "}
|
||||
|
||||
### Badges
|
||||
|
||||
You can have <span class="badge badge-info">badges</span>. You can also have
|
||||
<span class="badge badge-warning">yellow badges</span> or
|
||||
<span class="badge badge-danger">red badges</span>.
|
||||
|
||||
#### Badges as links
|
||||
|
||||
You can make a badge a link. Wrap the `<span>` with an `<a>` (not the other way
|
||||
around) so that the text on the badge is still white.
|
||||
|
||||
```html
|
||||
<a href="/test/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="Open the test page (in a new window)">Test</span></a>
|
||||
```
|
||||
|
||||
<a href="/test/" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="Open the test page (in a new window)">Test</span></a>
|
||||
|
||||
|
||||
You can also put tooltips on badges (as the example above shows). Keep reading for tooltips.
|
||||
|
||||
### Tooltips
|
||||
|
||||
To add a tooltip to any element, set `data-toggle="tooltip"` and set a `title`.
|
||||
Hovering over the element with the mouse pointer will make it visible. Tooltips
|
||||
are not visible on mobile devices or touchscreens, so don't rely on them as the
|
||||
only way to communicate important info.
|
||||
|
||||
```html
|
||||
<span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="Open the test page">Test</span>
|
||||
```
|
||||
|
||||
<span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="Open the test page">Test</span>
|
||||
|
||||
You can optionally set the `data-placement` attribute to `top`, `bottom`,
|
||||
`middle`, `center`, `left`, or `right`. Only set it if not setting it causes
|
||||
layout issues.
|
||||
|
||||
You don't have to use HTML. You can also set these attributes using Markdown.
|
||||
|
||||
```markdown
|
||||
This is a paragraph that has a tooltip. We position it to the left so it doesn't align with the middle top of the paragraph (that looks weird).
|
||||
{:data-toggle="tooltip" data-placement="left" title="Markdown tooltip example"}
|
||||
```
|
||||
|
||||
This is a paragraph that has a tooltip. We position it to the left so it doesn't align with the middle top of the paragraph (that looks weird).
|
||||
{:data-toggle="tooltip" data-placement="left" title="Markdown tooltip example"}
|
||||
|
||||
## 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.
|
||||
|
||||
## 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)
|
||||
- Important, which use the `{: .important}` tag
|
||||
- Warning , which use the `{: .warning}` tag
|
||||
|
||||
The new styles include prepended icons, color sidebars, and bold color titles
|
||||
for multi-paragraph notes, but no auto-prepended text. These are defined in a
|
||||
way that does not impact admonitions formatted with the original styles, so
|
||||
notes in your published documents are not adversely affected.
|
||||
|
||||
Examples are shown in the following sections.
|
||||
|
||||
### 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
|
||||
> 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.
|
||||
```
|
||||
|
||||
A note renders as follows:
|
||||
|
||||
> 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 are also formatted like this:
|
||||
|
||||
```markdown
|
||||
> **Note**
|
||||
>
|
||||
> This is another way to format a note.
|
||||
```
|
||||
|
||||
### 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}
|
||||
```
|
||||
|
||||
The 'important' class renders as follows:
|
||||
|
||||
> **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.
|
||||
>
|
||||
> You can also add more paragraphs here if your explanation is super complex.
|
||||
{: .warning}
|
||||
```
|
||||
|
||||
The 'warning' class renders as follows:
|
||||
|
||||
> **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
|
||||
|
||||
Use the `upgrade-cta.html` include to render a CTA asking the user to upgrade their plan. There are two parameters:
|
||||
|
||||
- `target-url`: This is what the upgrade button will link to. Will typically be something like `https://www.docker.com/pricing`, possibly with a utm code.
|
||||
- `header-text`: The text shown in the bolded header at the top of the CTA. Only accepts strings, no Markdown support.
|
||||
- `body`: This forms the body of the CTA. It accepts Markdown. To use multi-line bodies, use named captures as explained in [the Jekyll docs](https://jekyllrb.com/docs/includes/#passing-parameter-variables-to-includes).
|
||||
|
||||
{% raw %}
|
||||
```liquid
|
||||
{% include upgrade-cta.html
|
||||
body="Upgrade to gain access to this feature"
|
||||
header-text="This feature is restricted to X and Y plans"
|
||||
target-url="https://www.example.com/"
|
||||
%}
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
## Code blocks
|
||||
|
||||
Rouge provides lots of different code block "hints". If you leave off the hint,
|
||||
it tries to guess and sometimes gets it wrong. These are just a few hints that
|
||||
we use often.
|
||||
|
||||
### Raw, no highlighting
|
||||
|
||||
The raw markup is needed to keep Liquid from interpreting the things with double
|
||||
braces as templating language.
|
||||
|
||||
{% raw %}
|
||||
```none
|
||||
none with raw
|
||||
$ some command with {{double braces}}
|
||||
$ some other command
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Raw, Bash
|
||||
|
||||
{% raw %}
|
||||
```bash
|
||||
bash with raw
|
||||
$ some command with {{double braces}}
|
||||
$ some other command
|
||||
```
|
||||
{% endraw %}
|
||||
|
||||
### Bash
|
||||
|
||||
```bash
|
||||
$ echo "deb https://packages.docker.com/1.12/apt/repo ubuntu-trusty main" | sudo tee /etc/apt/sources.list.d/docker.list
|
||||
```
|
||||
|
||||
### Go
|
||||
|
||||
```go
|
||||
incoming := map[string]interface{}{
|
||||
"asdf": 1,
|
||||
"qwer": []interface{}{},
|
||||
"zxcv": []interface{}{
|
||||
map[string]interface{}{},
|
||||
true,
|
||||
int(1e9),
|
||||
"tyui",
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### PowerShell
|
||||
|
||||
```powershell
|
||||
Install-Module DockerMsftProvider -Force
|
||||
Install-Package Docker -ProviderName DockerMsftProvider -Force
|
||||
[System.Environment]::SetEnvironmentVariable("DOCKER_FIPS", "1", "Machine")
|
||||
Expand-Archive docker-18.09.1.zip -DestinationPath $Env:ProgramFiles -Force
|
||||
```
|
||||
|
||||
### Python
|
||||
|
||||
```python
|
||||
return html.format(name=os.getenv('NAME', "world"), hostname=socket.gethostname(), visits=visits)
|
||||
```
|
||||
|
||||
### Ruby
|
||||
|
||||
```ruby
|
||||
docker_service 'default' do
|
||||
action [:create, :start]
|
||||
end
|
||||
```
|
||||
|
||||
### JSON
|
||||
|
||||
Warning: Syntax highlighting breaks easily for JSON if the code you present is
|
||||
not a valid JSON document. Try running your snippet through [this
|
||||
linter](https://jsonlint.com) to make sure it's valid, and remember: there is no
|
||||
syntax for comments in JSON!
|
||||
|
||||
```json
|
||||
"server": {
|
||||
"http_addr": ":4443",
|
||||
"tls_key_file": "./fixtures/notary-server.key",
|
||||
"tls_cert_file": "./fixtures/notary-server.crt"
|
||||
}
|
||||
```
|
||||
|
||||
### HTML
|
||||
|
||||
```html
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<title>Welcome to nginx!</title>
|
||||
</head>
|
||||
</html>
|
||||
```
|
||||
|
||||
### Markdown
|
||||
|
||||
```markdown
|
||||
# Hello
|
||||
```
|
||||
|
||||
### ini
|
||||
|
||||
```ini
|
||||
[supervisord]
|
||||
nodaemon=true
|
||||
|
||||
[program:sshd]
|
||||
command=/usr/sbin/sshd -D
|
||||
```
|
||||
|
||||
### Dockerfile
|
||||
|
||||
To enable syntax highlighting for Dockerfiles, use the `conf` lexer, for now.
|
||||
In the future, native Dockerfile support is coming to Rouge.
|
||||
|
||||
```dockerfile
|
||||
# syntax=docker/dockerfile:1
|
||||
|
||||
#
|
||||
# example Dockerfile for https://docs.docker.com/examples/postgresql_service/
|
||||
#
|
||||
|
||||
FROM ubuntu
|
||||
|
||||
RUN apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys B97B0AFCAA1A47F044F244A07FCC7D46ACCC4CF8
|
||||
|
||||
RUN echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main" > /etc/apt/sources.list.d/pgdg.list
|
||||
|
||||
RUN apt-get update && apt-get install -y python-software-properties software-properties-common postgresql-9.3 postgresql-client-9.3 postgresql-contrib-9.3
|
||||
|
||||
# Note: The official Debian and Ubuntu images automatically ``apt-get clean``
|
||||
# after each ``apt-get``
|
||||
|
||||
USER postgres
|
||||
|
||||
RUN /etc/init.d/postgresql start &&\
|
||||
psql --command "CREATE USER docker WITH SUPERUSER PASSWORD 'docker';" &&\
|
||||
createdb -O docker docker
|
||||
|
||||
RUN echo "host all all 0.0.0.0/0 md5" >> /etc/postgresql/9.3/main/pg_hba.conf
|
||||
|
||||
RUN echo "listen_addresses='*'" >> /etc/postgresql/9.3/main/postgresql.conf
|
||||
|
||||
EXPOSE 5432
|
||||
|
||||
VOLUME ["/etc/postgresql", "/var/log/postgresql", "/var/lib/postgresql"]
|
||||
|
||||
CMD ["/usr/lib/postgresql/9.3/bin/postgres", "-D", "/var/lib/postgresql/9.3/main", "-c", "config_file=/etc/postgresql/9.3/main/postgresql.conf"]
|
||||
```
|
||||
|
||||
### YAML
|
||||
|
||||
```yaml
|
||||
authorizedkeys:
|
||||
image: dockercloud/authorizedkeys
|
||||
deployment_strategy: every_node
|
||||
autodestroy: always
|
||||
environment:
|
||||
- AUTHORIZED_KEYS=ssh-rsa AAAAB3Nsomelongsshkeystringhereu9UzQbVKy9o00NqXa5jkmZ9Yd0BJBjFmb3WwUR8sJWZVTPFL
|
||||
volumes:
|
||||
/root:/user:rw
|
||||
```
|
||||
Reference in New Issue
Block a user