mirror of https://github.com/docker/docs.git
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:
parent
d4a743db31
commit
e02dcae84b
|
@ -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)
|
||||
```
|
||||
|
|
|
@ -8,20 +8,33 @@ toc_max: 3
|
|||
|
||||
- A small image: 
|
||||
|
||||
- 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:
|
||||
|
||||

|
||||
|
||||
- Image size can be set using URL query parameters: 
|
||||
- Image size can be set using query parameters: `?h=<height>&w=<width>`
|
||||
|
||||

|
||||
|
||||
- Image with a border, also set with a query parameter: `?border=true`
|
||||
|
||||

|
||||
|
||||
|
||||
## HTML and Markdown
|
||||
|
||||
```markdown
|
||||
- A small image: 
|
||||
|
||||
- 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:
|
||||
|
||||

|
||||
|
||||
- Image size can be set using URL query parameters (`h` and `w`): 
|
||||
```
|
||||
- Image size can be set using query parameters: `?h=<height>&w=<width>`
|
||||
|
||||

|
||||
|
||||
- Image with a border, also set with a query parameter: `?border=true`
|
||||
|
||||

|
||||
```
|
||||
|
|
|
@ -76,4 +76,4 @@ Use dashes (`-`) or asterisks (`*`) for bullet points.
|
|||
| -------- | -------- |
|
||||
| Thing 1 | Thing 2 |
|
||||
| Thing 3 | Thing 4 |
|
||||
````
|
||||
````
|
||||
|
|
|
@ -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>
|
||||
```
|
|
@ -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>
|
||||
```
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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/
|
||||
|
|
Loading…
Reference in New Issue