diff --git a/README.md b/README.md index f7db9aceae..237e702993 100644 --- a/README.md +++ b/README.md @@ -1,295 +1,34 @@ # Docs @ Docker -Welcome to the repo for our documentation. This is the source for + +![Welcome to Docker Documentation](/images/docker-docs.png){:width="500px"} + +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){: target="_blank" rel="noopener" class="_"}. Personalized support is available through the Docker Pro, Team, and Business subscriptions. See [Docker Pricing](https://www.docker.com/pricing){: target="_blank" rel="noopener" class="_"} 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. - - - -## 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 `

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

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

` 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 `` 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 - -
-
TAB 1 CONTENT
-
TAB 2 CONTENT
-
-``` - -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 `