diff --git a/.github/instructions/styleguide-instructions.md b/.github/instructions/styleguide-instructions.md deleted file mode 100644 index 3e71939247..0000000000 --- a/.github/instructions/styleguide-instructions.md +++ /dev/null @@ -1,111 +0,0 @@ ---- -applyTo: '**/*.md' ---- -# Documentation Writing Instructions - -These are our documentation writing style guidelines. - -## General Style tips - -* Get to the point fast. -* Talk like a person. -* Simpler is better. -* Be brief. Give customers just enough information to make decisions confidently. Prune every excess word. -* We use Hugo to generate our docs. - -## Grammar - -* Use present tense verbs (is, open) instead of past tense (was, opened). -* Write factual statements and direct commands. Avoid hypotheticals like "could" or "would". -* Use active voice where the subject performs the action. -* Write in second person (you) to speak directly to readers. -* Use gender-neutral language. -* Avoid multiple -ing words that can create ambiguity. -* Keep prepositional phrases simple and clear. -* Place modifiers close to what they modify. - -## Capitalization - -* Use sentence-style capitalization for everything except proper nouns. -* Always capitalize proper nouns. -* Don’t capitalize the spelled-out form of an acronym unless it's a proper noun. -* In programming languages, follow the traditional capitalization of keywords and other special terms. -* Don't use all uppercase for emphasis. - -## Numbers - -* Spell out numbers for zero through nine, unless space is limited. Use numerals for 10 and above. -* Spell out numbers at the beginning of a sentence. -* Spell out ordinal numbers such as first, second, and third. Don't add -ly to form adverbs from ordinal numbers. - -## Punctuation - -* Use short, simple sentences. -* End all sentences with a period. -* Use one space after punctuation marks. -* After a colon, capitalize only proper nouns. -* Avoid semicolons - use separate sentences instead. -* Use question marks sparingly. -* Don't use slashes (/) - use "or" instead. - -## Text formatting - -* UI elements, like menu items, dialog names, and names of text boxes, should be in bold text. -* Use code style for: - * Code elements, like method names, property names, and language keywords. - * SQL commands. - * Command-line commands. - * Database table and column names. - * Resource names (like virtual machine names) that shouldn't be localized. - * URLs that you don't want to be selectable. -* For code placeholders, if you want users to replace part of an input string with their own values, use angle brackets (less than < and greater than > characters) on that placeholder text. -* Don't apply an inline style like italic, bold, or inline code style to headings. - -## Alerts - -* Alerts are a Markdown extension to create block quotes that render with colors and icons that indicate the significance of the content. The following alert types are supported: - - * `[!NOTE]` Information the user should notice even if skimming. - * `[!TIP]` Optional information to help a user be more successful. - * `[!IMPORTANT]` Essential information required for user success. - * `[!CAUTION]` Negative potential consequences of an action. - * `[!WARNING]` Dangerous certain consequences of an action. - -## Links - -* Links to other documentation articles should be relative, not absolute. Include the `.md` suffix. -* Links to bookmarks within the same article should be relative and start with `#`. -* Link descriptions should be descriptive and make sense on their own. Don't use "click here" or "this link" or "here". - -## Images - -* Use images only when they add value. -* Images have a descriptive and meaningful alt text that starts with "Screenshot showing" and ends with ".". -* Videos have a descriptive and meaningful alt text or title that starts with "Video showing" and ends with ".". - -## Numbered steps - -* Write complete sentences with capitalization and periods -* Use imperative verbs -* Clearly indicate where actions take place (UI location) -* For single steps, use a bullet instead of a number -* When allowed, use angle brackets for menu sequences (File > Open) -* When writing ordered lists, only use 1's. - -## Terminology - -* Use "Select" instead of "Click" for UI elements like buttons, menu items, links, dropdowns, and checkboxes. -* Use "might" instead of "may" for conditional statements. -* Avoid latin abbreviations like "e.g.". Use "for example" instead. -* Use the verb "to enable" instead "to allow" unless you're referring to permissions. -* Follow the terms and capitalization guidelines in #fetch [VS Code docs wiki](https://github.com/microsoft/vscode-docs/wiki/VS-Code-glossary) - - -## Complete style guide - -Find all the details of the style guide in these files: - -- `./content/contribute/style/grammar.md` – Grammar rules -- `./content/contribute/style/formatting.md` – Formatting rules -- `./content/contribute/style/recommended-words.md` – Approved words and phrasing -- `./content/contribute/style/voice-tone.md` – Voice and tone guidance diff --git a/COMPONENTS.md b/COMPONENTS.md new file mode 100644 index 0000000000..a1dcebbf0d --- /dev/null +++ b/COMPONENTS.md @@ -0,0 +1,606 @@ +# Docker Documentation Components Guide + +This guide explains how to use components, shortcodes, and special features +when writing Docker documentation. For writing style and grammar, see +[STYLE.md](STYLE.md). + +## Front matter + +Every documentation page requires front matter at the top of the file. + +### Required fields + +```yaml +--- +title: Install Docker Engine on Ubuntu +description: Instructions for installing Docker Engine on Ubuntu +keywords: requirements, apt, installation, ubuntu +--- +``` + +| Field | Description | +| ----------- | ------------------------------------------------------------ | +| title | Page title, used in `

