docker
/
docs
mirror of https://github.com/docker/docs.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

chore: quick refresh of the contribution guidelines 

Just a quick pass to fix some obvious issues

Signed-off-by: David Karlsson <35727626+dvdksn@users.noreply.github.com>
This commit is contained in:
David Karlsson 2023-10-13 21:15:13 +02:00
parent d4a743db31
commit e02dcae84b
7 changed files with 53 additions and 100 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
content/contribute/components/badges.md
View File

@ -20,4 +20,5 @@ You can also make a badge a link.
```go ```go
{{</* badge color=amber text="amber badge" */>}} {{</* badge color=amber text="amber badge" */>}}
``` [{{</* badge color="blue" text="badge with a link" */>}}](../overview.md)
```

23
content/contribute/components/images.md
View File

@ -8,20 +8,33 @@ toc_max: 3
- A small image: ![a small image](/assets/images/footer_moby_icon.png) - A small image: ![a small image](/assets/images/footer_moby_icon.png)
- Images will by default occupy the full width of the reading column, if they are big enough: - Large images occupy the full width of the reading column by default:
![a pretty wide image](/assets/images/banner_image_24512.png) ![a pretty wide image](/assets/images/banner_image_24512.png)
- Image size can be set using URL query parameters: ![a pretty wide image](/assets/images/banner_image_24512.png?w=100&h=50) - Image size can be set using query parameters: `?h=<height>&w=<width>`
![a pretty wide image](/assets/images/banner_image_24512.png?w=100&h=50)
- Image with a border, also set with a query parameter: `?border=true`
![a small image](/assets/images/footer_moby_icon.png?border=true)
## HTML and Markdown ## HTML and Markdown
```markdown ```markdown
- A small image: ![a small image](/assets/images/footer_moby_icon.png) - A small image: ![a small image](/assets/images/footer_moby_icon.png)
- Images will by default occupy the full width of the reading column, if they are big enough: - Large images occupy the full width of the reading column by default:
![a pretty wide image](/assets/images/banner_image_24512.png) ![a pretty wide image](/assets/images/banner_image_24512.png)
- Image size can be set using URL query parameters (`h` and `w`): ![a pretty wide image](/assets/images/banner_image_24512.png?w=100&h=50) - Image size can be set using query parameters: `?h=<height>&w=<width>`
```
![a pretty wide image](/assets/images/banner_image_24512.png?w=100&h=50)
- Image with a border, also set with a query parameter: `?border=true`
![a small image](/assets/images/footer_moby_icon.png?border=true)
```

2
content/contribute/components/lists.md
View File

@ -76,4 +76,4 @@ Use dashes (`-`) or asterisks (`*`) for bullet points.
| -------- | -------- | | -------- | -------- |
| Thing 1 | Thing 2 | | Thing 1 | Thing 2 |
| Thing 3 | Thing 4 | | Thing 3 | Thing 4 |
```` ````

40
content/contribute/components/tooltips.md
View File

@ -1,40 +0,0 @@
---
description: components and formatting examples used in Docker's docs
title: Tooltips
toc_max: 3
---
Tooltips aren't visible on mobile devices or touchscreens, so don't rely on them as the
only way to communicate important info.
## Examples
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="left" title="Tooltip on left">Tooltip on left</button>
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="top" title="Tooltip on top">Tooltip on top</button>
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">Tooltip on bottom</button>
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="right" title="Tooltip on right">Tooltip on right</button>
This is a paragraph that has a tooltip. We position it to the left so it doesn't align with the middle top of the paragraph (that looks weird).
{:data-toggle="tooltip" data-placement="left" title="Markdown tooltip example"}
<a href="/contribute/components/tooltips" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="Open the test page (in a new window)">Test</span></a>
## HTML
```html
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="left" title="Tooltip on left">Tooltip on left</button>
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="top" title="Tooltip on top">Tooltip on top</button>
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">Tooltip on bottom</button>
<button type="button" class="btn btn-default" data-toggle="tooltip" data-placement="right" title="Tooltip on right">Tooltip on right</button>
This is a paragraph that has a tooltip. We position it to the left so it doesn't align with the middle top of the paragraph (that looks weird).
{:data-toggle="tooltip" data-placement="left" title="Markdown tooltip example"}
<a href="/contribute/components" target="_blank" rel="noopener" class="_"><span class="badge badge-info" data-toggle="tooltip" data-placement="right" title="Open the test page (in a new window)">Test</span></a>
```

14
content/contribute/components/videos.md
View File

@ -4,11 +4,13 @@ title: Videos
toc_max: 3 toc_max: 3
--- ---
To embed a YouTube video on a docs page, open the video on YouTube, select To embed a video on a docs page, use an `<iframe>` element:
**Share** > **Embed** and then copy the code displayed.
For example, the video embedded on the Get Started page has the following code:
```html ```html
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/iqqDU2crIEQ?start=30" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe> <iframe
``` class="border-0 w-full aspect-video mb-8"
allow="fullscreen"
title=""
src=""
></iframe>
```

69
content/contribute/contribute-guide.md
View File

