diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index e3bda7862a..c6126e512c 100644 --- a/CONTRIBUTING.md +++ b/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/). - -### 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. +[Contribution guidelines](/opensource/index.md). ### 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 diff --git a/Dockerfile b/Dockerfile index ab80d3bd1d..b42f3cabf3 100644 --- a/Dockerfile +++ b/Dockerfile @@ -63,6 +63,7 @@ RUN set -eu; \ sed -i 's#/#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#\(]* href="\)https://docs.docker.com/#\1/#g' "$i"; done; diff --git a/README.md b/README.md index 1ddf7e91e5..c9add850b5 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Docs @ Docker -Welcome to the repo for our documentation. This is the source for -[https://docs.docker.com/](https://docs.docker.com/). +Welcome to the repo for our documentation. 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! @@ -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) -- [Read these docs offline](#read-these-docs-offline) +- [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) @@ -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 - git clone --recursive https://github.com/docker/docker.github.io.git - cd docker.github.io - docker-compose up --build - ``` +Then build and run the documentation with [Docker Compose](https://docs.docker.com/compose/) - If you haven't got Docker Compose installed, - [follow these installation instructions](https://docs.docker.com/compose/install/). +```bash +docker-compose up -d --build +``` - The container runs in the background and incrementally rebuilds the site each - time a file changes. You can keep your browser open to http://localhost:4000/ - 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/). - ```bash - docker-compose down - ``` +Once the container is built and running, visit [http://localhost:4000](http://localhost:4000) +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 - DOCKER_BUILDKIT=1 docker build -t docker build -t docker-docs - docker run --rm -it -p 4000:4000 docker-docs - ``` +```bash +docker-compose up -d --build +``` - After the `docker run` command, copy the URL provided in the container build output in a browser, - http://0.0.0.0:4000, and verify your changes. +Once the container is built and running, visit [http://localhost:4000](http://localhost:4000) +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 - git clone --recursive https://github.com/docker/docker.github.io.git - ``` +```bash +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 - gem install bundler - ``` +- 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 - d. If you use Ubuntu, install packages required for the Nokogiri HTML - parser: +If you want to contribute in these areas, you can perform a "production" build +locally. - ```bash - sudo apt-get install ruby-dev zlib1g-dev liblzma-dev - ``` +To preview the documentation with deployment features enabled, you need to set the +`JEKYLL_ENV` environment variable when building the documentation; - e. Install Jekyll and other required dependencies: +```bash +JEKYLL_ENV=production docker-compose up --build +``` - ```bash - bundle install - ``` +Once the container is built and running, visit [http://localhost:4000](http://localhost:4000) +in your web browser to view the docs. - >**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. +To rebuild the docs after you make changes, repeat the steps above. + ## 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
  • TAB 1 HEADER
  • TAB 2 HEADER
    • @@ -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. diff --git a/_config_production.yml b/_config_production.yml index 71664640e0..31a1963c26 100644 --- a/_config_production.yml +++ b/_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 diff --git a/_includes/head.html b/_includes/head.html index 7ce01b8c36..e2ef8dd56e 100644 --- a/_includes/head.html +++ b/_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' -%} - {%- else -%} + {%- endif -%} + {%- if site.local_search -%} {%- endif -%}