` and `` tag | +| description | SEO description (150-160 characters), added to HTML metadata | +| keywords | Comma-separated keywords for SEO | + +### Optional fields + +| Field | Description | +| --------------- | ------------------------------------------------------------------ | +| linkTitle | Shorter title for navigation and sidebar (if different from title) | +| weight | Controls sort order in navigation (lower numbers appear first) | +| aliases | List of URLs that redirect to this page | +| toc_min | Minimum heading level in table of contents (default: 2) | +| toc_max | Maximum heading level in table of contents (default: 3) | +| notoc | Set to `true` to disable table of contents | +| sitemap | Set to `false` to exclude from search engine indexing | +| sidebar.badge | Add badge to sidebar (see [Badges](#badges)) | +| sidebar.reverse | Reverse sort order of pages in section | +| sidebar.goto | Override sidebar link URL | + +### Example with optional fields + +```yaml +--- +title: Install Docker Engine on Ubuntu +linkTitle: Install on Ubuntu +description: Instructions for installing Docker Engine on Ubuntu +keywords: requirements, apt, installation, ubuntu, install, uninstall +weight: 10 +aliases: + - /engine/installation/linux/ubuntu/ + - /install/linux/ubuntu/ +toc_max: 4 +params: + sidebar: + badge: + color: blue + text: Beta +--- +``` + +## Shortcodes + +Shortcodes are reusable components that add rich functionality to your +documentation. + +### Tabs + +Use tabs for platform-specific instructions or content variations. + +**Example:** + +{{< tabs >}} +{{< tab name="Linux" >}} + +```console +$ docker run hello-world +``` + +{{< /tab >}} +{{< tab name="macOS" >}} + +```console +$ docker run hello-world +``` + +{{< /tab >}} +{{< tab name="Windows" >}} + +```powershell +docker run hello-world +``` + +{{< /tab >}} +{{< /tabs >}} + +**Syntax:** + +```markdown +{{</* tabs */>}} +{{</* tab name="Linux" */>}} +Content for Linux +{{</* /tab */>}} +{{</* tab name="macOS" */>}} +Content for macOS +{{</* /tab */>}} +{{</* /tabs */>}} +``` + +**Tab groups (synchronized selection):** + +Use the `group` attribute to synchronize tab selection across multiple tab +sections: + +```markdown +{{</* tabs group="os" */>}} +{{</* tab name="Linux" */>}} +Linux content for first section +{{</* /tab */>}} +{{</* tab name="macOS" */>}} +macOS content for first section +{{</* /tab */>}} +{{</* /tabs */>}} + +{{</* tabs group="os" */>}} +{{</* tab name="Linux" */>}} +Linux content for second section +{{</* /tab */>}} +{{</* tab name="macOS" */>}} +macOS content for second section +{{</* /tab */>}} +{{</* /tabs */>}} +``` + +When a user selects "Linux" in the first section, all tabs in the "os" group +switch to "Linux". + +### Accordion + +Use accordions for collapsible content like optional steps or advanced +configuration. + +**Example:** + +{{< accordion title="Advanced configuration" >}} + +```yaml +version: "3.8" +services: + web: + build: . + ports: + - "8000:8000" +``` + +{{< /accordion >}} + +**Syntax:** + +```markdown +{{</* accordion title="Advanced configuration" */>}} +Content inside the accordion +{{</* /accordion */>}} +``` + +### Include + +Reuse content across multiple pages using the include shortcode. Include +files must be in the `content/includes/` directory. + +**Syntax:** + +```markdown +{{</* include "filename.md" */>}} +``` + +**Example:** + +```markdown +{{</* include "install-prerequisites.md" */>}} +``` + +### Badges + +Use badges to highlight new, beta, experimental, or deprecated content. + +**Example:** + +{{< badge color=blue text="Beta" >}} +{{< badge color=violet text="Experimental" >}} +{{< badge color=green text="New" >}} +{{< badge color=gray text="Deprecated" >}} + +**Syntax:** + +Inline badge: + +```markdown +{{</* badge color=blue text="Beta" */>}} +``` + +Badge as link: + +```markdown +[{{</* badge color=blue text="Beta feature" */>}}](link-to-page.md) +``` + +Sidebar badge (in front matter): + +```yaml +--- +title: Page title +params: + sidebar: + badge: + color: violet + text: Experimental +--- +``` + +**Color options:** + +- `blue` - Beta content +- `violet` - Experimental or early access +- `green` - New GA content +- `amber` - Warning or attention +- `red` - Critical +- `gray` - Deprecated + +**Usage guidelines:** + +- Use badges for no longer than 2 months post-release +- Use violet for experimental/early access features +- Use blue for beta features +- Use green for new GA features +- Use gray for deprecated features + +### Summary bars + +Summary bars indicate subscription requirements, version requirements, or +administrator-only features at the top of a page. + +**Example:** + +{{< summary-bar feature_name="Docker Scout" >}} + +**Setup:** + +1. Add feature to `/data/summary.yaml`: + +```yaml +features: + Docker Scout: + subscription: Business + availability: GA + requires: "Docker Desktop 4.17 or later" +``` + +2. Add shortcode to page: + +```markdown +{{</* summary-bar feature_name="Docker Scout" */>}} +``` + +**Attributes in summary.yaml:** + +| Attribute | Description | Values | +| ------------ | ------------------------------------- | ------------------------------------------------- | +| subscription | Subscription tier required | All, Personal, Pro, Team, Business | +| availability | Product development stage | Experimental, Beta, Early Access, GA, Retired | +| requires | Minimum version requirement | String describing version (link to release notes) | +| for | Indicates administrator-only features | Administrators | + +### Buttons + +Create styled buttons for calls to action. + +**Syntax:** + +```markdown +{{</* button text="Download Docker Desktop" url="/get-docker/" */>}} +``` + +### Cards + +Create card layouts for organizing content. + +**Syntax:** + +```markdown +{{</* card + title="Get started" + description="Learn Docker basics" + link="/get-started/" +*/>}} +``` + +### Icons + +Use Material Symbols icons in your content. + +**Syntax:** + +```markdown +{{</* icon name="check_circle" */>}} +``` + +Browse available icons at +[Material Symbols](https://fonts.google.com/icons). + +## Callouts + +Use GitHub-style callouts to emphasize important information. Use sparingly - +only when information truly deserves special emphasis. + +**Syntax:** + +```markdown +> [!NOTE] +> This is a note with helpful context. + +> [!TIP] +> This is a helpful suggestion or best practice. + +> [!IMPORTANT] +> This is critical information users must understand. + +> [!WARNING] +> This warns about potential issues or consequences. + +> [!CAUTION] +> This is for dangerous operations requiring extreme care. +``` + +**When to use each type:** + +| Type | Use for | Color | +| --------- | -------------------------------------------------------------- | ------ | +| Note | Information that may not apply to all readers or is tangential | Blue | +| Tip | Helpful suggestions or best practices | Green | +| Important | Issues of moderate magnitude | Yellow | +| Warning | Actions that may cause damage or data loss | Red | +| Caution | Serious risks | Red | + +## Code blocks + +Format code with syntax highlighting using triple backticks and language +hints. + +### Language hints + +Common language hints: + +- `console` - Interactive shell with `$` prompt +- `bash` - Bash scripts +- `dockerfile` - Dockerfiles +- `yaml` - YAML files +- `json` - JSON data +- `go`, `python`, `javascript` - Programming languages +- `powershell` - PowerShell commands + +**Interactive shell example:** + +````markdown +```console +$ docker run hello-world +``` +```` + +**Bash script example:** + +````markdown +```bash +#!/usr/bin/bash +echo "Hello from Docker" +``` +```` + +### Variables in code + +Use `<VARIABLE_NAME>` format for placeholder values: + +````markdown +```console +$ docker tag <IMAGE_NAME> <REGISTRY>/<IMAGE_NAME>:<TAG> +``` +```` + +This syntax renders variables in a special color and font style. + +### Highlighting lines + +Highlight specific lines with `hl_lines`: + +````markdown +```go {hl_lines=[3,4]} +func main() { + fmt.Println("Hello") + fmt.Println("This line is highlighted") + fmt.Println("This line is highlighted") +} +``` +```` + +### Collapsible code blocks + +Make long code blocks collapsible: + +````markdown +```dockerfile {collapse=true} +# syntax=docker/dockerfile:1 +FROM golang:1.21-alpine +RUN apk add --no-cache git +# ... more lines +``` +```` + +## Images + +Add images using standard Markdown syntax with optional query parameters for +sizing and borders. + +**Basic syntax:** + +```markdown +![Alt text description](/assets/images/image.png) +``` + +**With size parameters:** + +```markdown +![Alt text](/assets/images/image.png?w=600&h=400) +``` + +**With border:** + +```markdown +![Alt text](/assets/images/image.png?border=true) +``` + +**Combined parameters:** + +```markdown +![Alt text](/assets/images/image.png?w=600&h=400&border=true) +``` + +**Best practices:** + +- Store images in `/static/assets/images/` +- Use descriptive alt text for accessibility +- Compress images before adding to repository +- Capture only relevant UI, avoid unnecessary whitespace +- Use realistic text, not lorem ipsum +- Remove unused images from repository + +## Videos + +Embed videos using HTML video tags or platform-specific embeds. + +**Local video:** + +```html +<video controls width="100%"> + <source src="/assets/videos/demo.mp4" type="video/mp4" /> +</video> +``` + +**YouTube embed:** + +```html +<iframe + width="560" + height="315" + src="https://www.youtube.com/embed/VIDEO_ID" + frameborder="0" + allow="autoplay; encrypted-media" + allowfullscreen +> +</iframe> +``` + +## Links + +Use standard Markdown link syntax. For internal links, use relative paths +with source filenames. + +**External link:** + +```markdown +[Docker Hub](https://hub.docker.com/) +``` + +**Internal link (same section):** + +```markdown +[Installation guide](install.md) +``` + +**Internal link (different section):** + +```markdown +[Get started](/get-started/overview.md) +``` + +**Link to heading:** + +```markdown +[Prerequisites](#prerequisites) +``` + +**Best practices:** + +- Use descriptive link text (around 5 words) +- Front-load important terms +- Avoid generic text like "click here" or "learn more" +- Don't include end punctuation in link text +- Use relative paths for internal links + +## Lists + +### Unordered lists + +```markdown +- First item +- Second item +- Third item + - Nested item + - Another nested item +``` + +### Ordered lists + +```markdown +1. First step +2. Second step +3. Third step + 1. Nested step + 2. Another nested step +``` + +### Best practices + +- Limit bulleted lists to 5 items when possible +- Don't add commas or semicolons to list item ends +- Capitalize list items for ease of scanning +- Make all list items parallel in structure +- For nested sequential lists, use lowercase letters (a, b, c) + +## Tables + +Use standard Markdown table syntax with sentence case for headings. + +**Example:** + +```markdown +| Feature | Description | Availability | +| -------------- | ------------------------------- | ------------ | +| Docker Compose | Multi-container orchestration | All | +| Docker Scout | Security vulnerability scanning | Business | +| Build Cloud | Remote build service | Pro, Team | +``` + +**Best practices:** + +- Use sentence case for table headings +- Don't leave cells empty - use "N/A" or "None" +- Align decimals on the decimal point +- Keep tables scannable - avoid dense content + +## Quick reference + +### File structure + +```plaintext +content/ +├── manuals/ # Product documentation +│ ├── docker-desktop/ +│ ├── docker-hub/ +│ └── ... +├── guides/ # Learning guides +├── reference/ # API and CLI reference +└── includes/ # Reusable content snippets +``` + +### Common patterns + +**Platform-specific instructions:** + +Use tabs with consistent names: Linux, macOS, Windows + +**Optional content:** + +Use accordions for advanced or optional information + +**Version/subscription indicators:** + +Use badges or summary bars + +**Important warnings:** + +Use callouts (NOTE, WARNING, CAUTION) + +**Code examples:** + +Use `console` for interactive shells, appropriate language hints for code diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8e60c4b335..8173a1271e 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -3,9 +3,12 @@ We value documentation contributions from the Docker community. We'd like to make it as easy as possible for you to work in this repository. -Our style guide and instructions on using our page templates and components is -available in the [contribution section](https://docs.docker.com/contribute/) on -the website. +Before contributing, review our documentation standards: + +- [STYLE.md](STYLE.md) - Writing style, voice, grammar, and formatting + guidelines +- [COMPONENTS.md](COMPONENTS.md) - How to use Hugo shortcodes, front matter, + and components The following guidelines describe how to contribute to the Docker documentation at <https://docs.docker.com/>, and how to get started. diff --git a/README.md b/README.md index 1db900fbdc..418a410070 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,7 @@ Feel free to open pull requests or issues. Our docs are completely open source, ## Provide feedback We’d love to hear your feedback! To submit feedback: + - Click **[New issue](https://github.com/docker/docs/issues/new)** on the docs repository, or - Click **Request changes** in the right column of every page on [docs.docker.com](https://docs.docker.com/), or @@ -28,7 +29,11 @@ repository. ## Contribute to Docker docs -See [CONTRIBUTING.md](CONTRIBUTING.md). +We welcome contributions! To get started: + +- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribution workflow and setup +- [STYLE.md](STYLE.md) - Writing style and content guidelines +- [COMPONENTS.md](COMPONENTS.md) - Component and shortcode usage ## Copyright and license diff --git a/STYLE.md b/STYLE.md new file mode 100644 index 0000000000..e5c9a86914 --- /dev/null +++ b/STYLE.md @@ -0,0 +1,566 @@ +# Docker Documentation Style Guide + +This guide consolidates voice, grammar, formatting, and terminology +standards for Docker documentation. Follow these guidelines to create +clear, consistent, and helpful content. For instructions on how to use +components, shortcodes, and other features, see [COMPONENTS.md](COMPONENTS.md). + +## Voice and tone + +Write like a knowledgeable colleague explaining something useful. We're +developers writing for developers. + +### Core principles: The 4Cs + +1. **Correct** - Information is accurate +2. **Concise** - Succinct without unnecessary words +3. **Complete** - Includes enough detail to complete the task +4. **Clear** - Easy to understand + +### Writing approach + +- **Be honest.** Give all the facts. Don't use misdirection or + ambiguous statements. +- **Be concise.** Don't bulk up communication with fluffy words or + complex metaphors. Get to the point. +- **Be relaxed.** Casual but not lazy, smart but not arrogant, focused + but not cold. Be welcoming and warm. +- **Be inclusive.** Every person is part of our community, regardless + of experience level. + +### Tone guidelines + +- Use a natural, friendly, and respectful tone +- Use contractions to sound conversational (it's, you're, don't) +- Avoid overdoing politeness - skip "please" in most technical documentation +- Be clear over comical +- Use positive language - emphasize what users can do, not what they can't + +**Positive language example:** + +Instead of: "Features such as Single Sign-on (SSO), Image Access +Management, Registry Access Management are not available in Docker Team +subscription." + +Use: "Features such as Single Sign-on (SSO), Image Access Management, +Registry Access Management are available in Docker Business subscription." + +### Avoiding marketing language + +Documentation should be factual and direct, not promotional. + +**Avoid hedge words** that overstate ease or capability: + +- ❌ simply, just, easily, seamlessly (implies ease when it may not be + easy) +- ❌ robust, powerful (marketing language) +- ✅ Instead: describe what it actually does + +**Avoid excessive enthusiasm:** + +- ❌ "powerful feature", "game-changing", "revolutionary", "amazing" +- ✅ Instead: describe the feature and its benefits factually + +**Avoid meta-commentary:** + +These phrases add no value - state the fact directly: + +- ❌ "It's worth noting that..." +- ❌ "It's important to understand that..." +- ❌ "Keep in mind that..." +- ✅ Instead: state the information directly + +### Voice and perspective + +- **Use "you" not "we"**: Focus on what the user can do, not what "we" + created + - ❌ "We provide a feature that helps you deploy" + - ✅ "Deploy your applications with..." +- **Avoid "please"**: Don't use in normal explanations or "please note" + phrases +- **Write timelessly**: Avoid "currently" or "as of this writing" - the + documentation describes the product as it is today + +### Scope preservation + +When updating existing documentation, resist the urge to expand +unnecessarily. Users value brevity. + +**Understand the current document:** +Read it fully to grasp its scope, length, and character. Is it a minimal +how-to or a comprehensive reference? + +**Match the existing character:** +If the document is brief and direct (90 lines), keep it that way. Don't +transform a focused guide into an exhaustive tutorial. + +**Add only what's genuinely missing:** +Fill gaps, don't elaborate. If the document already covers a topic +adequately, don't expand it. + +**Value brevity:** +Say what needs to be said, then stop. Not every topic needs +prerequisites, troubleshooting, best practices, and examples sections. + +**Respect the original intent:** +The document exists in its current form for a reason. Improve it, don't +remake it. + +Good additions fill genuine gaps. Bad additions change the document's +character. When in doubt, add less rather than more. + +## Grammar and style + +Write in US English with US grammar. + +### Acronyms and initialisms + +- Spell out lesser-known acronyms on first use, then follow with the + acronym in parentheses: "single sign-on (SSO)" +- Don't spell out common acronyms like URL, HTML, API +- Use all caps for file type acronyms: JPEG, PNG +- Don't use apostrophes for plurals: URLs not URL's +- Avoid introducing acronyms in headings - introduce them in the body + text that follows + +### Capitalization + +Use sentence case for almost everything: headings, titles, links, buttons, +navigation labels. + +- Capitalize Docker solutions: Docker Desktop, Docker Hub, Docker Extensions +- Capitalize job titles only when they immediately precede a name: + "Chief Executive Officer Scott Johnston" but "Scott Johnston, chief + executive officer" +- Follow company capitalization preferences: DISH, bluecrux +- Match UI capitalization when referring to specific interface elements + +### Contractions + +Use contractions to maintain a conversational tone, but don't overdo it. + +- Stay consistent - don't switch between "you are" and "you're" in the + same content +- Avoid negative contractions when possible (can't, don't, won't) - + rewrite to be positive +- Never contract a noun with a verb (your container is ready, not your + container's ready) + +### Dangling modifiers + +Avoid unclear subjects: + +- ❌ After enabling auto-log-out, your users are logged out +- ✅ When you enable auto-log-out, your users are logged out + +### Dates and numbers + +- Use US date format: June 26, 2021 or Jun. 26, 2021 +- Spell out numbers one through nine, except in units: 4 MB +- Use numerals for 10 and above: 10, 625, 1000 +- Use decimals instead of fractions: 0.5 not ½ +- For numbers with five or more digits, use spaces instead of commas: + 14 586 not 14,586 +- For version numbers: version 4.8.2, v1.0, Docker Hub API v2 + +### Punctuation + +- **Commas:** Use the Oxford comma (serial comma) in lists +- **Colons:** Use to introduce lists or provide explanations +- **Semicolons:** Don't use - write two sentences instead +- **Em dashes:** Use sparingly with spaces on either side: "text - like + this - text" +- **Hyphens:** Use for compound adjectives before nouns: + "up-to-date documentation" +- **Exclamation marks:** Avoid +- **Parentheses:** Avoid in technical documentation - they reduce + readability + +### Conciseness and redundant phrases + +Remove unnecessary words to make documentation clearer and more direct. + +**Eliminate redundant phrases:** + +- ❌ "in order to" → ✅ "to" +- ❌ "serves the purpose of" → ✅ state what it does directly +- ❌ "allows you to" → ✅ "lets you" or state what it does +- ❌ "enables you to" → ✅ "lets you" or state what it does + +### Bold and italics + +Use bold **only** for UI elements (buttons, menus, field labels). Never +use bold for emphasis, product names, or feature names. + +- ✅ Select **Save** (UI button - use bold) +- ✅ Docker Hub provides storage (product name - no bold) +- ✅ This is important to understand (emphasis - no bold) +- ❌ **Docker Desktop** is a tool (product name - don't bold) +- ❌ This is **very important** (emphasis - don't bold) +- ❌ The **build** command (command name - don't bold) + +**Italics:** +Use italics sparingly, as this formatting can be difficult to read in +digital experiences. Notable exceptions are titles of articles, blog +posts, or specification documents. + +## Formatting + +### Content types and detail balance + +Different content types require different writing approaches. Match your +style and detail level to the content type. + +**Getting Started / Tutorials:** + +- Step-by-step instructions +- Assume beginner knowledge +- Explain _why_ at each step +- Include more context and explanation + +**How-to Guides:** + +- Task-focused and goal-oriented +- Assume intermediate knowledge +- Focus on _how_ efficiently +- Less explanation, more direct steps + +**Reference Documentation:** + +- Comprehensive and exhaustive +- Assume advanced knowledge +- Focus on _what_ precisely +- Complete parameter lists and options + +**Concept Explanations:** + +- Educational and foundational +- Any skill level +- Focus on _understanding_ over doing +- Theory before practice + +**Match detail to context:** + +- **First mention** of a concept: explain it +- **Subsequent mentions**: link to the explanation or use the term + directly if recently explained +- **Common knowledge** (to your audience): state it, don't explain it +- **Edge cases**: mention them but don't let them dominate the main flow + +### Headings + +- Keep headings short (no more than eight words) +- Front-load the most important words +- Use descriptive, action-oriented language +- Skip leading articles (a, the) +- Avoid puns, teasers, and cultural references +- Page titles should be action-oriented: "Install Docker Desktop", + "Enable SCIM" + +### Page structure and flow + +Every page should answer two questions in the first paragraph: + +1. **What will I learn?** - State what the page covers +2. **Why does this matter?** - Explain the benefit or use case + +**Good opening:** + +```markdown +Docker Compose Watch automatically updates your running containers when +you change code. This eliminates the manual rebuild-restart cycle during +development. +``` + +**Weak opening:** + +```markdown +Docker Compose Watch is a powerful feature that enables developers to +streamline their development workflow by providing automatic +synchronization capabilities. +``` + +**Transitions and flow:** +Connect ideas naturally. Each section should flow logically from the +previous one. Save detailed discussions for after showing basic usage - +don't front-load complexity. + +**Good flow:** + +1. Prerequisites +2. Basic usage (show the simple case first) +3. Advanced options (add complexity after basics are clear) + +**Jarring flow:** + +1. Prerequisites +2. Overview of all capabilities (too much before seeing it work) +3. Basic usage + +**Avoid structural problems:** + +- Don't start multiple sentences or sections with the same structure + (varies pacing and improves readability) +- Don't over-explain obvious things (trust the reader's competence) +- Don't use "**Bold:** format" for subsection labels (use plain text + with colon) + +### Lists + +- Limit bulleted lists to five items when possible +- Don't add commas or semicolons to list item ends +- Capitalize list items for ease of scanning +- Make all list items parallel in structure +- Start each item with a capital letter unless it's a parameter or + command +- For nested sequential lists, use lowercase letters: 1. Top level, + a. Child step + +**Avoid marketing-style list formatting:** + +Don't use "**Term** - Description" format, which reads like marketing +copy: + +❌ **Bad example:** + +- **Build** - Creates images from Dockerfiles +- **Run** - Starts containers from images +- **Push** - Uploads images to registries + +✅ **Good alternatives:** + +Use simple descriptive bullets: + +- Build images from Dockerfiles +- Start containers from images +- Upload images to registries + +Or use proper prose when appropriate: +"Docker lets you build images from Dockerfiles, start containers from +images, and upload images to registries." + +### Code and commands + +Format Docker commands, instructions, filenames, and package names as +inline code using backticks: `docker build` + +**Code example pattern:** + +Follow this three-step pattern for code examples: + +1. **State** what you're doing (brief) +2. **Show** the command or code +3. **Explain** the result or key parts (if not obvious) + +**Example:** + +````markdown +Build your image: + +```console +$ docker build -t my-app . +``` + +This creates an image tagged `my-app` using the Dockerfile in the +current directory. +```` + +**When to show command output:** + +- Show output when it helps understanding +- Show output when users need to verify results +- Don't show output for commands with obvious results +- Don't show output when it's not relevant to the point + +For code block syntax, language hints, variables, and advanced features +(line highlighting, collapsible blocks), see +[COMPONENTS.md](COMPONENTS.md#code-blocks). + +### Links + +- Use plain, descriptive language (around five words) +- Front-load important terms at the beginning +- Avoid generic calls to action like "click here" or "find out more" +- Don't include end punctuation in link text +- Use relative links with source filenames for internal links +- Don't make link text bold or italic unless it would be in normal + body copy + +### Images + +**Best practices:** + +- Capture only relevant UI - don't include unnecessary white space +- Use realistic text, not lorem ipsum +- Keep images small and focused +- Compress images before adding to repository +- Remove unused images from repository + +For image syntax and parameters (sizing, borders), see +[COMPONENTS.md](COMPONENTS.md#images). + +### Callouts + +Use callouts sparingly to emphasize important information. Use them only +when information truly deserves special emphasis - for warnings, critical +notes, or important context that affects how users approach a task. + +Callout types: Note (informational), Tip (helpful suggestion), Important +(moderate issue), Warning (potential damage/loss), Caution (serious risk). + +For syntax and detailed usage guidelines, see +[COMPONENTS.md](COMPONENTS.md#callouts). + +### Tables + +- Use sentence case for table headings +- Don't leave cells empty - use "N/A" or "None" if needed +- Align decimals on the decimal point + +### Navigation instructions + +- Use location, then action: "From the **Visibility** drop-down list, select Public" +- Be brief and specific: "Select **Save**" +- Start with the reason if a step needs one: "To view changes, select the link" + +### Optional steps + +Start optional steps with "Optional." followed by the instruction: + +_1. Optional. Enter a description for the job._ + +### File types and units + +- Use formal file type names: "a PNG file" not "a .png file" +- Use abbreviated units with spaces: "10 GB" not "10GB" or + "10 gigabytes" + +## Word list + +### Recommended terms + +| Use | Don't use | +| ------------------------------------- | ---------------------- | +| lets | allows | +| turn on, toggle on | enable | +| turn off, toggle off | disable | +| select | click | +| following | below | +| previous | above | +| checkbox | check box | +| username | account name | +| sign in | sign on, log in, login | +| sign up, create account | register | +| for example, such as | e.g. | +| run | execute | +| want | wish | +| Kubernetes | K8s | +| repository | repo | +| administrator (first use), admin (UI) | - | +| and | & (ampersand) | +| move through, navigate to | scroll | +| (be more precise) | respectively | +| versus | vs, vs. | +| use | utilize | +| help | facilitate | + +### Version numbers + +- Use "earlier" not "lower": Docker Desktop 4.1 and earlier +- Use "later" not "higher" or "above": Docker Desktop 4.1 and later + +### Quick transformations + +Common phrases to transform for clearer, more direct writing: + +| Instead of... | Write... | +| ------------------------ | ---------------------------- | +| In order to build | To build | +| This allows you to build | This lets you build / Build | +| Simply run the command | Run the command | +| We provide a feature | Docker provides / You can | +| Utilize the API | Use the API | +| This facilitates testing | This helps test / This tests | +| Click the button | Select the button | +| It's worth noting that X | X (state it directly) | + +### UI elements + +- **tab vs view** - Use "view" for major UI sections, "tab" for + sub-sections +- **toggle** - You "turn on" or "turn off" a toggle + +## Docker terminology + +### Products and features + +- **Docker Compose** - The application or all functionality associated + with it +- **`docker compose`** - Use code formatting for commands +- **Docker Compose CLI** - The family of Compose commands from + Docker CLI +- **Compose plugin** - The add-on for Docker CLI that can be + enabled/disabled +- **compose.yaml** - Current designation for the Compose file (use + code formatting) + +### Technical terms + +- **Digest** - Long string automatically created when you push an + image +- **Member** - A user of Docker Hub who is part of an organization +- **Namespace** - Organization or user name; every image needs a + namespace +- **Node** - Physical or virtual machine running Docker Engine in + swarm mode + - Manager nodes: Perform swarm management and orchestration + - Worker nodes: Execute tasks +- **Registry** - Online storage for Docker images +- **Repository** - Lets users share container images with team, + customers, or community + +### Platform terminology + +- **Multi-platform** - Broad: Mac/Linux/Windows; Narrow: Linux/amd64 + and Linux/arm64 +- **Multi-architecture (multi-arch)** - CPU architecture or + hardware-architecture-based; don't use as synonym for multi-platform + +## Quick reference + +### Voice checklist + +- ✅ Direct and practical +- ✅ Conversational with active voice +- ✅ Specific and actionable +- ❌ Corporate-speak +- ❌ Condescending +- ❌ Overly formal + +### Structure checklist + +- ✅ Answer "What will I learn?" in the first paragraph +- ✅ Answer "Why does this matter?" in the first paragraph +- ✅ Front-load important information in headings and lists +- ✅ Connect ideas naturally between sections +- ✅ Use examples to clarify concepts +- ✅ Match content type (tutorial vs how-to vs reference vs concept) +- ✅ Follow code example pattern: state → show → explain +- ✅ Preserve document scope (don't unnecessarily expand) + +### Common mistakes + +- ❌ Using "click" instead of "select" +- ❌ Using "below" instead of "following" +- ❌ Starting sentences with numbers (recast the sentence) +- ❌ Using apostrophes in plural acronyms +- ❌ Leaving table cells empty +- ❌ Using commas in large numbers (use spaces) +- ❌ Referring to file types by extension (.png file) +- ❌ Using bold for product names or emphasis (only for UI elements) +- ❌ Using "**Term** - Description" format in lists +- ❌ Using hedge words (simply, easily, just, seamlessly) +- ❌ Using meta-commentary (it's worth noting that...) +- ❌ Using "we" instead of "you" or "Docker" +- ❌ Showing command output when it's not needed +- ❌ Not explaining what users will learn in first paragraph diff --git a/content/contribute/_index.md b/content/contribute/_index.md deleted file mode 100644 index 3801814cd1..0000000000 --- a/content/contribute/_index.md +++ /dev/null @@ -1,53 +0,0 @@ ---- -title: Contribute to Docker's docs -linkTitle: Contribute -weight: 10 -toc_max: 1 -aliases: -- /opensource/ -- /contribute/overview/ -- /contribute/contribute-guide/ -grid: -- title: Grammar and style - description: Explore Docker's grammar and style guide - icon: menu_book - link: /contribute/style/grammar -- title: Formatting - description: Format your content to match the rest of our documentation. - icon: newspaper - link: /contribute/style/formatting -- title: Recommended word list - description: Choose the right words for your content. - icon: checklist - link: /contribute/style/recommended-words -- title: Source file conventions - description: Guidelines for creating a new page. - icon: note_add - link: /contribute/file-conventions -- title: Terminology - description: Explore commonly used Docker terms. - icon: spellcheck - link: /contribute/style/terminology -- title: Voice and tone - description: Learn about how we use voice and tone in our writing. - icon: voice_selection - link: /contribute/style/voice-tone ---- - -We value documentation contributions from the Docker community. We'd like to -make it as easy as possible for you to contribute to the Docker documentation. - -Find the contribution guidelines in -[CONTRIBUTING.md](https://github.com/docker/docs/blob/main/CONTRIBUTING.md) in -the `docker/docs` GitHub repository. Use the following links to review our -style guide and instructions on how to use our page templates and components. - -{{< grid >}} - -### Additional resources - -See also: - -- A section of useful components you can add to your documentation. -- Information on Docker's [tone and voice](style/voice-tone.md). -- A [writing checklist](checklist.md) to help you when you're contributing to Docker's documentation. diff --git a/content/contribute/checklist.md b/content/contribute/checklist.md deleted file mode 100644 index e9e8af6fea..0000000000 --- a/content/contribute/checklist.md +++ /dev/null @@ -1,55 +0,0 @@ ---- -title: Writing checklist -description: A helpful writing checklist when creating documentation -keywords: checklist, documentation, style guide, contribute -weight: 60 ---- - -Use this checklist to communicate in a way that is clear, helpful, and consistent with the rest of Docker Docs. - -##### Used active voice - -Active voice is specific and removes ambiguity. - -In active voice, the subject of the sentence (the customer or the system) does the action. - -Sentences that use active voice are easier to read. Active voice makes it clear who has done what and to whom. Plus, active voice keeps sentences direct and more concise. - -Helping verbs such as is, was, or would may indicate that you're writing in passive voice. And, if you can add the phrase 'by zombies' after the verb, you're writing in the passive voice. - -|Correct| Incorrect| -|:--|:--| -|Increase productivity with Docker Desktop.| Productivity can be increased (by zombies) with Docker Desktop.| -|If you remove items from a grid, charts automatically refresh to display the change. | If items are removed (by zombies) from a grid, charts automatically refresh to display the change.| - -##### Written clear sentences that get to the point - -Write short, concise sentences. Punchy sentences are faster to read and easier to understand. - -##### Used subheadings and bulleted lists to break up the page - -This helps find the information they need quickly and easily. - -For more information, see the [formatting](style/formatting.md#headings-and-subheadings) page, or see the [components](components/lists.md) for examples. - -##### Started the title of your page with a verb - -For example, 'Install Docker Desktop'. - -##### Checked that the left-hand table of contents title in docs.docker.com, matches the title displayed on the page - -##### Checked for broken links and images - -Use relative links to link to other pages or images within the GitHub repository. - -For more information, see the [formatting](style/formatting.md#links) page, or see the [components](components/links.md) for examples. - -##### Checked that any redirects you may have added, work - -For information on how to add redirects, see [Source file conventions](file-conventions.md#front-matter). - -##### Used bold on any UI elements you refer to in your content - -##### Completed a final spelling, punctuation, and grammar check - -For more in-depth information on our Style Guide, explore the [grammar](style/grammar.md) or [formatting](style/formatting.md) guides. diff --git a/content/contribute/components/_index.md b/content/contribute/components/_index.md deleted file mode 100644 index 3c3ff89b1a..0000000000 --- a/content/contribute/components/_index.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -build: - render: never -title: Useful components -weight: 50 ---- \ No newline at end of file diff --git a/content/contribute/components/accordions.md b/content/contribute/components/accordions.md deleted file mode 100644 index c88cf9bdae..0000000000 --- a/content/contribute/components/accordions.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Accordions -toc_max: 3 ---- - -## Example - -{{< accordion title="Accordion example" >}} - -```console -$ docker run hello-world -``` - -{{< /accordion >}} - -## Markup - -````markdown -{{</* accordion title="Accordion example" */>}} - -```console -$ docker run hello-world -``` - -{{</* /accordion */>}} -```` diff --git a/content/contribute/components/badges.md b/content/contribute/components/badges.md deleted file mode 100644 index 6db626bd0e..0000000000 --- a/content/contribute/components/badges.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Badges -toc_max: 3 ---- - -### Examples - -{{< badge color=blue text="blue badge" >}} -{{< badge color=amber text="amber badge" >}} -{{< badge color=red text="red badge" >}} -{{< badge color=green text="green badge" >}} -{{< badge color=violet text="violet badge" >}} -{{< badge color=gray text="gray badge" >}} - -You can also make a badge a link. - -[{{< badge color="blue" text="badge with a link" >}}](../_index.md) - -### Usage guidelines - -Use badges to indicate new content and product content in various stages of the release lifecycle: - -- The violet badge to highlight new early access or experimental content -- The blue badge to highlight beta content -- The green badge to highlight new content that is either GA or not product-related content, such as guides/learning paths -- The gray badge to highlight deprecated content - -Best practice is to use this badge for no longer than 2 months post release of the feature. - -### Markup - -Inline badge: - -```go -{{</* badge color=amber text="amber badge" */>}} -[{{</* badge color="blue" text="badge with a link" */>}}](../overview.md) -``` - -Sidebar badge in frontmatter: - -```yaml ---- -title: Page title -params: - sidebar: - badge: - color: gray - text: Deprecated ---- -``` diff --git a/content/contribute/components/buttons.md b/content/contribute/components/buttons.md deleted file mode 100644 index 7e7aed3fdb..0000000000 --- a/content/contribute/components/buttons.md +++ /dev/null @@ -1,15 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Buttons -toc_max: 3 ---- - -### Examples - -{{< button url="https://example.com/" text="hello" >}} - -### Markup - -```go -{{</* button url="https://example.com/" text="hello" */>}} -``` diff --git a/content/contribute/components/call-outs.md b/content/contribute/components/call-outs.md deleted file mode 100644 index 231e896d2b..0000000000 --- a/content/contribute/components/call-outs.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Callouts -toc_max: 3 ---- - -We support these broad categories of callouts: - -- Alerts: Note, Tip, Important, Warning, Caution - -We also support summary bars, which represent a feature's required subscription, version, or Adminstrator role. -To add a summary bar: - -Add the feature name to the `/data/summary.yaml` file. Use the following attributes: - -| Attribute | Description | Possible values | -|----------------|--------------------------------------------------------|---------------------------------------------------------| -| `subscription` | Notes the subscription required to use the feature | All, Personal, Pro, Team, Business | -| `availability` | Notes what product development stage the feature is in | Experimental, Beta, Early Access, GA, Retired | -| `requires` | Notes what minimum version is required for the feature | No specific value, use a string to describe the version and link to relevant release notes | -| `for` | Notes if the feature is intended for IT Administrators | Administrators | - -Then, add the `summary-bar` shortcode on the page you want to add the summary bar to. Note, the feature name is case sensitive. The icons that appear in the summary bar are automatically rendered. - -## Examples - -{{< summary-bar feature_name="PKG installer" >}} - -> [!NOTE] -> -> Note the way the `get_hit_count` function is written. This basic retry -> loop lets us attempt our request multiple times if the redis service is -> not available. This is useful at startup while the application comes -> online, but also makes our application more resilient if the Redis -> service needs to be restarted anytime during the app's lifetime. In a -> cluster, this also helps handling momentary connection drops between -> nodes. - -> [!TIP] -> -> For a smaller base image, use `alpine`. - -> [!IMPORTANT] -> -> Treat access tokens like your password and keep them secret. Store your -> tokens securely (for example, in a credential manager). - -> [!WARNING] -> -> Removing Volumes -> -> By default, named volumes in your compose file are NOT removed when running -> `docker compose down`. If you want to remove the volumes, you will need to add -> the `--volumes` flag. -> -> The Docker Desktop Dashboard does not remove volumes when you delete the app stack. - -> [!CAUTION] -> -> Here be dragons. - -For both of the following callouts, consult [the Docker release lifecycle](/release-lifecycle) for more information on when to use them. - -## Formatting - -```md -{{</* summary-bar feature_name="PKG installer" */>}} -``` - -```html -> [!NOTE] -> -> Note the way the `get_hit_count` function is written. This basic retry -> loop lets us attempt our request multiple times if the redis service is -> not available. This is useful at startup while the application comes -> online, but also makes our application more resilient if the Redis -> service needs to be restarted anytime during the app's lifetime. In a -> cluster, this also helps handling momentary connection drops between -> nodes. - -> [!TIP] -> -> For a smaller base image, use `alpine`. - -> [!IMPORTANT] -> -> Treat access tokens like your password and keep them secret. Store your -> tokens securely (for example, in a credential manager). - -> [!WARNING] -> -> Removing Volumes -> -> By default, named volumes in your compose file are NOT removed when running -> `docker compose down`. If you want to remove the volumes, you will need to add -> the `--volumes` flag. -> -> The Docker Desktop Dashboard does not remove volumes when you delete the app stack. - -> [!CAUTION] -> -> Here be dragons. -``` \ No newline at end of file diff --git a/content/contribute/components/cards.md b/content/contribute/components/cards.md deleted file mode 100644 index 0dc0f009cf..0000000000 --- a/content/contribute/components/cards.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Cards -toc_max: 3 -grid: -- title: Docker Desktop - description: Docker on your Desktop. - icon: install_desktop - link: /desktop/ -- title: Docker Engine - description: Vrrrrooooommm - icon: developer_board - link: /engine/ -- title: Docker Build - description: Clang bang - icon: build - link: /build/ -- title: Docker Compose - description: Figgy! - icon: account_tree - link: /compose/ -- title: Docker Hub - description: so much content, oh wow - icon: hub - link: /docker-hub/ ---- - -Cards can be added to a page using the `card` shortcode. -The parameters for this shortcode are: - -| Parameter | Description | -| ----------- | -------------------------------------------------------------------- | -| title | The title of the card | -| icon | The icon slug of the card | -| image | Use a custom image instead of an icon (mutually exclusive with icon) | -| link | (Optional) The link target of the card, when clicked | -| description | A description text, in Markdown | - -> [!NOTE] -> -> There's a known limitation with the Markdown description of cards, -> in that they can't contain relative links, pointing to other .md documents. -> Such links won't render correctly. Instead, use an absolute link to the URL -> path of the page that you want to link to. -> -> For example, instead of linking to `../install/linux.md`, write: -> `/engine/install/linux/`. - -## Example - -{{< card - title="Get your Docker on" - icon=favorite - link=https://docs.docker.com/ - description="Build, share, and run your apps with Docker" >}} - -## Markup - -```go -{{</* card - title="Get your Docker on" - icon=favorite - link=https://docs.docker.com/ - description="Build, share, and run your apps with Docker" -*/>}} -``` - -### Grid - -There's also a built-in `grid` shortcode that generates a... well, grid... of cards. -The grid size is 3x3 on large screens, 2x2 on medium, and single column on small. - -{{< grid >}} - -Grid is a separate shortcode from `card`, but it implements the same component under the hood. -The markup you use to insert a grid is slightly unconventional. The grid shortcode takes no arguments. -All it does is let you specify where on a page you want your grid to appear. - -```go -{{</* grid */>}} -``` - -The data for the grid is defined in the front matter of the page, under the `grid` key, as follows: - -```yaml -# front matter section of a page -title: some page -grid: - - title: "Docker Engine" - description: Vrrrrooooommm - icon: "developer_board" - link: "/engine/" - - title: "Docker Build" - description: Clang bang - icon: "build" - link: "/build/" -``` diff --git a/content/contribute/components/code-blocks.md b/content/contribute/components/code-blocks.md deleted file mode 100644 index 63f7b1ab3e..0000000000 --- a/content/contribute/components/code-blocks.md +++ /dev/null @@ -1,244 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Code blocks -toc_max: 3 ---- - -Rouge provides lots of different code block "hints". If you leave off the hint, -it tries to guess and sometimes gets it wrong. These are just a few hints that -we use often. - -## Variables - -If your example contains a placeholder value that's subject to change, -use the format `<[A-Z_]+>` for the placeholder value: `<MY_VARIABLE>` - -```text -export name=<MY_NAME> -``` - -This syntax is reserved for variable names, and will cause the variable to -be rendered in a special color and font style. - -## Highlight lines - -```text {hl_lines=[7,8]} -incoming := map[string]interface{}{ - "asdf": 1, - "qwer": []interface{}{}, - "zxcv": []interface{}{ - map[string]interface{}{}, - true, - int(1e9), - "tyui", - }, -} -``` - -````markdown -```go {hl_lines=[7,8]} -incoming := map[string]interface{}{ - "asdf": 1, - "qwer": []interface{}{}, - "zxcv": []interface{}{ - map[string]interface{}{}, - true, - int(1e9), - "tyui", - }, -} -``` -```` - -## Collapsible code blocks - -```dockerfile {collapse=true} -# syntax=docker/dockerfile:1 - -ARG GO_VERSION="1.21" - -FROM golang:${GO_VERSION}-alpine AS base -ENV CGO_ENABLED=0 -ENV GOPRIVATE="github.com/foo/*" -RUN apk add --no-cache file git rsync openssh-client -RUN mkdir -p -m 0700 ~/.ssh && ssh-keyscan github.com >> ~/.ssh/known_hosts -WORKDIR /src - -FROM base AS vendor -# this step configure git and checks the ssh key is loaded -RUN --mount=type=ssh <<EOT - set -e - echo "Setting Git SSH protocol" - git config --global url."git@github.com:".insteadOf "https://github.com/" - ( - set +e - ssh -T git@github.com - if [ ! "$?" = "1" ]; then - echo "No GitHub SSH key loaded exiting..." - exit 1 - fi - ) -EOT -# this one download go modules -RUN --mount=type=bind,target=. \ - --mount=type=cache,target=/go/pkg/mod \ - --mount=type=ssh \ - go mod download -x - -FROM vendor AS build -RUN --mount=type=bind,target=. \ - --mount=type=cache,target=/go/pkg/mod \ - --mount=type=cache,target=/root/.cache \ - go build ... -``` - -## Bash - -Use the `bash` language code block when you want to show a Bash script: - -```bash -#!/usr/bin/bash -echo "deb https://download.docker.com/linux/ubuntu noble stable" | sudo tee /etc/apt/sources.list.d/docker.list -``` - -If you want to show an interactive shell, use `console` instead. -In cases where you use `console`, make sure to add a dollar character -for the user sign: - -```console -$ echo "deb https://download.docker.com/linux/ubuntu noble stable" | sudo tee /etc/apt/sources.list.d/docker.list -``` - -## Go - -```go -incoming := map[string]interface{}{ - "asdf": 1, - "qwer": []interface{}{}, - "zxcv": []interface{}{ - map[string]interface{}{}, - true, - int(1e9), - "tyui", - }, -} -``` - -## PowerShell - -```powershell -Install-Module DockerMsftProvider -Force -Install-Package Docker -ProviderName DockerMsftProvider -Force -[System.Environment]::SetEnvironmentVariable("DOCKER_FIPS", "1", "Machine") -Expand-Archive docker-18.09.1.zip -DestinationPath $Env:ProgramFiles -Force -``` - -## Python - -```python -return html.format(name=os.getenv('NAME', "world"), hostname=socket.gethostname(), visits=visits) -``` - -## Ruby - -```ruby -docker_service 'default' do - action [:create, :start] -end -``` - -## JSON - -```json -"server": { - "http_addr": ":4443", - "tls_key_file": "./fixtures/notary-server.key", - "tls_cert_file": "./fixtures/notary-server.crt" -} -``` - -#### HTML - -```html -<!DOCTYPE html> -<html> -<head> -<title>Welcome to nginx! - - -``` - -## Markdown - -```markdown -# Hello -``` - -If you want to include a triple-fenced code block inside your code block, -you can wrap your block in a quadruple-fenced code block: - -`````markdown -````markdown -# Hello - -```go -log.Println("did something") -``` -```` -````` - -## ini - -```ini -[supervisord] -nodaemon=true - -[program:sshd] -command=/usr/sbin/sshd -D -``` - -## Dockerfile - -```dockerfile -# syntax=docker/dockerfile:1 - -FROM ubuntu - -RUN apt-key adv --keyserver hkp://p80.pool.sks-keyservers.net:80 --recv-keys B97B0AFCAA1A47F044F244A07FCC7D46ACCC4CF8 - -RUN echo "deb http://apt.postgresql.org/pub/repos/apt/ precise-pgdg main" > /etc/apt/sources.list.d/pgdg.list - -RUN apt-get update && apt-get install -y python-software-properties software-properties-common postgresql-9.3 postgresql-client-9.3 postgresql-contrib-9.3 - -# Note: The official Debian and Ubuntu images automatically ``apt-get clean`` -# after each ``apt-get`` - -USER postgres - -RUN /etc/init.d/postgresql start &&\ - psql --command "CREATE USER docker WITH SUPERUSER PASSWORD 'docker';" &&\ - createdb -O docker docker - -RUN echo "host all all 0.0.0.0/0 md5" >> /etc/postgresql/9.3/main/pg_hba.conf - -RUN echo "listen_addresses='*'" >> /etc/postgresql/9.3/main/postgresql.conf - -EXPOSE 5432 - -VOLUME ["/etc/postgresql", "/var/log/postgresql", "/var/lib/postgresql"] - -CMD ["/usr/lib/postgresql/9.3/bin/postgres", "-D", "/var/lib/postgresql/9.3/main", "-c", "config_file=/etc/postgresql/9.3/main/postgresql.conf"] -``` - -## YAML - -```yaml -authorizedkeys: - image: dockercloud/authorizedkeys - deployment_strategy: every_node - autodestroy: always - environment: - - AUTHORIZED_KEYS=ssh-rsa AAAAB3Nsomelongsshkeystringhereu9UzQbVKy9o00NqXa5jkmZ9Yd0BJBjFmb3WwUR8sJWZVTPFL - volumes: - /root:/user:rw -``` diff --git a/content/contribute/components/icons.md b/content/contribute/components/icons.md deleted file mode 100644 index b89533075d..0000000000 --- a/content/contribute/components/icons.md +++ /dev/null @@ -1,151 +0,0 @@ ---- -description: Icons used across docs -title: Icons -grid: - - title: "Install" - icon: "download" - description: Icon name = download - - title: "FAQs" - icon: "help" - description: Icon name = help - - title: "Onboarding/quickstarts" - icon: "explore" - description: Icon name = explore - - title: "Release notes" - icon: "note_add" - description: Icon name = note_add - - title: "Feedback" - icon: "sms" - description: Icon name = sms - - title: "Multi-platform/arch" - icon: "content_copy" - description: Icon name = content_copy - - title: "Rootless/ECI" - icon: "security" - description: Icon name = security - - title: "Settings management" - icon: "shield_lock" - description: Icon name = shield_lock - - title: "Processes" - icon: "checklist" - description: Icon name = checklist - - title: "Networking" - icon: "network_node" - description: Icon name = network_node - - title: "Exploring a feature" - icon: "feature_search" - description: Icon name = feature_search - - title: "Company" - icon: "apartment" - description: Icon name = apartment - - title: "Organization" - icon: "store" - description: Icon name = store - - title: "Additional resources" - icon: "category" - description: Icon name = category - - title: "Designing" - icon: "design_services" - description: Icon name = design_services - - title: "Publishing" - icon: "publish" - description: Icon name = publish - - title: "Interacting" - icon: "multiple_stop" - description: Icon name = multiple_stop - - title: "Storage" - icon: "database" - description: Icon name = database - - title: "logs" - icon: "text_snippet" - description: Icon name = text_snippet - - title: "Prune/cut" - icon: "content_cut" - description: Icon name = content_cut - - title: "Configure" - icon: "tune" - description: Icon name = tune - - title: "Deprecated" - icon: "folder_delete" - description: Icon name = folder_delete - - title: "RAM" - icon: "home_storage" - description: Icon name = home_storage - - title: "IAM" - icon: "photo_library" - description: Icon name = photo_library - - title: "Packaging" - icon: "inventory_2" - description: Icon name = inventory_2 - - title: "Multi-stage" - icon: "stairs" - description: Icon name = stairs - - title: "Architecture" - icon: "construction" - description: Icon name = construction - - title: "Build drivers" - icon: "engineering" - description: Icon name = engineering - - title: "Export" - icon: "output" - description: Icon name = output - - title: "Cache" - icon: "cycle" - description: Icon name = cycle - - title: "Bake" - icon: "cake" - description: Icon name = cake - - title: "Docker ID" - icon: "fingerprint" - description: Icon name = fingerprint - - title: "Repository" - icon: "inbox" - description: Icon name = inbox - - title: "Access tokens" - icon: "password" - description: Icon name = password - - title: "official images" - icon: "verified" - description: Icon name = verified - - title: "Hardened Docker Desktop" - icon: "lock" - description: Icon name = lock - - title: "Sign in" - icon: "passkey" - description: Icon name = passkey - - title: "SSO and SCIM" - icon: "key" - description: Icon name = key - - title: "2FA" - icon: "phonelink_lock" - description: Icon name = phonelink_lock - - title: "Add/update payment method" - icon: "credit_score" - description: Icon name = credit_score - - title: "Update billing info" - icon: "contract_edit" - description: Icon name = contract_edit - - title: "Billing history" - icon: "payments" - description: Icon name = payments - - title: "Upgrade" - icon: "upgrade" - description: Icon name = upgrade - - title: "Add/manage more seats/users" - icon: "group_add" - description: Icon name = group_add - - title: "Domains" - icon: "domain_verification" - description: Icon name = domain_verification - - title: Company owner - description: Icon name = supervised_user_circle - icon: supervised_user_circle - - title: "General settings" - icon: "settings" - description: Icon name = settings ---- - -Below is an inventory of the icons we use to represent different topics or features across docs. To be used with the [cards component](cards.md). - -{{< grid >}} - diff --git a/content/contribute/components/images.md b/content/contribute/components/images.md deleted file mode 100644 index 305334c283..0000000000 --- a/content/contribute/components/images.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Images -toc_max: 3 ---- - -## Example - -- A small image: ![a small image](/assets/images/footer_moby_icon.png) - -- 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 query parameters: `?h=&w=` - - ![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) - -- 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 query parameters: `?h=&w=` - - ![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) -``` diff --git a/content/contribute/components/links.md b/content/contribute/components/links.md deleted file mode 100644 index d5fed2fd4a..0000000000 --- a/content/contribute/components/links.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Links -toc_max: 3 ---- - -## Examples - -[External links](https://docker.com) and [internal links](links.md) both -open in the same tab. - -Use relative links, using source filenames. - -#### Links to auto-generated content - -When you link to heading IDs in auto-generated pages, such as CLI -reference content, you won't get any help from your editor in resolving the -anchor names. That's because the pages are generated at build-time and your -editor or LSP doesn't know about them in advance. - -## Syntax - -```md -[External links](https://docker.com) -[Internal links](links.md) -``` diff --git a/content/contribute/components/lists.md b/content/contribute/components/lists.md deleted file mode 100644 index 551b47af88..0000000000 --- a/content/contribute/components/lists.md +++ /dev/null @@ -1,79 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Lists -toc_max: 3 ---- - -## Examples - -Use dashes (`-`) or asterisks (`*`) for bullet points. - -- Bullet list item 1 -- Bullet list item 2 -- Bullet list item 3 - -1. Numbered list item 1. Two spaces between the period and the first letter - helps with alignment. - -2. Numbered list item 2. Let's put a note in it. - - > [!NOTE]: We did it! - -3. Numbered list item 3 with a code block in it. You need the blank line before - the code block happens. - - ```bash - $ docker run hello-world - ``` - -4. Numbered list item 4 with a bullet list inside it and a numbered list - inside that. - - - Sub-item 1 - - Sub-item 2 - - 1. Sub-sub-item 1 - 2. Sub-sub-item-2 with a table inside it because we like to party! - Indentation is super important. - - | Header 1 | Header 2 | - | -------- | -------- | - | Thing 1 | Thing 2 | - | Thing 3 | Thing 4 | - -## Markdown - -````md -- Bullet list item 1 -- Bullet list item 2 -- Bullet list item 3 - -1. Numbered list item 1. Two spaces between the period and the first letter - helps with alignment. - -2. Numbered list item 2. Let's put a note in it. - - > [!NOTE]: We did it! - -3. Numbered list item 3 with a code block in it. You need the blank line before - the code block happens. - - ```bash - $ docker run hello-world - ``` - -4. Numbered list item 4 with a bullet list inside it and a numbered list - inside that. - - - Sub-item 1 - - Sub-item 2 - - 1. Sub-sub-item 1 - 2. Sub-sub-item-2 with a table inside it. - Indentation is super important. - - | Header 1 | Header 2 | - | -------- | -------- | - | Thing 1 | Thing 2 | - | Thing 3 | Thing 4 | -```` diff --git a/content/contribute/components/tables.md b/content/contribute/components/tables.md deleted file mode 100644 index 1631bafb2b..0000000000 --- a/content/contribute/components/tables.md +++ /dev/null @@ -1,54 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Tables -toc_max: 3 ---- - -## Example - -### Basic table - -| Permission level | Access | -| :----------------------------------------------------------------------- | :------------------------------------------------------------ | -| **Bold** or _italic_ within a table cell. Next cell is empty on purpose. | | -| | Previous cell is empty. A `--flag` in mono text. | -| Read | Pull | -| Read/Write | Pull, push | -| Admin | All of the above, plus update description, create, and delete | - -### Feature-support table - -| Platform | x86_64 / amd64 | -| :--------- | :------------: | -| Ubuntu | ✅ | -| Debian | ✅ | -| Fedora | | -| Arch (btw) | ✅ | - -## Markdown - -### Basic table - -```md -| Permission level | Access | -| :----------------------------------------------------------------------- | :------------------------------------------------------------ | -| **Bold** or _italic_ within a table cell. Next cell is empty on purpose. | | -| | Previous cell is empty. A `--flag` in mono text. | -| Read | Pull | -| Read/Write | Pull, push | -| Admin | All of the above, plus update description, create, and delete | -``` - -The alignment of the cells in the source doesn't really matter. The ending pipe -character is optional (unless the last cell is supposed to be empty). - -### Feature-support table - -```md -| Platform | x86_64 / amd64 | -| :--------- | :------------: | -| Ubuntu | ✅ | -| Debian | ✅ | -| Fedora | | -| Arch (btw) | ✅ | -``` diff --git a/content/contribute/components/tabs.md b/content/contribute/components/tabs.md deleted file mode 100644 index ceca66e690..0000000000 --- a/content/contribute/components/tabs.md +++ /dev/null @@ -1,99 +0,0 @@ ---- -description: components and formatting examples used in Docker's docs -title: Tabs -toc_max: 3 ---- - -The tabs component consists of two shortcodes: - -- `{{}}` -- `{{}}` - -The `{{}}` shortcode is a parent, component, wrapping a number of `tabs`. -Each `{{}}` is given a name using the `name` attribute. - -You can optionally specify a `group` attribute for the `tabs` wrapper to indicate -that a tab section should belong to a group of tabs. See [Groups](#groups). - -## Example - -{{< tabs >}} -{{< tab name="JavaScript">}} - -```js -console.log("hello world") -``` - -{{< /tab >}} -{{< tab name="Go">}} - -```go -fmt.Println("hello world") -``` - -{{< /tab >}} -{{< /tabs >}} - -## Markup - -````markdown -{{}} -{{}} - -```js -console.log("hello world") -``` - -{{}} -{{}} - -```go -fmt.Println("hello world") -``` - -{{}} -{{}} -```` - -## Groups - -You can optionally specify a tab group on the `tabs` shortcode. -Doing so will synchronize the tab selection for all of the tabs that belong to the same group. - -### Tab group example - -The following example shows two tab sections belonging to the same group. - -{{< tabs group="code" >}} -{{< tab name="JavaScript">}} - -```js -console.log("hello world") -``` - -{{< /tab >}} -{{< tab name="Go">}} - -```go -fmt.Println("hello world") -``` - -{{< /tab >}} -{{< /tabs >}} - -{{< tabs group="code" >}} -{{< tab name="JavaScript">}} - -```js -const res = await fetch("/users/1") -``` - -{{< /tab >}} -{{< tab name="Go">}} - -```go -resp, err := http.Get("/users/1") -``` - -{{< /tab >}} -{{< /tabs >}} diff --git a/content/contribute/components/videos.md b/content/contribute/components/videos.md deleted file mode 100644 index 72b27635ca..0000000000 --- a/content/contribute/components/videos.md +++ /dev/null @@ -1,66 +0,0 @@ ---- -description: Learn about guidelines and best practices for videos in docs, and how to add a video component. -title: Videos -toc_max: 3 ---- - -## Video guidelines - -Videos are used rarely in Docker's documentation. When used, video should complement written text and not be the sole format of documentation. Videos can take longer to produce and be more difficult to maintain than written text or even screenshots, so consider the following before adding video: - -- Can you demonstrate a clear customer need for using video? -- Does the video offer new content, rather than directly reading or re-purposing official documentation? -- If the video contains user interfaces that may change regularly, do you have a maintenance plan to keep the video fresh? -- Does the [voice and tone](../style/voice-tone.md) of the video align with the rest of the documentation? -- Have you considered other options, such as screenshots or clarifying existing documentation? -- Is the quality of the video similar to the rest of Docker's documentation? -- Can the video be linked or embedded from the site? - -If all of the above criteria are met, you can reference the following best practices before creating a video to add to Docker documentation. - -### Best practices - -- Determine the audience for your video. Will the video be a broad overview for beginners, or will it be a deep dive into a technical process designed for an advanced user? -- Videos should be less than 5 minutes long. Keep in mind how long the video needs to be to properly explain the topic, and if the video needs to be longer than 5 minutes, consider text, diagrams, or screenshots instead. These are easier for a user to scan for relevant information. -- Videos should adhere to the same standards for accessibility as the rest of the documentation. -- Ensure the quality of your video by writing a script (if there's narration), making sure multiple browsers and URLs aren't visible, blurring or cropping out any sensitive information, and using smooth transitions between different browsers or screens. - -Videos are not hosted in the Docker documentation repository. To add a video, you can [link to](./links.md) hosted content, or embed using an [iframe](#iframe). - - -## iframe - -To embed a video on a docs page, use an ` -``` - -## asciinema - -`asciinema` is a command line tool for recording terminal sessions. The -recordings can be embedded on the documentation site. These are similar to -`console` code blocks, but since they're playable and scrubbable videos, they -add another level of usefulness over static codeblocks in some cases. Text in -an `asciinema` "video" can also be copied, which makes them more useful. - -Consider using an `asciinema` recording if: - -- The input/output of the terminal commands are too long for a static example - (you could also consider truncating the output) -- The steps you want to show are easily demonstrated in a few commands -- Where the it's useful to see both inputs and outputs of commands - -To create an `asciinema` recording and add it to docs: - -1. [Install](https://docs.asciinema.org/getting-started/) the `asciinema` CLI -2. Run `asciinema auth` to configure your client and create an account -3. Start a new recording with `asciinema rec` -4. Run the commands for your demo and stop the recording with `` or `exit` -5. Upload the recording to -6. Embed the player with a `