@ -15,7 +15,7 @@ There are two ways to contribute a pull request to the docs repository:
1. You can select the **Edit this page** option in the right column of every page on [https://docs.docker.com/](/). 1. You can select the **Edit this page** option in the right column of every page on [https://docs.docker.com/](/).
This opens the GitHub editor, which means you don't need to know a lot about Git, or even about Markdown. When you save, Git prompts you to create a fork if you don't already have one, and to create a branch in your fork and submit the pull request. This opens the GitHub editor, which means you don't need to know a lot about Git, or even about Markdown. When you save, GitHub prompts you to create a fork if you don't already have one, and to create a branch in your fork and submit the pull request.
<!-- markdownlint-disable-next-line --> <!-- markdownlint-disable-next-line -->
2. Fork the [docs GitHub repository]({{% param "repo" %}}). Suggest changes or add new content on your local branch, and submit a pull request (PR) to the `main` branch. 2. Fork the [docs GitHub repository]({{% param "repo" %}}). Suggest changes or add new content on your local branch, and submit a pull request (PR) to the `main` branch.
@ -28,14 +28,14 @@ There are two ways to contribute a pull request to the docs repository:
Here’s a list of some of the important files: Here’s a list of some of the important files:
- `/_data/toc.yaml` defines the left-hand navigation for the docs. - `/content` contains all the pages. The site uses filesystem-based routing, so the filepath of the source files correspond to the url subpath.
- `/js/docs.js` defines most of the docs-specific JS such as the table of contents (ToC) generation and menu syncing. - `/data/toc.yaml` defines the left-hand navigation for the docs.
- `/css/style.scss` defines the docs-specific style rules. - `/layouts` contains the html templates used to generate the HTML pages.
- `/_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.
### Files not edited here CLI reference documentation is generated from code, and is not maintained in
this repository. (They're only vendored here, either manually in `/data` or
Some files and directories are maintained in the upstream repositories. You can find a list of such files in `_config_production.yml`. Pull requests against these files will be rejected. automatically in `/_vendor`.) To update CLI reference docs, refer to the
corresponding repository containing the CLI source code.
## Pull request guidelines ## Pull request guidelines
@ -72,7 +72,7 @@ $ git clone {{% param "repo" %}}.git
$ cd docs $ cd docs
``` ```
Then, build and run the documentation using [Docker Compose](../compose/index.md): Then, build and run the documentation using [Docker Compose](../compose/_index.md):
```console ```console
$ docker compose watch $ docker compose watch
@ -80,7 +80,7 @@ $ docker compose watch
> **Note** > **Note**
> >
>You need Docker Compose to build and run the docs locally. Docker Compose is included with [Docker Desktop](../desktop/index.md). If you don't have Docker Desktop installed, follow the [instructions](../compose/install/index.md) to install Docker Compose. >You need Docker Compose to build and run the docs locally. Docker Compose is included with [Docker Desktop](../desktop/_index.md). If you don't have Docker Desktop installed, follow the [instructions](../compose/install/index.md) to install Docker Compose.
When the container is built and running, visit [http://localhost:1313](http://localhost:1313) in your web browser to view the docs. When the container is built and running, visit [http://localhost:1313](http://localhost:1313) in your web browser to view the docs.
@ -93,48 +93,27 @@ To stop the development container:
1. In your terminal, press `<Ctrl+C>` to exit the file watch mode of Compose. 1. In your terminal, press `<Ctrl+C>` to exit the file watch mode of Compose.
2. Stop the Compose services with the `docker compose down` command. 2. Stop the Compose services with the `docker compose down` command.
### 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 feedback
- `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, set the `JEKYLL_ENV` environment variable when building the documentation:
```bash
JEKYLL_ENV=production docker compose up --build
```
When 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.
### Test the docs locally ### Test the docs locally
We use a command-line tool called [vale](https://vale.sh/) to check the style and help you find For testing the documentation, we use:
errors in your writing. We highly recommend that you use vale to lint your documentation before - a command-line tool called [vale](https://vale.sh/) to check the style and help you find errors in your writing.
you submit your pull request. - [wjdp/htmltest](https://github.com/wjdp/htmltest) for proofing HTML markup and checking for broken links
You can run vale as a stand-alone tool using the command-line, or you can integrate it with You can use Buildx to run all the tests locally before you create your pull
your editor to get real-time feedback on your writing. request:
To get started, follow the [vale installation instructions](https://vale.sh/docs/vale-cli/installation/) ```console
for your operating system. To enable the vale integration for your editor, install the relevant plugin: $ docker buildx bake validate
```
You can also integrate `vale` with your text editor to get real-time feedback
on your writing. Refer to the relevant plugin for your editor:
- [VS Code](https://github.com/chrischinchilla/vale-vscode) - [VS Code](https://github.com/chrischinchilla/vale-vscode)
- [Neovim](https://github.com/jose-elias-alvarez/null-ls.nvim/blob/main/doc/BUILTINS.md#vale) - [Neovim](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md#vale_ls)
- [Emacs](https://github.com/tpeacock19/flymake-vale) - [Emacs](https://github.com/tpeacock19/flymake-vale)
- [Jetbrains](https://vale.sh/docs/integrations/jetbrains/) - [Jetbrains](https://vale.sh/docs/integrations/jetbrains/)
- [Sublime Text](https://github.com/errata-ai/LSP-vale-ls) - [Sublime Text](https://github.com/errata-ai/LSP-vale-ls)
The vale rules that implement the Docker style guide are included in the Docker docs repository, The `vale` rules that implement the Docker style guide are included in the
in the `.github/vale` directory. Vale will automatically apply these rules when invoked in this Docker docs repository, in the `.github/vale` directory.
repository.

2
data/toc.yaml
View File

@ -230,8 +230,6 @@ Guides:
title: Tables title: Tables
- path: /contribute/components/tabs/ - path: /contribute/components/tabs/
title: Tabs title: Tabs
- path: /contribute/components/tooltips/
title: Tooltips
- path: /contribute/components/videos/ - path: /contribute/components/videos/
title: Videos title: Videos
- path: /contribute/components/buttons/ - path: /contribute/components/buttons/