Update README to cleanup build instructions

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

README.md

@@ -11,8 +11,8 @@ open source and we deeply appreciate contributions from our community!
   - [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 the docs locally](#build-the-docs-locally)
+- [Build and preview the docs locally](#build-and-preview-the-docs-locally)
-- [Read these docs offline](#read-these-docs-offline)
+  - [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)
@@ -82,86 +82,78 @@ the errors that prevented it from building. Review the staged site and amend you
 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 the docs locally
+## Build and preview the docs locally
 
-You have three options:
+On your local machine, clone this repo:
-
-1.  On your local machine, clone this repo and run our staging container:
 
 ```bash
 git clone --recursive https://github.com/docker/docker.github.io.git
 cd docker.github.io
-    docker-compose up --build
 ```
 
-    If you haven't got Docker Compose installed,
+Then build and run the documentation with [Docker Compose](https://docs.docker.com/compose/)
-    [follow these installation instructions](https://docs.docker.com/compose/install/).
 
-    The container runs in the background and incrementally rebuilds the site each
+```bash
-    time a file changes. You can keep your browser open to http://localhost:4000/
+docker-compose up -d --build
-    and refresh to see your changes. The container runs in the foreground, but
+```
-    you can use `CTRL+C` to get the command prompt back. To stop the container,
+
-    issue the following command:
+> 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
 ```
 
-2. Build and run a Docker image for your working branch.
+### Build the docs with deployment features enabled
+
+The default configuration for local builds of the documentation disables some
+features to allow for a shorter build-time. The following options differ between
+local builds, and builds that are deployed to docs.docker.com:
+
+- search auto-completion, and generation of `js/metadata.json`
+- google analytics
+- page ratings
+- `sitemap.xml` generation
+- minification of stylesheets (css/style.css)
+- adjusting "edit this page" links for content in other repositories
+
+If you want to contribute in these areas, you can perform a "production" build
+locally.
+
+To preview the documentation with deployment features enabled, you need to set the
+`JEKYLL_ENV` environment variable when building the documentation;
 
 ```bash
-   DOCKER_BUILDKIT=1 docker build -t docker build -t docker-docs
+JEKYLL_ENV=production docker-compose up --build
-   docker run --rm -it -p 4000:4000 docker-docs
 ```
 
-   After the `docker run` command, copy the URL provided in the container build output in a browser,
+Once the container is built and running, visit [http://localhost:4000](http://localhost:4000)
-   http://0.0.0.0:4000, and verify your changes.
+in your web browser to view the docs.
 
-3.  Install Jekyll and GitHub Pages on your local machine.
+To rebuild the docs after you make changes, repeat the steps above.
-
-    a. Clone this repo by running:
-
-       ```bash
-       git clone --recursive https://github.com/docker/docker.github.io.git
-       ```
-
-    b. Install Ruby 2.3 or later as described in [Installing Ruby](https://www.ruby-lang.org/en/documentation/installation/).
-
-    c. Install Bundler:
-
-       ```bash
-       gem install bundler
-       ```
-
-    d. If you use Ubuntu, install packages required for the Nokogiri HTML
-       parser:
-
-       ```bash
-       sudo apt-get install ruby-dev zlib1g-dev liblzma-dev
-       ```
-
-    e. Install Jekyll and other required dependencies:
-
-       ```bash
-       bundle install
-       ```
-
-       >**Note**: You may need to install some packages manually.
-
-    f. Change the directory to `docker.github.io`.
-
-    g. Use the `jekyll serve` command to continuously build the HTML output.
-
-    The `jekyll serve` process runs in the foreground, and starts a web server
-    running on http://localhost:4000/ by default. To stop it, use `CTRL+C`.
-    You can continue working in a second terminal and Jekyll will rebuild the
-    website incrementally. Refresh the browser to preview your changes.
 
+<!--
+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
+To see all available tags, go to [Docker Hub](https://docs.docker.com/docker-hub/).
-[Docker Hub](https://docs.docker.com/docker-hub/).
 
 The following examples use the `latest` tag:
 
@@ -180,6 +172,7 @@ The following examples use the `latest` tag:
   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
 
@@ -246,7 +239,7 @@ 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>
@@ -300,4 +293,4 @@ still optimizes the bandwidth during browsing).
 
 ## Copyright and license
 
-Code and documentation copyright 2017 Docker, inc, released under the Apache 2.0 license.
+Copyright 2013-2020 Docker, inc, released under the Apache 2.0 license.