diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c6126e512c..6c42bf9966 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,43 +1,113 @@
-## Contributing
+# Contributing to Docker Documentation
 
-We value your documentation contributions, and we want to make it as easy
-as possible to work in this repository. One of the first things to decide is
-which branch to base your work on. If you get confused, just ask and we will
-help. If a reviewer realizes you have based your work on the wrong branch, we'll
-let you know so that you can rebase it.
+We deeply value documentation contributions from the Docker community. We'd like to make it as easy
+as possible for you to work in this repository. The documentation for Docker is published at [https://docs.docker.com/](https://docs.docker.com/). The following sections guide you through the process of contributing to Docker documentation.
 
->**Note**: To contribute code to Docker projects, see the
-[Contribution guidelines](/opensource/index.md).
+## Table of Contents
 
-### Quickstart
+- [Contribution guidelines](#contribution-guidelines)
+  - [Files not edited here](#files-not-edited-here)
+  - [Important files](#important-files)
+  - [Per-page front-matter](#per-page-front-matter)
+- [Pull request guidelines](#pull-request-guidelines)
+- [Collaborate on a pull request](#collaborate-on-a-pull-request)
+- [Per-PR staging on GitHub](#per-pr-staging-on-github)
+- [Relative linking for GitHub viewing](#relative-linking-for-github-viewing)
+- [Testing changes and practical guidance](#testing-changes-and-practical-guidance)
+  - [Creating tabs](#creating-tabs)
+  - [Running in-page Javascript](#running-in-page-javascript)
+  - [Images](#images)
+  - [Style guide](#style-guide)
+- [Build and preview the docs locally](#build-and-preview-the-docs-locally)
+  - [Build the docs with deployment features enabled](#build-the-docs-with-deployment-features-enabled)
+- [Copyright and license](#copyright-and-license)
 
-If you spot a problem while reading the documentation and want to try to fix it
-yourself, click the **Edit this page** link at the bottom of that page. The
-page will open in the Github editor, which means you don't need to know a lot
-about Git, or even about Markdown.
+## Contribution guidelines
 
-When you save, you will be prompted to create a fork if you don't already have
-one, and to create a branch in your fork and submit the pull request. We hope
-you give it a try!
+The live docs are published from the `master` branch. Therefore, you must create pull requests against the `master` branch for all content updates. This includes:
 
-### Overall doc improvements
-
-Most commits will be made against the `master` branch. This includes:
-
-- Conceptual and task-based information not specific to new features
+- Conceptual and task-based information
 - Restructuring / rewriting
 - Doc bug fixing
-- Typos and grammar errors
+- Fixing typos, broken links, and any grammar errors
 
-One quirk of this project is that the `master` branch is where the live docs are
-published from, so upcoming features can't be documented there. See
-[Specific new features for a project](#specific-new-features-for-a-project)
-for how to document upcoming features. These feature branches will be periodically
-merged with `master`, so don't worry about fixing typos and documentation bugs
-there.
+There are two ways to contribute a pull request to the docs repository:
 
->Do you enjoy creating graphics? Good graphics are key to great documentation,
-and we especially value contributions in this area.
+1. You can click **Edit this page** option  in the right column of every page on [https://docs.docker.com/](https://docs.docker.com/).
+
+    This opens the GitHub editor, which means you don't need to know a lot about Git, or even about Markdown. When you save, Git prompts you to create a fork if you don't already have one, and to create a branch in your fork and submit the pull request.
+
+2. Fork the [docs GitHub repository](https://github.com/docker/docker.github.io). Suggest changes or add new content on your local branch, and submit a pull request (PR) to the `master` branch.
+
+    This is the manual, more advanced version of clicking 'Edit this page' on a published docs page. Initiating a docs changes in a PR from your own branch gives you more flexibility, as you can submit changes to multiple pages or files under a single pull request, and even create new topics.
+
+    For a demo of the components, tags, Markdown syntax, styles, etc we use at [https://docs.docker.com/](https://docs.docker.com/), see [test.md](/test.md).
+
+### Important files
+
+Here’s a list of some of the important files:
+
+- `/_data/toc.yaml` defines the left-hand navigation for the docs
+- `/js/docs.js` defines most of the docs-specific JS such as the table of contents (ToC) generation and menu syncing
+- `/css/style.scss` defines the docs-specific style rules
+- `/_layouts/docs.html` is the HTML template file, which defines the header and footer, and includes all the JS/CSS that serves the docs content
+
+### Files not edited here
+
+Some files and directories are maintained in the upstream repositories. You can find a list of such files in [`_config_production.yml`](_config_production.yml#L52). Pull requests against these files will be rejected.
+
+### Per-page front-matter
+
+The front-matter of a given page is in a section at the top of the Markdown
+file that starts and ends with three hyphens. It includes YAML content. The
+following keys are supported. The title, description, and keywords are required.
+
+| Key                    | Required  | Description                             |
+|------------------------|-----------|-----------------------------------------|
+| title                  | yes       | The page title. This is added to the HTML output as a `<h1>` level header. |
+| description            | yes       | A sentence that describes the page contents. This is added to the HTML metadata. |
+| keywords               | yes       | A comma-separated list of keywords. These are added to the HTML metadata. |
+| redirect_from          | no        | A YAML list of pages which should redirect to the current page. At build time, each page listed here is created as an HTML stub containing a 302 redirect to this page. |
+| notoc                  | no        | Either `true` or `false`. If `true`, no in-page TOC is generated for the HTML output of this page. Defaults to `false`. Appropriate for some landing pages that have no in-page headings.|
+| toc_min                | no        | Ignored if `notoc` is set to `true`. The minimum heading level included in the in-page TOC. Defaults to `2`, to show `<h2>` headings as the minimum. |
+| toc_max                | no        | Ignored if `notoc` is set to `false`. The maximum heading level included in the in-page TOC. Defaults to `3`, to show `<h3>` headings. Set to the same as `toc_min` to only show `toc_min` level of headings. |
+| skip_read_time         | no        | Set to `true` to disable the 'Estimated reading time' banner for this page. |
+| sitemap                | no        | Exclude the page from indexing by search engines. When set to `false`, the page is excluded from `sitemap.xml`, and a `<meta name="robots" content="noindex"/>` header is added to the page. |
+
+Here's an example of a valid (but contrived) page metadata. The order of
+the metadata elements in the front-matter isn't important.
+
+```liquid
+---
+description: Instructions for installing Docker Engine on Ubuntu
+keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update
+title: Install Docker Engine on Ubuntu
+redirect_from:
+- /ee/docker-ee/ubuntu/
+- /engine/installation/linux/docker-ce/ubuntu/
+- /engine/installation/linux/docker-ee/ubuntu/
+- /engine/installation/linux/ubuntu/
+- /engine/installation/linux/ubuntulinux/
+- /engine/installation/ubuntulinux/
+- /install/linux/docker-ce/ubuntu/
+- /install/linux/docker-ee/ubuntu/
+- /install/linux/ubuntu/
+- /installation/ubuntulinux/
+toc_max: 4
+---
+```
+
+## Pull request guidelines
+
+Help us review your PRs more quickly by following these guidelines.
+
+- Try not to touch a large number of files in a single PR if possible.
+- Don't change whitespace or line wrapping in parts of a file you are not
+  editing for other reasons. Make sure your text editor is not configured to
+  automatically reformat the whole file when saving.
+- We highly recommend that you build the docs locally and verify your changes before submitting a PR. See the section [Build and preview the docs locally](#build-and-preview-the-docs-locally).
+- A Netlify test runs for each PR that is against the `master` branch, and deploys the result of your PR to a staging site. The URL will be available at in the **Conversation** tab. Check the staging site to verify how your changes look and fix issues, if necessary.
+- Use relative linking to link to other topics. See [Relative linking for GitHub viewing](#relative-linking-for-GitHub-viewing).
 
 ## Collaborate on a pull request
 
@@ -49,29 +119,138 @@ given file in the **Files** view.
 
 If a PR consists of multiple small addendum commits on top of a more significant
 one, the commit will usually be "squash-merged", so that only one commit is
-merged in. On occasion this is not appropriate and all commits will be kept
-separate when merging.
+merged into the `master` branch. In some scenarios where a squash and merge isn't appropriate, all commits are kept separate when merging.
 
-## Pull request guidelines
+## Per-PR staging on GitHub
 
-Help us review your PRs more quickly by following these guidelines.
+A Netlify test runs for each PR created against the `master` branch and deploys the result of your PR to a staging site. When the site builds successfully, you will see a comment in the **Conversation** tab in the PR stating **Deploy Preview for docsdocker ready!**. Click the **Browse the preview** URL and check the staging site to verify how your changes look and fix issues, if necessary. Reviewers also check the staged site before merging the PR to protect the integrity of the docs site.
 
-- Try not to touch a large number of files in a single PR if possible.
+## Relative linking for GitHub viewing
 
-- Don't change whitespace or line wrapping in parts of a file you are not
-  editing for other reasons. Make sure your text editor is not configured to
-  automatically reformat the whole file when saving.
+Feel free to link to `../foo.md` so that the docs are readable in GitHub, but keep in mind that Jekyll templating notation
+`{% such as this %}` renders in raw text and will not be processed. In general, it's best to assume the docs are being read
+directly on [https://docs.docker.com/](https://docs.docker.com/).
 
-- A Netlify test runs for each PR that is against one of our long-lived
-  branches like `master` and the `vnext` branches, and deploys the result of
-  your PR to a staging site. The URL will be available at the bottom of the PR
-  in the **Conversation** view. Check the staging site for problems and fix them
-  if necessary. Reviewers will check the staging site too.
+## Testing changes and practical guidance
 
-If you can think of other ways we could streamline the review process, let us
-know.
+If you want to test a style change, or if you want to see how to achieve a
+particular outcome with Markdown, Bootstrap, JQuery, or something else, have
+a look at `test.md` (which renders in the site at `/test/`).
 
-## Style guide
+### Creating tabs
 
-Docker does not currently maintain a style guide. Use your best judgment, and
-try to follow the example set by the existing documentation.
+The use of tabs, as on pages like [https://docs.docker.com/engine/api/](/engine/api/), requires the use of HTML. The tabs use Bootstrap CSS/JS, so refer to those docs for more advanced usage. For a basic horizontal tab set, copy/paste starting from this code and implement from there. Keep an eye on those `href="#id"` and `id="id"` references as you rename, add, and remove tabs.
+
+```html
+<ul class="nav nav-tabs">
+  <li class="active"><a data-toggle="tab" data-target="#tab1">TAB 1 HEADER</a></li>
+  <li><a data-toggle="tab" data-target="#tab2">TAB 2 HEADER</a></li>
+</ul>
+<div class="tab-content">
+  <div id="tab1" class="tab-pane fade in active">TAB 1 CONTENT</div>
+  <div id="tab2" class="tab-pane fade">TAB 2 CONTENT</div>
+</div>
+```
+
+For more info and a few more permutations, see [test.md](/test.md).
+
+### Running in-page Javascript
+
+If you need to run custom Javascript within a page, and it depends upon JQuery
+or Bootstrap, make sure the `<script>` tags are at the very end of the page,
+after all the content. Otherwise, the script may try to run before JQuery and
+Bootstrap JS are loaded.
+
+### Images
+
+Don't forget to remove images that are no longer used. Keep the images sorted
+in the local `images/` directory, with names that naturally group related images
+together in alphabetical order. For example,  use `settings-file-share.png`
+and `settings-proxies.png` instead of `file-share-settings.png` and
+`proxies-settings.png`.
+
+You may also use numbers, especially in the case of a
+sequence, for example, `run-only-the-images-you-trust-1.svg`,
+`run-only-the-images-you-trust-2.png`, `run-only-the-images-you-trust-3.png`.
+When applicable, capture windows rather than the rectangular regions. This
+eliminates unpleasant background and saves the editors the need to crop images.
+
+On Mac, capture windows without shadows. To do this, when  you press
+<kbd>Command-Shift-4</kbd>, press <kbd>Option</kbd> while clicking on the window. To disable shadows completely, run:
+
+```bash
+$ defaults write com.apple.screencapture disable-shadow -bool TRUE
+$ killall SystemUIServer  # restart it.
+```
+
+You can restore the shadows later using `-bool FALSE`.
+
+To keep the Git repository light, _please_ compress the images
+(losslessly). On Mac, you can use [ImageOptim](https://imageoptim.com) for
+instance. Be sure to compress the images **before** adding them to the
+repository. Compressing images after adding them to the repository actually worsens the impact on the Git repo (however, ut still optimizes the bandwidth during browsing).
+
+### Style guide
+
+Docker does not currently maintain a style guide. Follow the examples set by the existing documentation and use your best judgment.
+
+## Build and preview the docs locally
+
+On your local machine, clone the docs repository:
+
+```bash
+git clone --recursive https://github.com/docker/docker.github.io.git
+cd docker.github.io
+```
+
+Then, build and run the documentation using [Docker Compose](https://docs.docker.com/compose/)
+
+```bash
+docker compose up -d --build
+```
+
+> You need Docker Compose to build and run the docs locally. Docker Compose is included with [Docker Desktop](https://docs.docker.com/desktop/).
+> If you don't have Docker Desktop installed, follow the [instructions](https://docs.docker.com/compose/install/) to install Docker Compose.
+
+When the container is built and running, visit [http://localhost:4000](http://localhost:4000) in your web browser to view the docs.
+
+To rebuild the docs after you made changes, run the `docker compose up` command
+again. This rebuilds the docs, and updates the container with your changes:
+
+```bash
+docker compose up -d --build
+```
+
+To stop the staging container, use the `docker compose down` command:
+
+```bash
+docker compose down
+```
+
+### Build the docs with deployment features enabled
+
+The default configuration for local builds of the documentation disables some
+features to allow for a shorter build-time. The following options differ between
+local builds, and builds that are deployed to [docs.docker.com](https://docs.docker.com/):
+
+- search auto-completion, and generation of `js/metadata.json`
+- Google Analytics
+- page ratings
+- `sitemap.xml` generation
+- minification of stylesheets (`css/style.css`)
+- adjusting "edit this page" links for content in other repositories
+
+If you want to contribute in these areas, you can perform a "production" build
+locally. To preview the documentation with deployment features enabled, set the `JEKYLL_ENV` environment variable when building the documentation:
+
+```bash
+JEKYLL_ENV=production docker compose up --build
+```
+
+When the container is built and running, visit [http://localhost:4000](http://localhost:4000) in your web browser to view the docs.
+
+To rebuild the docs after you make changes, repeat the steps above.
+
+## Copyright and license
+
+Copyright 2013-2021 Docker, inc, released under the Apache 2.0 license.
diff --git a/README.md b/README.md
index f7db9aceae..ff7305c2b8 100644
--- a/README.md
+++ b/README.md
@@ -1,295 +1,47 @@
 # Docs @ Docker
-Welcome to the repo for our documentation. This is the source for
+
+<img src="images/docker-docs.png" alt="Welcome to Docker Documentation" style="max-width: 50%;">
+
+Welcome to the Docker Documentation repository. This is the source for
 [https://docs.docker.com/](https://docs.docker.com/).
 
-Feel free to send us pull requests and file issues. Our docs are completely	
-open source and we deeply appreciate contributions from our community!
-## Table of Contents
+Feel free to send us pull requests and file issues. Our docs are completely
+open source and we deeply appreciate contributions from the Docker community!
 
-- [Providing feedback](#providing-feedback)
-- [Contributing](#contributing)
-  - [Files not edited here](#files-not-edited-here)
-  - [Overall doc improvements](#overall-doc-improvements)
-- [Per-PR staging on GitHub](#per-pr-staging-on-github)
-- [Build and preview the docs locally](#build-and-preview-the-docs-locally)
-  - [Build the docs with deployment features enabled](#build-the-docs-with-deployment-features-enabled)
-- [Important files](#important-files)
-- [Relative linking for GitHub viewing](#relative-linking-for-github-viewing)
-  - [Testing changes and practical guidance](#testing-changes-and-practical-guidance)
-  - [Per-page front-matter](#per-page-front-matter)
-  - [Creating tabs](#creating-tabs)
-  - [Running in-page Javascript](#running-in-page-javascript)
-  - [Images](#images)
-- [Copyright and license](#copyright-and-license)
+## Provide feedback
 
+We’d love to hear your feedback. Please file documentation issues only in the
+docs GitHub repository. You can file a new issue to suggest improvements or if
+you see any errors in the existing documentation.
 
-## Providing feedback
+Before submitting a new issue, check whether the issue has already been
+reported. You can join the discussion using an emoji, or by adding a comment to
+an existing issue. If possible, we recommend that you suggest a fix to the issue
+by creating a pull request.
 
-We really want your feedback, and we've made it easy. You can edit a page or
-request changes in the right column of every page on
-[docs.docker.com](https://docs.docker.com/). You can also rate each page by
-clicking a link at the footer.
+You can ask general questions and get community support through the [Docker
+Community Slack](http://dockr.ly/slack). Personalized support is available
+through the Docker Pro, Team, and Business subscriptions. See [Docker
+Pricing](https://www.docker.com/pricing) for details.
 
-**Only file issues about the documentation in this repository.** One way
-to think about this is that you should file a bug here if your issue is that you
-don't see something that should be in the docs, or you see something incorrect
-or confusing in the docs.
+If you have an idea for a new feature or behavior change in a specific aspect of
+Docker, or have found a product bug, file that issue in the project's code
+repository.
 
-- If your problem is a general question about how to configure or use Docker,
-  ask in [https://forums.docker.com](https://forums.docker.com) instead.
+We've made it really easy for you to file new issues.
 
-- If you have an idea for a new feature or behavior change in a specific aspect
-  of Docker, or have found a bug in part of Docker, file that issue in
-  the project's code repository.
+- Click **New issue** on the docs repository and fill in the details, or
+- Click **Request docs changes** in the right column of every page on
+  docs.docker.com and add the details.
 
-## Contributing
+![Docs feedback on each page](/opensource/images/docs-site-feedback.png)
 
-We value your documentation contributions, and we want to make it as easy
-as possible to work in this repository. One of the first things to decide is
-which branch to base your work on. If you get confused, just ask and we will
-help. If a reviewer realizes you have based your work on the wrong branch, we'll
-let you know so that you can rebase it.
+## Contribute to Docker docs
 
->**Note**: To contribute code to Docker projects, see the
-[Contribution guidelines](CONTRIBUTING.md).
-
-### Files not edited here
-
-Files and directories listed in the `path:` keys in
-[`.NOT_EDITED_HERE.yaml`](.NOT_EDITED_HERE.yaml) are maintained in other
-repositories and should not be edited in this one. Pull requests against these
-files will be rejected. Make your edits to the files in the repository and path
-in the `source:` key in the YAML file.
-
-### Overall doc improvements
-
-Pull requests should be opened against the `master` branch, this includes:
-
-- Conceptual and task-based information not specific to new features
-- Restructuring / rewriting
-- Doc bug fixing
-- Typos and grammar errors
-
-> Do you enjoy creating graphics? Good graphics are key to great documentation,
-> and we especially value contributions in this area.
-
-## Per-PR staging on GitHub
-
-For every PR against `master`, a staged version of the site is built using Netlify.
-If the site builds, you will see **deploy/netlify — Deploy preview ready**.
-Otherwise, you will see an error. Click **Details** to review the staged site or
-the errors that prevented it from building. Review the staged site and amend your
-commit if necessary. Reviewers will also check the staged site before merging the
-PR, to protect the integrity of [https://docs.docker.com/](https://docs.docker.com/).
-
-## Build and preview the docs locally
-
-On your local machine, clone this repo:
-
-```bash
-git clone --recursive https://github.com/docker/docker.github.io.git
-cd docker.github.io
-```
-
-Then build and run the documentation with [Docker Compose](https://docs.docker.com/compose/)
-
-```bash
-docker-compose up -d --build
-```
-
-> Docker Compose is included with [Docker Desktop](https://docs.docker.com/desktop/).
-> If you don't have Docker Compose installed, [follow these installation instructions](https://docs.docker.com/compose/install/).
-
-Once the container is built and running, visit [http://localhost:4000](http://localhost:4000)
-in your web browser to view the docs.
-
-To rebuild the docs after you made changes, run the `docker-compose up` command
-again. This rebuilds the documentation, and updates the container with your changes:
-
-```bash
-docker-compose up -d --build
-```
-
-Once the container is built and running, visit [http://localhost:4000](http://localhost:4000)
-in your web browser to view the docs.
-
-
-To stop the staging container, use the `docker-compose down` command:
-
-```bash
-docker-compose down
-```
-
-### Build the docs with deployment features enabled
-
-The default configuration for local builds of the documentation disables some
-features to allow for a shorter build-time. The following options differ between
-local builds, and builds that are deployed to [docs.docker.com](https://docs.docker.com/):
-
-- search auto-completion, and generation of `js/metadata.json`
-- google analytics
-- page ratings
-- `sitemap.xml` generation
-- minification of stylesheets (`css/style.css`)
-- adjusting "edit this page" links for content in other repositories
-
-If you want to contribute in these areas, you can perform a "production" build
-locally.
-
-To preview the documentation with deployment features enabled, you need to set the
-`JEKYLL_ENV` environment variable when building the documentation;
-
-```bash
-JEKYLL_ENV=production docker-compose up --build
-```
-
-Once the container is built and running, visit [http://localhost:4000](http://localhost:4000)
-in your web browser to view the docs.
-
-To rebuild the docs after you make changes, repeat the steps above.
-
-<!--
-TODO re-enable auto-builds, or push master builds to Docker hub
-## Read these docs offline
-
-To read the docs offline, you can use either a standalone container or a swarm service.
-To see all available tags, go to [Docker Hub](https://docs.docker.com/docker-hub/).
-
-The following examples use the `latest` tag:
-
-- Run a single container:
-
-  ```bash
-  docker run  -it -p 4000:4000 docs/docker.github.io:latest
-  ```
-
-- Run a swarm service:
-
-  ```bash
-  docker service create -p 4000:4000 --name localdocs --replicas 1 docs/docker.github.io:latest
-  ```
-
-  This example uses only a single replica, but you could run as many replicas as you'd like.
-
-Either way, you can now access the docs at port 4000 on your Docker host.
--->
-
-## Important files
-
-- `/_data/toc.yaml` defines the left-hand navigation for the docs
-- `/js/docs.js` defines most of the docs-specific JS such as TOC generation and menu syncing
-- `/css/style.scss` defines the docs-specific style rules
-- `/_layouts/docs.html` is the HTML template file, which defines the header and footer, and includes all the JS/CSS that serves the docs content
-
-## Relative linking for GitHub viewing
-
-Feel free to link to `../foo.md` so that the docs are readable in GitHub, but keep in mind that Jekyll templating notation
-`{% such as this %}` will render in raw text and not be processed. In general it's best to assume the docs are being read
-directly on [https://docs.docker.com/](https://docs.docker.com/).
-
-### Testing changes and practical guidance
-
-If you want to test a style change, or if you want to see how to achieve a
-particular outcome with Markdown, Bootstrap, JQuery, or something else, have
-a look at `test.md` (which renders in the site at `/test/`).
-
-### Per-page front-matter
-
-The front-matter of a given page is in a section at the top of the Markdown
-file that starts and ends with three hyphens. It includes YAML content. The
-following keys are supported. The title, description, and keywords are required.
-
-| Key                    | Required  | Description                             |
-|------------------------|-----------|-----------------------------------------|
-| title                  | yes       | The page title. This is added to the HTML output as a `<h1>` level header. |
-| description            | yes       | A sentence that describes the page contents. This is added to the HTML metadata. |
-| keywords               | yes       | A comma-separated list of keywords. These are added to the HTML metadata. |
-| redirect_from          | no        | A YAML list of pages which should redirect to THIS page. At build time, each page listed here is created as a HTML stub containing a 302 redirect to this page. |
-| notoc                  | no        | Either `true` or `false`. If `true`, no in-page TOC is generated for the HTML output of this page. Defaults to `false`. Appropriate for some landing pages that have no in-page headings.|
-| toc_min                | no        | Ignored if `notoc` is set to `true`. The minimum heading level included in the in-page TOC. Defaults to `2`, to show `<h2>` headings as the minimum. |
-| toc_max                | no        | Ignored if `notoc` is set to `false`. The maximum heading level included in the in-page TOC. Defaults to `3`, to show `<h3>` headings. Set to the same as `toc_min` to only show `toc_min` level of headings. |
-| no_ratings             | no        | Either `true` or `false`. Set to `true` to disable the page-ratings applet for this page. Defaults to `false`. |
-| skip_read_time         | no        | Set to `true` to disable the 'Estimated reading time' banner for this page. |
-| sitemap                | no        | Exclude the page from indexing by search engines. When set to `false`, the page is excluded from `sitemap.xml`, and a `<meta name="robots" content="noindex"/>` header is added to the page. |
-
-The following is an example of valid (but contrived) page metadata. The order of
-the metadata elements in the front-matter is not important.
-
-```liquid
----
-description: Instructions for installing Docker on Ubuntu
-keywords: requirements, apt, installation, ubuntu, install, uninstall, upgrade, update
-redirect_from:
-- /engine/installation/ubuntulinux/
-- /installation/ubuntulinux/
-- /engine/installation/linux/ubuntulinux/
-title: Get Docker for Ubuntu
-toc_min: 1
-toc_max: 6
-skip_read_time: true
-no_ratings: true
----
-```
-
-### Creating tabs
-
-The use of tabs, as on pages like [https://docs.docker.com/engine/api/](/engine/api/), requires
-the use of HTML. The tabs use Bootstrap CSS/JS, so refer to those docs for more
-advanced usage. For a basic horizontal tab set, copy/paste starting from this
-code and implement from there. Keep an eye on those `href="#id"` and `id="id"`
-references as you rename, add, and remove tabs.
-
-```html
-<ul class="nav nav-tabs">
-  <li class="active"><a data-toggle="tab" data-target="#tab1">TAB 1 HEADER</a></li>
-  <li><a data-toggle="tab" data-target="#tab2">TAB 2 HEADER</a></li>
-</ul>
-<div class="tab-content">
-  <div id="tab1" class="tab-pane fade in active">TAB 1 CONTENT</div>
-  <div id="tab2" class="tab-pane fade">TAB 2 CONTENT</div>
-</div>
-```
-
-For more info and a few more permutations, see `test.md`.
-
-### Running in-page Javascript
-
-If you need to run custom Javascript within a page, and it depends upon JQuery
-or Bootstrap, make sure the `<script>` tags are at the very end of the page,
-after all the content. Otherwise the script may try to run before JQuery and
-Bootstrap JS are loaded.
-
-> **Note**: In general, this is a bad idea.
-
-### Images
-
-Don't forget to remove images that are no longer used. Keep the images sorted
-in the local `images/` directory, with names that naturally group related images
-together in alphabetical order. For instance prefer `settings-file-share.png`
-and `settings-proxies.png` to `file-share-settings.png` and
-`proxies-settings.png`. You may also use numbers, especially in the case of a
-sequence, e.g., `run-only-the-images-you-trust-1.svg`
-`run-only-the-images-you-trust-2.png` `run-only-the-images-you-trust-3.png`.
-
-When applicable, capture windows rather than rectangular regions. This
-eliminates unpleasant background and saves the editors the need to crop.
-
-On Mac, capture windows without shadows. To this end, once you pressed
-<kbd>Command-Shift-4</kbd>, press <kbd>Option</kbd> while clicking on the window. To disable
-shadows once for all, run:
-
-```bash
-$ defaults write com.apple.screencapture disable-shadow -bool TRUE
-$ killall SystemUIServer  # restart it.
-```
-
-You can restore shadows later with `-bool FALSE`.
-
-In order to keep the Git repository light, _please_ compress the images
-(losslessly). On Mac you may use [ImageOptim](https://imageoptim.com) for
-instance. Be sure to compress the images *before* adding them to the
-repository, doing it afterwards actually worsens the impact on the Git repo (but
-still optimizes the bandwidth during browsing).
+We value your contribution. We'd like to make it as easy as possible to submit
+your contributions to the Docker docs repository. Changes to the docs are
+handled through pull requests against the `master` branch. To learn how to
+contribute, see [CONTRIBUTING.md](CONTRIBUTING.md).
 
 ## Copyright and license
 
diff --git a/_data/toc.yaml b/_data/toc.yaml
index 57ce133831..f93f2c4cda 100644
--- a/_data/toc.yaml
+++ b/_data/toc.yaml
@@ -373,14 +373,8 @@ guides:
         title: Use the VFS storage driver
 - path: /get-started/resources/
   title: "Educational resources"
-- sectiontitle: Open source at Docker
-  section:
-  - path: /opensource/
-    title: Contribute to documentation
-  - path: /opensource/ways/
-    title: Other ways to contribute
-- path: /docsarchive/
-  title: Documentation archive
+- path: /opensource/
+  title: "Contribute to documentation"
 reference:
 - path: /reference/
   title: Reference documentation
diff --git a/images/docker-docs.png b/images/docker-docs.png
new file mode 100644
index 0000000000..89bebf552c
Binary files /dev/null and b/images/docker-docs.png differ
diff --git a/images/important-admonition-example.png b/images/important-admonition-example.png
deleted file mode 100644
index d684806803..0000000000
Binary files a/images/important-admonition-example.png and /dev/null differ
diff --git a/images/note-admonition-example.png b/images/note-admonition-example.png
deleted file mode 100644
index 1c8df9a253..0000000000
Binary files a/images/note-admonition-example.png and /dev/null differ
diff --git a/images/warning-admonition-example.png b/images/warning-admonition-example.png
deleted file mode 100644
index ec897db6c0..0000000000
Binary files a/images/warning-admonition-example.png and /dev/null differ
diff --git a/opensource/images/docs-site-feedback.png b/opensource/images/docs-site-feedback.png
index 97db5f45f4..19aa7a666f 100644
Binary files a/opensource/images/docs-site-feedback.png and b/opensource/images/docs-site-feedback.png differ
diff --git a/opensource/index.md b/opensource/index.md
index d93c9aae7f..9205200578 100644
--- a/opensource/index.md
+++ b/opensource/index.md
@@ -1,6 +1,6 @@
 ---
-description: Overview of contributing
-keywords: open, source, contributing, overview
+description: Contribute to Docker documentation
+keywords: Docker documentation, contributing, overview
 title: Contribute to documentation
 redirect_from:
 - /contributing/
@@ -34,75 +34,46 @@ redirect_from:
 
 Contributing to the Docker documentation can be a rewarding experience. When you
 offer feedback, questions, edits, or new content, you help us, the projects you
-work on, and the larger Docker community.
+work on, and the larger Docker community. Feel free to create pull requests and
+file issues. Our docs are completely open source and we deeply appreciate
+contributions from the Docker community!
 
-We welcome your participation to help make the documentation better!
+## Provide feedback
 
-> Looking for the open source Moby project?
->
-> See [Looking for Moby?](#looking-for-moby) below.
+We’d love to hear your feedback. Please file documentation issues only in the
+docs GitHub repository. You can file a new issue to suggest improvements or if
+you see any errors in the existing documentation.
 
-## How to contribute to the docs
+Before submitting a new issue, check whether the issue has already been
+reported. You can join the discussion using an emoji, or by adding a comment to
+an existing issue. If possible, we recommend that you suggest a fix to the issue
+by creating a pull request.
 
-The documentation for Docker is published at
-[docs.docker.com](https://docs.docker.com/).
+You can ask general questions and get community support through the [Docker
+Community Slack](http://dockr.ly/slack). Personalized support is available
+through the Docker Pro, Team, and Business subscriptions. See [Docker
+Pricing](https://www.docker.com/pricing) for details.
 
-There are many ways to contribute:
+If you have an idea for a new feature or behavior change in a specific aspect of
+Docker, or have found a product bug, file that issue in the project's code
+repository.
 
-- Edit, rate, or file an issue or question directly on the site by
-using the links available on the right-side menu on every page
-at [docs.docker.com](/).
+We've made it really easy for you to file new issues.
 
-  ![Docs feedback links](images/docs-site-feedback.png)
+- Click **New issue** on the docs repository and fill in the details, or
+- Click **Request docs changes** in the right column of every page on
+  docs.docker.com and add the details.
 
-- File a documentation issue on GitHub at
-[https://github.com/docker/docker.github.io/issues](https://github.com/docker/docker.github.io/issues).
+![Docs feedback on each page](/opensource/images/docs-site-feedback.png)
 
-  This is similar to clicking **Request doc changes** on a published docs
-  page, but if you manually file an issue you need to fill in links to
-  the related pages.
+## Contribute to Docker docs
 
-- Fork the documentation, make changes or add new content on your local
-branch, and submit a pull request (PR) to the master branch for the docs.
+We value your contribution. We'd like to make it as easy as possible to submit
+your contributions to the Docker docs repository. Changes to the docs are
+handled through pull requests against the `master` branch. To learn how to
+contribute, see
+[CONTRIBUTING.md](https://github.com/docker/docker.github.io/blob/master/CONTRIBUTING.md).
 
-  This is the manual, more advanced version of clicking **Edit this page**
-  on a published docs page. Initiating a docs changes in a PR from your
-  own branch gives you more flexibility, as you can submit changes to
-  multiple pages or files under a single pull request, and even create
-  new topics.
-
-## Resources and guidance
-
-We are here to help. If you are interested in contributing, but don't feel ready
-to dive in on more complex updates, we can help get you up and running.
-
-You might start by using the right-side menus on published pages:
-
-* Click **Request doc changes** on a page to automatically log an issue.
-
-* Click **Edit this page** to make a change to content, which automatically creates a PR.
-
-The issue and PR pages on GitHub give us a community space to discuss
-things, and answer any questions you might have about the problem or topic you
-are reporting on.
-
-To learn more about working on the documentation, see these topics:
-
-- [README on docker/docker.github.io](https://github.com/docker/docker.github.io/blob/master/README.md)
-
-- [Docs Test page](../test.md) - This is on the
-published site. It explains how to use Docs components, resources, and
-formats, and gives us a way to test and demo them.
-
-## Looking for meetups and Docker Community?
-
-Go to the [Docker Community GitHub repository](https://github.com/docker/community/blob/master/README.md){:target="_blank" rel="noopener" class="_"}
-for resources and information on the community.
-
-The topics in this guide on [Other ways to contribute](/opensource/ways/)
-provide some additional information,  but the community
-information you are looking for is probably available on the GitHub repository.
-
-## Looking for Moby?
-
-{% include content/moby.md %}
+For a demo of the components, tags, Markdown syntax, styles, used in Docker
+documentation, see
+[test.md](https://github.com/docker/docker.github.io/blob/master/test.md).
diff --git a/test.md b/test.md
index f727545699..dbda9d3f08 100644
--- a/test.md
+++ b/test.md
@@ -37,7 +37,7 @@ topics).
 By default, this is the highest heading included in the right navigation bar. To
 include more heading levels, set `toc_min: 1` in the page's front-matter (as is
 done on this `test.md` page). You can go all the way to 6, but if `toc_min` is
-geater than `toc_max` then no headings are shown.
+greater than `toc_max` then no headings are shown.
 
 ### Heading 3
 
@@ -91,7 +91,6 @@ culpa qui officia deserunt mollit anim id est laborum.
 ### Links
 
 - [a markdown link](https://docker.com/)
-https://github.com/docker/docker.github.io/tree/master/docker-cloud/images
 - [a markdown link that opens in a new window](https://docker.com/){: target="_blank" rel="noopener" class="_" }
   (the `class="_"` trick prevents Atom from italicizing the whole rest of the file until it encounters another underscore.)
 
@@ -113,7 +112,7 @@ https://github.com/docker/docker.github.io/tree/master/docker-cloud/images
   - If you can't find a reference page in the `docker.github.io`
   GitHub repository, but see it out on `docs.docker.com`, you can
   surmise that it's probably auto-generated from the codebase.
-  (FYI, to view the markdown source for the file, just click
+  (FYI, to view the Markdown source for the file, just click
   **Edit this page** on `docs.docker.com`. But don't use that URL in your docs.)
 
   - Go to the file in a web browser, grab everything after the domain name
@@ -125,6 +124,7 @@ https://github.com/docker/docker.github.io/tree/master/docker-cloud/images
 {: id="custom-target-id"}
 
 #### Using a custom target ID
+
 This topic has a custom target ID above its heading that can be used to link to
 it, in addition to, or instead of, the default concatenated heading style. The
 format of this ID is `{: id="custom-target-id"}`.
@@ -135,7 +135,7 @@ target.
 
 An example of a custom target ID in the documentation is the topic on
 [Compose file version 2 topic on CPU and other resources](compose/compose-file/compose-file-v2.md#cpu-and-other-resources).
-It has a long heading that breaks the normal markdown linking mechanism,
+It has a long heading that breaks the normal Markdown linking mechanism,
 so we added a custom ID above the target heading.
 
 ### Images
@@ -151,7 +151,7 @@ so we added a custom ID above the target heading.
 
 - The same as above but using HTML: <img src="/images/banner_image_24512.png" alt="a pretty wide image using HTML"/>
 
-[Some Bootstrap image classes](https://v4-alpha.getbootstrap.com/content/images/)
+[Some Bootstrap image classes](https://getbootstrap.com/docs/3.4/css/#images){: target="_blank" rel="noopener" class="_" }
 might be interesting. You can use them with Markdown or HTML images.
 
 - An image using the Bootstrap "thumbnail" class: ![an image as a thumbnail](/images/footer_moby_icon.png){: class="img-thumbnail" }
@@ -160,7 +160,16 @@ might be interesting. You can use them with Markdown or HTML images.
 
 ## Videos
 
-You can add a link to a YouTube video like this:
+To embed a YouTube video on a docs page, open the video on YouTube, click
+**Share** > **Embed** and then copy the code displayed.
+
+For example, the video embedded on the Get Started page has the following code:
+
+```html
+<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/iqqDU2crIEQ?start=30" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
+```
+
+You can also add a link to a YouTube video like this:
 
 [Docker 101: Introduction to Docker](https://www.youtube.com/watch?v=V9IJj4MzZBc "Docker 101: Introduction to Docker"){:target="_blank" rel="noopener" class="_"}
 
@@ -205,7 +214,6 @@ For the overlay, you can use the play button at
           | Thing 1 | Thing 2  |
           | Thing 3 | Thing 4  |
 
-
 ## Tables
 
 Some tables in markdown and html.
@@ -216,7 +224,7 @@ Some tables in markdown and html.
 |                                                                          | Previous cell is empty. A `--flag` in mono text.             |
 | Read                                                                     | Pull                                                         |
 | Read/Write                                                               | Pull, push                                                   |
-| Admin                                                                    | All of the above, plus update description, create and delete |
+| Admin                                                                    | All of the above, plus update description, create, and delete |
 
 The alignment of the cells in the source doesn't really matter. The ending pipe
 character is optional (unless the last cell is supposed to be empty). The header
@@ -318,12 +326,6 @@ You can nest captures within each other to represent more complex logic with Liq
 - In-line variables set via `assign` or `capture` are available for the remainder of the page after they are set.
 - If you include a file, you can pass key-value pairs at the same time. These are available as include variables, like `{{ include.toc_min }}`.
 
-### Image formatting
-
-This image was originally created on a white background and converted to a transparent background (or so it seems). In night-mode, the text still shows traces of the white and looks garbled. To fix this, we apply a white background inline with a class defined in _scss/_night-mode.css (and incorporated into style.css): `img.white-bg { background-color: white; }`.
-
-![alt_text](https://github.com/docker/docker.github.io/blob/423f6d58b2f301d01163241099f0346f2ecf1019/machine/img/provision-use-case.png){: .white-bg}
-
 ## Bootstrap and CSS tricks
 
 Here are cool components you can include on Docs pages using
@@ -356,6 +358,7 @@ as an attribute in the HTML for the `<div>` so that Kramdown renders it.
 </ul>
 <div class="tab-content">
 <div id="tab3" class="tab-pane fade in active" markdown="1">
+
 #### A Markdown header
 
 - list item 1
@@ -363,6 +366,7 @@ as an attribute in the HTML for the `<div>` so that Kramdown renders it.
 <hr>
 </div>
 <div id="tab4" class="tab-pane fade" markdown="1">
+
 #### Another Markdown header
 
 - list item 3
@@ -402,7 +406,6 @@ And some content between the two sets, just for fun...
   <div id="python-2" class="tab-pane fade in">Python content here<hr></div>
 </div>
 
-
 ### Cards
 
 In a Bootstrap row, your columns need to add up to 12. Here are three cards in
@@ -460,30 +463,31 @@ to see another example.
 $ docker run hello-world
 Unable to find image 'hello-world:latest' locally
 latest: Pulling from library/hello-world
-b04784fba78d: Pull complete
-Digest: sha256:f3b3b28a45160805bb16542c9531888519430e9e6d6ffc09d72261b0d26ff74f
+2db29710123e: Pull complete
+Digest: sha256:cc15c5b292d8525effc0f89cb299f1804f3a725c8d05e158653a563f15e4f685
 Status: Downloaded newer image for hello-world:latest
 
 Hello from Docker!
 This message shows that your installation appears to be working correctly.
 
 To generate this message, Docker took the following steps:
- 1. The Docker client contacted the Docker daemon.
- 2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
- 3. The Docker daemon created a new container from that image which runs the
-    executable that produces the output you are currently reading.
- 4. The Docker daemon streamed that output to the Docker client, which sent it
+
+1. The Docker client contacted the Docker daemon.
+2. The Docker daemon pulled the "hello-world" image from the Docker Hub.
+    (amd64)
+3. The Docker daemon created a new container from that image which runs the
+4. The Docker daemon streamed that output to the Docker client, which sent it
     to your terminal.
 
 To try something more ambitious, you can run an Ubuntu container with:
- $ docker run -it ubuntu bash
+
+$ docker run -it ubuntu bash
 
 Share images, automate workflows, and more with a free Docker ID:
  https://hub.docker.com/
 
 For more examples and ideas, visit:
- https://docs.docker.com/engine/userguide/
-
+ https://docs.docker.com/get-started/
 </code></pre>
     </div>
     <div class="panel-heading collapsed" data-toggle="collapse" data-target="#collapseSample2"  style="cursor: pointer"> Another Sample <i class="chevron fa fa-fw"></i></div>
@@ -578,15 +582,13 @@ or Bootstrap, make sure the `<script>` tags are at the very end of the page,
 after all the content. Otherwise the script may try to run before JQuery and
 Bootstrap JS are loaded.
 
-> **Note**: In general, this is a bad idea.
-
 ## Admonitions (notes)
 
 Current styles for admonitions in
 [`_scss/_notes.scss`](https://github.com/docker/docker.github.io/blob/master/_scss/_notes.scss)
 support these broad categories of admonitions:
 
-- Notes (no Liquid tag required) (deprecated)
+- Notes (no Liquid tag required)
 - Important, which use the `{: .important}` tag
 - Warning , which use the `{: .warning}` tag
 
@@ -597,13 +599,11 @@ notes in your published documents are not adversely affected.
 
 Examples are shown in the following sections.
 
-### Note (Deprecated)
-
-Notes are deprecated and should not longer be used. Use important or warning instead.
+### Note
 
 A standard note is formatted like this:
 
-```
+```markdown
 > Handling transient errors
 >
 > Note the way the `get_hit_count` function is written. This basic retry
@@ -615,38 +615,50 @@ A standard note is formatted like this:
 > nodes.
 ```
 
-It renders like this with a colored sidebar and icon:
+A note renders as follows:
 
-![note admonition example](/images/note-admonition-example.png)
+  > Handling transient errors
+  >
+  > Note the way the `get_hit_count` function is written. This basic retry
+  > loop lets us attempt our request multiple times if the redis service is
+  > not available. This is useful at startup while the application comes
+  > online, but also makes our application more resilient if the Redis
+  > service needs to be restarted anytime during the app's lifetime. In a
+  > cluster, this also helps handling momentary connection drops between
+  > nodes.
 
-Notes were previously formatted like this:
+Notes are also formatted like this:
 
+```markdown
+> **Note**
+>
+> This is another way to format a note.
 ```
-> **Note**: This is a note using the old note style.
-```
-
-These will still render as a note with a colored sidebar to the left but no icon will be added.
 
 ### Important
 
 Add the `important` class to your blockquotes if you want to tell users to be careful about something:
 
-```
+```markdown
 > Pssst, wanna know something?
 >
 > You include a small description here telling users to be on the lookout
 {: .important}
 ```
 
-It renders like this  with a colored sidebar and icon:
+The 'important' class renders as follows:
 
-![important admonition example](/images/important-admonition-example.png)
+> **Important**
+>
+> Treat access tokens like your password and keep them secret. Store your
+> tokens securely (for example, in a credential manager).
+{: .important}
 
 ### Warning
 
 Use the `warning` class to let people know this is dangerous or they should pay close attention to this part of the road before moving on:
 
-```
+```markdown
 > Ouch, don't do that!
 >
 > Sticking your finger in an electrical outlet can result in an electric shock.
@@ -655,9 +667,18 @@ Use the `warning` class to let people know this is dangerous or they should pay
 {: .warning}
 ```
 
-It will render like this  with a colored sidebar and icon:
+The 'warning' class renders as follows:
 
-![warning admonition example](/images/warning-admonition-example.png)
+> **Warning**
+>
+> Removing Volumes
+>
+> By default, named volumes in your compose file are NOT removed when running
+> `docker-compose down`. If you want to remove the volumes, you will need to add
+> the `--volumes` flag.
+>
+> The Docker Dashboard does _not_ remove volumes when you delete the app stack.
+{: .warning}
 
 ## Upgrade CTA
 
@@ -778,7 +799,7 @@ syntax for comments in JSON!
 
 ### Markdown
 
-```md
+```markdown
 # Hello
 ```