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

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

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

21
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)
- 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)
- 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
```markdown
- 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)
- 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)
```

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

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

@ -4,11 +4,13 @@ title: Videos
toc_max: 3
---
To embed a YouTube video on a docs page, open the video on YouTube, select
**Share** > **Embed** and then copy the code displayed.
For example, the video embedded on the Get Started page has the following code:
To embed a video on a docs page, use an `<iframe>` element:
```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/](/).
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 -->
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:
- `/_data/toc.yaml` defines the left-hand navigation for the docs.
- `/js/docs.js` defines most of the docs-specific JS such as the table of contents (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.
- `/content` contains all the pages. The site uses filesystem-based routing, so the filepath of the source files correspond to the url subpath.
- `/data/toc.yaml` defines the left-hand navigation for the docs.
- `/layouts` contains the html templates used to generate the HTML pages.
### Files not edited here
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.
CLI reference documentation is generated from code, and is not maintained in
this repository. (They're only vendored here, either manually in `/data` or
automatically in `/_vendor`.) To update CLI reference docs, refer to the
corresponding repository containing the CLI source code.
## Pull request guidelines
@ -72,7 +72,7 @@ $ git clone {{% param "repo" %}}.git
$ 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
$ docker compose watch
@ -80,7 +80,7 @@ $ docker compose watch
> **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.
@ -93,48 +93,27 @@ To stop the development container:
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.
### 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
We use a command-line tool called [vale](https://vale.sh/) to check the style and help you find
errors in your writing. We highly recommend that you use vale to lint your documentation before
you submit your pull request.
For testing the documentation, we use:
- a command-line tool called [vale](https://vale.sh/) to check the style and help you find errors in your writing.
- [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
your editor to get real-time feedback on your writing.
You can use Buildx to run all the tests locally before you create your pull
request:
To get started, follow the [vale installation instructions](https://vale.sh/docs/vale-cli/installation/)
for your operating system. To enable the vale integration for your editor, install the relevant plugin:
```console
$ 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)
- [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)
- [Jetbrains](https://vale.sh/docs/integrations/jetbrains/)
- [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,
in the `.github/vale` directory. Vale will automatically apply these rules when invoked in this
repository.
The `vale` rules that implement the Docker style guide are included in the
Docker docs repository, in the `.github/vale` directory.

2
data/toc.yaml
View File

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