Merge pull request #11618 from thaJeztah/stub_search

Disable search auto-complete in dev environment, update README and CONTRIBUTING

CONTRIBUTING.md

@@ -7,15 +7,7 @@ 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.
 
 >**Note**: To contribute code to Docker projects, see the
-[Contribution guidelines](/opensource/).
+[Contribution guidelines](/opensource/index.md).
-
-### Files not edited here
-
-Files and directories listed in the `path:` keys in
-[`.NOT_EDITED_HERE.yaml`](/_data/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.
 
 ### Quickstart
 
@@ -47,46 +39,6 @@ there.
 >Do you enjoy creating graphics? Good graphics are key to great documentation,
 and we especially value contributions in this area.
 
-### Specific new features for a project
-
-Our docs cover many projects which release at different times. **If, and only if,
-your pull request relates to a currently unreleased feature of a project, base
-your work on that project's `vnext` branch.** These branches were created by
-cloning `master` and then importing a project's `master` branch's docs into it
-(at the time of the migration), in a way that preserved the commit history. When
-a project has a release, its `vnext` branch will be merged into `master` and your
-work will be visible on [https://docs.docker.com/](/).
-
-The following `vnext` branches currently exist:
-
-- **[vnext-engine](https://github.com/docker/docker.github.io/tree/vnext-engine):**
-  docs for upcoming features in the [docker/docker](https://github.com/moby/moby/)
-  project
-
-- **[vnext-compose](https://github.com/docker/docker.github.io/tree/vnext-compose):**
-  docs for upcoming features in the [docker/compose](https://github.com/docker/compose/)
-  project
-
-- **[vnext-distribution](https://github.com/docker/docker.github.io/tree/vnext-distribution):**
-  docs for upcoming features in the [docker/distribution](https://github.com/docker/distribution/)
-  project
-
-- **[vnext-opensource](https://github.com/docker/docker.github.io/tree/vnext-opensource):**
-  docs for upcoming features in the [docker/opensource](https://github.com/docker/opensource/)
-  project
-
-- **[vnext-swarm](https://github.com/docker/docker.github.io/tree/vnext-swarm):**
-  docs for upcoming features in the [docker/swarm](https://github.com/docker/swarm/)
-  project
-
-- **[vnext-toolbox](https://github.com/docker/docker.github.io/tree/vnext-toolbox):**
-  docs for upcoming features in the [docker/toolbox](https://github.com/docker/toolbox/)
-  project
-
-- **[vnext-kitematic](https://github.com/docker/docker.github.io/tree/vnext-kitematic):**
-  docs for upcoming features in the [docker/kitematic](https://github.com/docker/kitematic/)
-  project
-
 ## Collaborate on a pull request
 
 Unless the PR author specifically disables it, you can push commits into another

Dockerfile

@@ -63,6 +63,7 @@ RUN set -eu; \
     sed -i 's#<loc>/#<loc>https://docs.docker.com/#' "${TARGET}/sitemap.xml"; \
  else \
     jekyll build --profile -d ${TARGET}; \
+    echo '[]' > ${TARGET}/js/metadata.json; \
  fi; \
  find ${TARGET} -type f -name '*.html' | while read i; do sed -i 's#\(<a[^>]* href="\)https://docs.docker.com/#\1/#g' "$i"; done;
 

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
+```
 
-    ```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.

_config_production.yml

@@ -11,6 +11,9 @@ exclude: ["_scripts", "404.html", "index.html"]
 google_analytics: GTM-WL2QLG5
 polldaddy_id:     8453675
 
+# Enable search autocompletion (requires metadata.json to be generated)
+local_search: true
+
 plugins:
   - jekyll-redirect-from
   - jekyll-relative-links

_includes/head.html

@@ -54,18 +54,19 @@
   scripts happens once the HTML is fully parsed.
   see https://flaviocopes.com/javascript-async-defer/#with-defer-in-the-head
   {%- endcomment -%}
-  {%- if page.landing == true -%}
+  {%- if page.layout == 'landing' -%}
   <!-- landing page scripts -->
   <script defer src="/js/theme-switcher.js"></script>
   <script defer src="/js/jquery.js"></script>
   <script defer src="/js/bootstrap.min.js"></script>
-  <script defer src="/js/search.js"></script>
   {%- else -%}
   <script defer src="/js/theme-switcher.js"></script>
   <script defer src="/js/anchorlinks.js"></script>
   <script defer src="/js/jquery.js"></script>
   <script defer src="/js/bootstrap.min.js"></script>
   <script defer src="/js/docs.js"></script>
+  {%- endif -%}
+  {%- if site.local_search -%}
   <script defer src="/js/search.js"></script>
   {%- endif -%}