Update README to cleanup build instructions

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

README.md

@@ -1,6 +1,6 @@
 # Docs @ Docker
-Welcome to the repo for our documentation. This is the source for	
+Welcome to the repo for our documentation. This is the source for
-[https://docs.docker.com/](https://docs.docker.com/).	
+[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!
@@ -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
+```
 
-    ```bash
+Then build and run the documentation with [Docker Compose](https://docs.docker.com/compose/)
-    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,
+```bash
-    [follow these installation instructions](https://docs.docker.com/compose/install/).
+docker-compose up -d --build
+```
 
-    The container runs in the background and incrementally rebuilds the site each
+> Docker Compose is included with [Docker Desktop](https://docs.docker.com/desktop/).
-    time a file changes. You can keep your browser open to http://localhost:4000/
+> If you don't have Docker Compose installed, [follow these installation instructions](https://docs.docker.com/compose/install/).
-    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:
 
-    ```bash
+Once the container is built and running, visit [http://localhost:4000](http://localhost:4000)
-    docker-compose down
+in your web browser to view the docs.
-    ```
 
-2. Build and run a Docker image for your working branch.
+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
+```bash
-   DOCKER_BUILDKIT=1 docker build -t docker build -t docker-docs
+docker-compose up -d --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.
 
-    a. Clone this repo by running:
+To stop the staging container, use the `docker-compose down` command:
 
-       ```bash
+```bash
-       git clone --recursive https://github.com/docker/docker.github.io.git
+docker-compose down
-       ```
+```
 
-    b. Install Ruby 2.3 or later as described in [Installing Ruby](https://www.ruby-lang.org/en/documentation/installation/).
+### Build the docs with deployment features enabled
 
-    c. Install Bundler:
+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:
 
-       ```bash
+- search auto-completion, and generation of `js/metadata.json`
-       gem install bundler
+- google analytics
-       ```
+- page ratings
+- `sitemap.xml` generation
+- minification of stylesheets (css/style.css)
+- adjusting "edit this page" links for content in other repositories
 
-    d. If you use Ubuntu, install packages required for the Nokogiri HTML
+If you want to contribute in these areas, you can perform a "production" build
-       parser:
+locally.
 
-       ```bash
+To preview the documentation with deployment features enabled, you need to set the
-       sudo apt-get install ruby-dev zlib1g-dev liblzma-dev
+`JEKYLL_ENV` environment variable when building the documentation;
-       ```
 
-    e. Install Jekyll and other required dependencies:
+```bash
+JEKYLL_ENV=production docker-compose up --build
+```
 
-       ```bash
+Once the container is built and running, visit [http://localhost:4000](http://localhost:4000)
-       bundle install
+in your web browser to view the docs.
-       ```
 
-       >**Note**: You may need to install some packages manually.
+To rebuild the docs after you make changes, repeat the steps above.
-
-    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.