diff --git a/docs/guides/linode-writers-formatting-guide/index.md b/docs/guides/linode-writers-formatting-guide/index.md index 896132f5509..c6e6aaf03ea 100644 --- a/docs/guides/linode-writers-formatting-guide/index.md +++ b/docs/guides/linode-writers-formatting-guide/index.md @@ -19,34 +19,114 @@ _build: ![Linode Writer's Formatting Guide](linode-writers-formatting-guide.png) -## Write Guides for Linode +## Writing Guidelines for Akamai Linode Documentation -This guide provides templates and guidelines to use when creating or updating a guide for [Linode Docs](/docs/). +This guide outlines how to submit content, including formatting standards, style guidelines, and workflows to use when creating or updating a guide for [Linode Docs](/docs/), a part of Akamai Cloud Computing. -Updates, improvements, and bug fixes to Linode documentation are always welcome through [GitHub](https://github.com/linode/docs) via pull requests (PRs) or issues. +Updates, improvements, and bug fixes to documentation are always welcome through [GitHub](https://github.com/linode/docs) via pull requests (PRs) or issues. -Through our Write For Linode program, authors can contribute new guides and be paid for their work. We ask that interested authors apply to the program with one or more writing samples so that we can evaluate your work. To learn more about the program and to complete an application, please visit our Write For Linode [program page](https://www.linode.com/lp/write-for-linode/). +Through our Write for Linode program, contributor's can and are invited to submit new guides and be compensated for accepted work. If you are interested, we encourage you to apply with one or more writing samples so that we can evaluate your style and technical clarity. To learn more and apply, visit the [Write For Linode program page](https://www.linode.com/lp/write-for-linode/). ## General Layout -Linode Guides & Tutorials are written in [Markdown](https://en.wikipedia.org/wiki/Markdown). Our documentation site uses [Hugo](https://gohugo.io), a static site generator. Hugo-specific Markdown formatting notes are given [further below](#markdown-formatting). +Linode guides and tutorials are written in [Markdown](https://en.wikipedia.org/wiki/Markdown) and rendered using [Hugo](https://gohugo.io), a static site generator. Hugo-specific Markdown formatting examples are provided throughout this guide. -Markdown files for guides are stored under the `docs/guides/` content directory. This content directory is then further subdivided into categories for different technical topics. New guides should be placed with a category that they most closely align with. For example, if you are writing a new guide on the Apache web server, it would be placed under `docs/guides/web-servers/apache/`. +### File References -A new subdirectory is created for each guide. This subdirectory should contain a file called `index.md`, which will be where the guide's Markdown is written to. For example, if your guide's title is `My Apache Guide`, then you would create its Markdown file at `docs/guides/web-servers/apache/my-apache-guide/index.md`. +Markdown files for guides are stored under the `docs/guides/` content directory (folder), organized by technical topical categories. Place new guides in a category they most closely align with. -A [Hugo archetype](https://gohugo.io/content-management/archetypes/) is available to create new Markdown files. For example, if you wanted to create the `My Apache Guide` example guide, you could run this command from inside your cloned docs repository: +**Example**: A new guide about the Apache web server, would go in the `docs/guides/web-servers/apache/my-apache-guide/` subdirectory (folder). + +In that subdirectory `/my-apache-guide/` (folder) is a **file** called `index.md` containing the guide's Markdown content (`docs/guides/web-servers/apache/my-apache-guide/**index.md**`). + +### Creating New Guides (Formatting) + +Use [Hugo's archetype](https://gohugo.io/content-management/archetypes/) feature to create properly formatted new guide files. For example, to create the `My Apache Guide` example, run this command from inside your cloned docs repository: ```command hugo new -k content docs/guides/web-servers/apache/my-apache-guide/index.md ``` -### Header +## Content Structure + +### Guide Structuring + +Guides should be split into cohesive sections which flow from one sequence of events to the next. Each section title should be styled with an *H2* heading element, and each subsection with an *H3* heading so that scanning the **EXPLORE DOCS** left sidebar shows the reader an overview of what is contained in the selected section title. Use Title Case for each noun, adjective, verb, and adverb in the article title, H2, H3, and H4 headings. + +Structure sequential content using numbered steps within subsections, as shown below. + +For example: + +```text +## Using MySQL + +1. Log in to MySQL as the root user: + + ```command + mysql -u root -p + ``` + +1. When prompted, enter the root password. + +### Create a New MySQL User and Database + +1. In the example below, `testdb` is the name of the database, `testuser` is the user, and `password` is the user’s password. + + ```command + create database testdb; + grant all on testdb.* to 'testuser' identified by 'password'; + ``` + +1. Exit MySQL. + + ```command + exit + ``` + +### Create a Sample Table + +1. Log back in as `testuser`: + + ```command + mysql -u testuser -p + ``` +``` + +{{< note >}} +The tab size is set to four, and **only** soft tabs should be used. This can be configured in the settings of most text editors. +{{< /note >}} + +### Before You Begin + +Create a prerequisites section that tells your readers what they need before beginning your guide to complete it successfully. This may include: + +- Required Akamai services or features (e.g., Compute Instances, LKE clusters, or Object Storage buckets) as well as any necessary hardware or plan requirements (see [Pricing](https://www.linode.com/pricing/)). + +- Required software or applications (e.g., LAMP stack, Docker) with links to installation instructions. Only add software directly used within the guide but that is not the guide's primary focus. If the software requires additional configuration or usage information, include those details in the main guide instructions rather than in the **Before You Begin** section. + +- External requirements, such as a registered domain name or specific local software (e.g., a PC running Windows 11). + +- Foundational knowledge requirements, such as understanding technology fundamentals (e.g., container orchestration) or familiarity with specific software or software stacks (e.g., Kubernetes). + +Example *Before You Begin* section (copy and edit as needed): + +```text + +## Before You Begin + +1. If you do not already have a virtual machine to use, create a Compute Instance with at least 4 GB of memory. See our [Getting Started with Linode](https://techdocs.akamai.com/cloud-computing/docs/getting-started) and [Creating a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/create-a-compute-instance) guides. + +1. Follow our [Setting Up and Securing a Compute Instance](https://techdocs.akamai.com/cloud-computing/docs/set-up-and-secure-a-compute-instance) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access. +``` + +### Metadata Header + +Linode guides and tutorials store metadata and other information in a [YAML](http://yaml.org/) header at the top of every page. If you notice a `deprecated` field in the header defaulted to false, only set it to *true* if you need to display a pre-written message stating that the guide is no longer maintained. This is typically used for guides covering applications or distributions that have reached End of Life (EOL). -Linode Guides & Tutorials store metadata and other information in a [YAML](http://yaml.org/) header at the top of every page. Use the template below for your own guide. +Use the template below as a guide. {{< note >}} -If you use the Hugo archetype command described in the previous section, the created Markdown file will be pre-populated with the frontmatter template below. +If you use the Hugo archetype command described in the previous section, the created Markdown file is pre-populated with the frontmatter template below. {{< /note >}} ```file {title="Author Submission" lang="yaml"} @@ -66,102 +146,228 @@ external_resources: --- ``` -If you're updating an existing guide in our repository, you may also notice a `deprecated` field in the header. This defaults to false, and setting it to *true* inserts a pre-written message near the beginning stating that the guide is no longer maintained. Typically, this will be used on guides specific to applications or distributions that have reached End of Life (EOL). - -### Introduction +### Introduction (section) -Introductions should be concise; explain what the goal of the guide is and why. If you're introducing new software to the system, include a brief description and link to its official website whenever possible. +Introductions should be concise; explain what the goal of the guide is. If you're introducing new software to the system, include a brief description and link to its official website whenever possible. -### Before You Begin - -The *Before You Begin* section is used to inform the reader of any prerequisites needed to successfully complete the guide. This may include the following: +### User privileges and sudo -- Specific Akamai services or features that are needed, like Compute Instances, LKE clusters, or Object Storage buckets. This should include any hardware or plan requirements (see [Pricing](https://www.linode.com/pricing/)). +This section describes how to handle user privileges and administrative access (for root and non-root access). -- Setup tasks on Akamai services, such as securing a Compute Instance, creating a limited user, configuring a hostname. Only include tasks that are related to the guide and the guide's objective. +**For Guides Using sudo (recommended for [security](https://www.linode.com/docs/guides/securing-your-lamp-stack/)):** -- External requirements, such as a registered domain name or specific local software (such as a PC running Windows 11). - -- Software or applications that need to be installed or configured (i.e. LAMP stack, Docker, etc.), making sure to include links to instructions. Only include software that is directly used within the guide, but is not the focus of the guide. If the software needs additional configuration or usage information, it should likely be included in the guide's instructions and not in the *Before You Begin* section. +{{}} +Commands requiring elevated privileges are prefixed with `sudo`. If you're not familiar with `sudo` or need help setting up user accounts, see our [Users and Groups](https://www.linode.com/docs/guides/linux-users-and-groups/) guide. +{{}} -- Foundational knowledge, like an understanding of technology fundamentals (like container orchestration) or specific software or software stacks (like Kubernetes). +**For guides requiring root access:** -Below is an example *Before You Begin* section. You may copy the example and edit it as needed: +{{}} This guide requires root privileges. Ensure you're logged in as root or use `sudo` with each command. For more information on user privileges, see our [Users and Groups](https://www.linode.com/docs/guides/linux-users-and-groups/#working-with-linux-groups-users-and-directories) guide. +{{}} -```file {title="Before You Begin"} -## Before You Begin +### Headings -1. If you do not already have a virtual machine to use, create a Compute Instance with at least 4 GB of memory. See our [Getting Started with Linode](/docs/products/platform/get-started/) and [Creating a Compute Instance](/docs/products/compute/compute-instances/guides/create/) guides. +Headings should be written in title case and can be up to 3 levels deep. -1. Follow our [Setting Up and Securing a Compute Instance](/docs/products/compute/compute-instances/guides/set-up-and-secure/) guide to update your system. You may also wish to set the timezone, configure your hostname, create a limited user account, and harden SSH access. -``` +| Syntax | Output | +| -- | -- | +| `## Section title (h2)` | approx. 18-24pt **Section title (h2)** | +| `### Subsection (h3)` | approx. 16-20pt **Subsection (h3)** | +| `#### Subsection (h4)` | approx. 14-18pt **Subsection (h4)** | -### Include a Note about Root or Non-Root users +Font sizes are approximate and depend on your site's theme or editor. -```file {title="Guides Written for a Non-Root User" lang="txt"} -{{}} -This guide is written for a non-root user. Commands that require elevated privileges are prefixed with `sudo`. If you’re not familiar with the `sudo` command, see the [Users and Groups](/docs/guides/linux-users-and-groups/) guide. -{{}} -``` +### Lists -```file {title="Guides Written for a Root User" lang="txt"} -{{}} -The steps in this guide require root privileges. Be sure to run the steps below as `root` or with the `sudo` prefix. For more information on privileges, see our [Users and Groups](/docs/guides/linux-users-and-groups/) guide. -{{}} -``` +#### Ordered Lists -## Paragraph Structure +Ordered lists are numbered and should be used to indicate a series of steps or other content that follows a defined sequence (i.e., apps to be installed in a certain order). Sequential procedures and step-by-step instructions should always use numbered lists rather than bullet points to emphasize the proper order. Use the following guidance when creating ordered lists: -Guides should be split into cohesive sections which flow from one sequence of events to the next. Each section title should be styled with an *H2* heading element, and each subsection with an *H3* heading so that scanning the *In This Guide* left sidebar should give the reader an overview of what will be done in the guide. Capitalize each noun, adjective, verb and adverb in the article title, H2 and H3 headers. +- **Longer lists that may change and where nested content is possible:** -Each **subsection** should be split into numbered steps as shown below. + These lists should use *lazy* numbering (by appending a `1.` to each step regardless of the actual step number). There should also be *two* spaces between the numbering and the text (see [Nested Content Within Lists](#nested-content-within-lists)). -For example: + ```command + 1. Step 1 + 1. Step 2 + 1. Step 3 + ``` -```file {lang="md"} -## Using MySQL +- **Short lists that remain static with no nested content:** -1. Log in to MySQL as the root user: + Optionally, you can use *true* numbering when a list is likely to remain short and static during its lifecycle. Provided there is no nested content, use a single space between the number and the text. ```command - mysql -u root -p + 1. Step 1 + 2. Step 2 + 3. Step 3 ``` -1. When prompted, enter the root password. +#### Unordered Lists -### Create a New MySQL User and Database +Unordered lists are bulleted and used for any collection of items that do not necessarily need to be ordered. These lists should be formatted by appending a `- ` to the beginning of each step. -1. In the example below, `testdb` is the name of the database, `testuser` is the user, and `password` is the user’s password. +- **Lists where nested content is possible:** + + Use *three* spaces between the bullet character (`-`) and the text. (see [Nested Content Within Lists](#nested-content-within-lists)). ```command - create database testdb; - grant all on testdb.* to 'testuser' identified by 'password'; + - Item A + - Item B + - Item C ``` -1. Exit MySQL. +- **Lists with no nested content:** + + Provided there is no nested content, you can use a single space between the bullet character and the text. ```command - exit + - Item A + - Item B + - Item C ``` -### Create a Sample Table +#### Nested Content Within Lists -1. Log back in as `testuser`: +To remain consistent across all of our guides, nested content should be indented *four* spaces and a blank line should be used above and below the content. Our Markdown processor assumes nested content starts directly below the *first* character in the text of the list item above it. With this in mind, it's important to indent the text portion of the list item to match that four space indent. In practice, there should be *two* spaces after the number (for ordered lists) and *three* spaces after the bullet for unordered lists. If this spacing is not respected, the nested content may not render properly. + +- **Ordered list** (`1.`): Use *two* spaces after the number. +- **Unordered list** (`-`): Use *three* spaces after the bullet. + +````command +- Item A + + This sentence is nested under *Item A*. + +- Item B ```command - mysql -u testuser -p + This command is nested under *Item B*. ``` + +- Item C +```` +### Tables + +You can create tables using standard Markdown syntax. Additionally, you can embed a Markdown table within the [table shortcode](#table-shortcode) for additional functionality. + +```file {lang="md"} +| Column Header 1 | Column Header 2 | +| -- | -- | +| **Example** | This is an example of text in the second column. | ``` -{{< note >}} -The tab size is set to four, and **only** soft tabs should be used. This can be configured in the settings of most text editors. -{{< /note >}} +| Column Header 1 | Column Header 2 | +| -- | -- | +| **Example** | This is an example of text in the second column. | + +#### Column Text Alignment + +To align text within a table, modify the second row. This row separates the header from the body of the table and can be used for additional metadata, like text alignment. + +- Left aligned: Default behavior (if there is a need to be explicit, use `| :-- |`) +- Center aligned: `| :--: |` +- Right aligned: `| --: |` -## How to Use Markdown Formatting for Linode Style + +```file {lang="md"} +| Left-Aligned Text | Center-Aligned Text | Right-Aligned Text | +| -- | :--: | --: | +| Example | Example | Example | +``` + +| Left-Aligned Text | Center-Aligned Text | Right-Aligned Text | +| -- | :--: | --: | +| Example | Example | Example | + +#### Table Shortcode + +Table shortcode can be used to add additional functionality to Markdown tables. By default, it adds a scrollbar when the table width is larger than the content area. This means that it can accommodate wide tables with lots of columns. It also adds alternating row background colors so that tables are easier to parse. + +```file {lang="md"} +{{}} +| Column Header | Column Header | Column Header | +| -- | -- | -- | +| **Row 1** | Example | Example | +| **Row 2** | Example | Example | +| **Row 3** | Example | Example | +{{}} +``` + +{{< table >}} +| Column Header | Column Header | Column Header | +| -- | -- | -- | +| **Row 1** | Example | Example | +| **Row 2** | Example | Example | +| **Row 3** | Example | Example | +{{< /table >}} + +#### Fixed First Column + +If you are creating a wide table and need the first column to be fixed when scrolling, use the **"first-sticky"** class. + +```file {lang="text"} +{{}} +| Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | +| -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | +| **Row1**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | +| **Row2**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | +| **Row3**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | +{{}} +``` + +{{< table class="first-sticky" >}} +| Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | +| -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | +| **Row1**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | +| **Row2**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | +| **Row3**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | +{{< /table >}} + +### Tabs + +Using a tabbed interface allows you to separate content into user-selectable tabs. This can be used to provide specific instructions for different versions of a software application (like MySQL 5.7 or .8), different operating systems (like macOS, Windows, or a Linux distribution), or different user tools (like the Cloud Manager, Linode CLI, or Linode API). + +````file +{{}} +{{}} +The content only appears when *Tab 1* is selected. +{{}} +{{}} +When *Tab 2* is selected, this content appears. +{{}} +{{}} +```` + +{{< tabs >}} +{{< tab "Tab 1" >}} +The content only appears when *Tab 1* is selected. +{{< /tab >}} +{{< tab "Tab 2" >}} +When *Tab 2* is selected, this content appears. +{{< /tab >}} +{{< /tabs >}} + +When a user selects a tab, the first item in each tab set that has a matching title is also selected. This means that if multiple tab sets are on a page, each with the same items, the user only needs to select an item within one tab set then all tab sets will show that item. + +{{< tabs >}} +{{< tab "Tab 1" >}} +This is *Tab 1* content When *Tab 1* is selected in any tab set on the page, this content becomes visible. +{{< /tab >}} +{{< tab "Tab 2" >}} +And here is *Tab 2* content. When *Tab 2* is selected in any tab set on the page, this content becomes visible. +{{< /tab >}} +{{< /tabs >}} + +When a tab is selected, a `tab` parameter string appears in the URL along with the title of all selected tabs. For instance, if *Tab 2* is selected in the tab sets above, `?tabs=tab-2` is appended to the URL. This allows the URL to be saved or shared, keeping the same tabs selected on the page. + +## Markdown Text Formatting ### Abbreviations and Acronyms -Upon first mention of a new concept or software, use the full name or term, then note the abbreviation or acronym in parenthesis beside it. The abbreviation/acronym can then be used in the article from that point. For example: Lightweight Resource/Provider (LWRP). +Upon first mention of a new concept or software, use the full name or term, then note the abbreviation or acronym in parentheses following it. The you can used the abbreviation/acronym in the article from that point forward. For example: Lightweight Resource/Provider (LWRP). Another example is: Virtual Private Server (VPS)" or "Content Delivery Network (CDN)". In longer guides spanning several pages, reintroduce the full term with the abbreviation in parentheses when it reappears after several pages of content. + +### New Terms Introduce new terms in italics with a `*` on either side of the term: @@ -173,16 +379,24 @@ This guide covers how to install Git, a *version control system*. ### Bold and Italics -Use a **Bold** font weight for buttons, menu selections and anything that requires emphasis or that you want to stand out to the reader. *Italicize* new terms and concepts the first time they are used. +Use a **Bold** font weight for buttons, menu selections, and anything that requires emphasis or that you want to stand out to your users. + +*Italicize* new terms and concepts the first time they are used. | Syntax | Output | | -- | -- | | `**bold**` | **bold** | | `*italics*` | *italics* | +### Sentence Spacing + +Use single spaces between sentences; do not double-space. + +## Code Elements + ### Commands -Commands that are not inline with paragraph text should be displayed with the *command shortcode*. This shortcode renders the command in a monospaced font with a light or dark background and a copy-to-clipboard button. Unlike other shortcodes (e.g. `content`, `note`, `caution`, etc), the command shortcode should be referenced with Markdown's *code fence* syntax. +Commands that are not inline with paragraph text should be displayed with the *command shortcode*. This shortcode renders the command in a monospaced font with a light or dark background and a copy-to-clipboard button. Unlike other shortcodes (e.g., `content`, `note`, `caution`, etc.), the command shortcode should be referenced using Markdown's **code fence** syntax. - **Command shortcode example** @@ -218,7 +432,7 @@ Commands that are not inline with paragraph text should be displayed with the *c - **Command with title** - The `title` parameter can be used to specify a title that displayed above a command shortcode. This can be useful to label the server or workstation that a reader should execute the command on. For example, some guides instruct the reader to set up multiple servers. Specifying a title can disambiguate which server a given command should be run on. + The `title` parameter can be used to specify a title that is displayed above a command shortcode. This can help identify which server or workstation the reader should execute the command on. For example, when guides involve multiple servers, specifying a title helps clarify which one a command applies to. ````file ```command {title="Web server"} @@ -242,7 +456,7 @@ Commands that are not inline with paragraph text should be displayed with the *c - **Command with dark background** - The `class` parameter can be used to specify that a command should be displayed with a dark background: + The `class` parameter is used to specify that a command should be displayed with a dark background: ````file ```command {class="dark"} @@ -258,7 +472,7 @@ Commands that are not inline with paragraph text should be displayed with the *c ### Commands (Deprecated Syntax) -In some existing guides, you may see commands displayed without the command shortcode. In these instances, the commands are simply indented with a tab or four spaces in the Markdown source text. For example: +In some existing guides, you may see commands displayed without the `command` shortcode. In these instances, the commands are just indented with a tab or four spaces in the Markdown source text to achieve code block formatting. This legacy approach is still valid for rendering purposes but does not support enhanced functionality like labeling or syntax tagging. For example: ```file {lang="md"} Run the following command to restart Apache: @@ -266,11 +480,15 @@ Run the following command to restart Apache: sudo systemctl restart apache2 ``` -*The older (tab or four space-indent) syntax should not be used for new content.* The code shortcode renders a copy-to-clipboard button for the reader's convenience, and the old syntax does not provide this feature. +**Note**: *The older syntax (tab or four space-indent) should not be used for new content.* The shortcode renders a copy-to-clipboard button for the reader's convenience, and the old syntax does not provide this feature. Instead, use the command shortcode: + +```command +sudo systemctl restart apache2 +``` ### Inline Commands -Inline commands should be denoted by backticks. +Inline commands should be enclosed in backticks. ```file {lang="md"} Update your system by running `yum update`. @@ -278,101 +496,115 @@ Update your system by running `yum update`. **Output:** Update your system by running `yum update`. -### Example IP Addresses - -When referencing IP address in the documentation, any real address should be obscured unless it is intended for the user to access that IP address. When possible, use the documentation address blocks given in [IETF RFC 5737](https://tools.ietf.org/html/rfc5737) and [IETF RFC 3849](https://datatracker.ietf.org/doc/html/rfc3849). +### Terminal Output -- **IPv4:** 192.0.2.0/24, 198.51.100.0/24, 203.0.113.0/24 +Output from terminal commands should be displayed with the *output shortcode*: - *Examples:* 192.0.2.84, 192.0.2.142, 198.51.100.65, 198.51.100.231, 203.0.113.2, 203.0.113.97 +````file +```output +Hello world! +``` +```` - In general, use these address blocks in order. Use the first block (`192.0.2.0/24`) for the first example IP address that is needed. If another IP address is needed, pull from the next block. If the example text is referencing the IPv4 address of a Compute Instance, do not use 0 or 1 as the last segment of the IP address as they are not used for Compute Instances. For instance, `192.0.2.17` is acceptable but `192.0.2.0` and `192.0.2.1` are not. +The above shortcode is rendered as: -- **IPv6:** 2001:DB8::/32 +```output +Hello world! +``` - *Examples:* 2001:db8:1:1:1:1:1:1, 2001:db8::f03c:485f:b84e:6534 +Here's an example of a command (using the command shortcode) and its output (using the output shortcode) displayed together: -### External Resources/More Information +````file +```command +echo "Hello world!" +``` -If you wish to provide links to external sites for the user to review after going through your guide, do so using the `external_resources` parameter in the [page header](#header). This will automatically appear as a text block with links at the bottom of the page. +```output +Hello world! +``` +```` -> More Information -> -> You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials. -> -> - [Link Title 1](http://www.example.com) -> - [Link Title 2](http://www.example.net) +The above shortcodes are rendered as: -### Extend Markdown Using Shortguides +```command +echo "Hello world!" +``` -Using shortcodes, it is possible to extend a Markdown file with another. For common tasks such as basic software installation, consider using the `content` shortcode. This allows our library to maintain consistent and up to date installation instructions for frequently used tools such as Python, MySQL, and Docker. +```output +Hello world! +``` -Markdown files intended to be inserted into multiple guides are called shortguides. To create a shortguide, create a directory with the name of your shortguide anywhere within `docs/`, and then create an index.md within the directory for your content (e.g. `example-shortguide-name/index.md`). +### Terminal Output (Deprecated Syntax) -Inserting `headless: true` in the front matter will hide the guide from the site navigation as well as the search index. +In some existing guides, you may see this older shortcode syntax for displaying terminal output: -When using the `content` shortcode in a guide to embed a shortguide, the shortcode will take the name of your guide's directory (e.g. `example-shortguide-name`) as a parameter. A shortguide can be within a different part of the `docs` hierarchy from the guide that embeds it, so the guide directory name exists within a global namespace of all shortguides in the repository. In other words, two different shortguides can't use the same directory name. +```file +{{}} +Hello world! +{{}} +``` -To use an image in a shortguide, add the image to your shortguide's directory and then use the `image` shortcode to embed it: +This is equivalent to: -```file {title="sample_embedding_guide/index.md" lang="md"} -{{}} +````file +```output +Hello world! ``` +```` -#### Example Usage +*The older syntax should not be used for new content.* While they are rendered with the same presentation by Hugo, they are not displayed the same in the GitHub.com UI. When viewing a Markdown file in the library on GitHub, using the newer code fence shortcode syntax will have enhanced styling, compared to the older shortcode syntax. -The following shortguide describes how to install Python via Miniconda. Create a directory named `install_python_miniconda` and filed named `index.md` within it: +### Placeholders -```file {title="install_python_miniconda/index.md" lang="yaml"} ---- -title: "Install Python with Miniconda" -description: 'A shortguide that shows how to install Python via Miniconda.' -keywords: [] -license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' -contributors: ["Author's FirstName LastName`"] -published: 2023-03-07 -modified: 2023-03-07 -headless: true -show_on_rss_feed: false ---- +The placeholder shortcode applies special formatting to highlight the user-replaceable portion of a command or file. It can also be used within a paragraph as a way to reference what the user should replace. - +- **Syntax:** `{{}}`
+- **Output:** {{< placeholder "VARIABLE_NAME" >}} -1. Download and install Miniconda: +When creating a placeholder, you can use either a descriptive variable name (like `VARIABLE_NAME`) or example text (like `example.com`). - ```command - curl -OL https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh - bash Miniconda3-latest-Linux-x86.64.sh - ``` +- **Placeholder example text:** A generic example that represents the expected user input. For instance, example IP addresses (`192.0.2.17`) and example domain names (`example.com`). This should be in the same case as the surrounding text, using whatever formatting is appropriate for the example text. For IP addresses, review the [Example IP Addresses](#example-ip-addresses) section. +- **Placeholder variable:** A short descriptive variable name. This should be formatted in uppercase with an underscore (`_`) used instead of spaces. For instance, `REGION_ID` and `FILE_NAME`. -1. You will be prompted several times during the installation process. Review the terms and conditions and select "yes" for each prompt. +The following example demonstrates a common use case for the placeholder shortcode. -1. Check your Python version: +- **Markdown syntax:** - ```command - python --version + ```` + Within the default NGINX configuration file, replace {{}} with your website's domain. + + ```file {title="/etc/nginx/sites-available/default"} + server { + listen 80; + listen [::]:80; + server_name {{}}; + } ``` -``` + ```` -To use this shortguide in another guide, use the following syntax: +- **Output:** -```file {title="sample_embedding_guide/index.md"} -{{%/* content "install_python_miniconda" */%}} -``` + Within the default NGINX configuration file, replace {{< placeholder "example.com" >}} with your website's domain. -{{< note >}} -Be sure to use the `%` delimiter inside the surrounding `{{ }}` braces for `content` shortcodes. -{{< /note >}} + ```file {title="/etc/nginx/sites-available/default"} + server { + listen 80; + listen [::]:80; + server_name {{< placeholder "example.com" >}}; + } + ``` + +## File References ### Files -Use the *file shortcode* to present code examples, code snippets, and other text file contents in a guide. This shortcode renders the file content with line numbering, a specified filepath, syntax highlighting, and line highlighting. Unlike other shortcodes (e.g. `content`, `note`, `caution`, etc), the file shortcode should be referenced with Markdown's *code fence* syntax. +Use the *file shortcode* to present code examples, code snippets, and other text file contents in a guide. This shortcode renders the file content with line numbering, a specified filepath, syntax highlighting, and line highlighting. Unlike other shortcodes (e.g., `content`, `note`, `caution`, etc.), the file shortcode should be referenced with Markdown's *code fence* syntax. {{< note >}} Exceptionally long files should be shown in parts, if needed. In these cases, you can add the entire file to the same directory as your guide and link to it from within the guide. {{< /note >}} -- **File with filepath** +- **File with filepath** ````file ```file {title="/path/to/file.html"} @@ -390,9 +622,9 @@ Exceptionally long files should be shown in parts, if needed. In these cases, yo ``` -- **File with language/syntax highlighting** +- **File with language/syntax highlighting** - A code language or syntax can be defined with the `lang` parameter to set how the text is displayed. A list of supported languages can be found [on GitHub](https://github.com/alecthomas/chroma). + A code language or syntax can be defined with the `lang` parameter to set how the text is displayed. A list of supported languages can be found [on GitHub](https://github.com/alecthomas/chroma#supported-languages). ````file ```file {title="/path/to/file.html" lang="html"} @@ -410,9 +642,9 @@ Exceptionally long files should be shown in parts, if needed. In these cases, yo ``` -- **File with starting line specified** +- **File with starting line specified** - If your file snippet represents the middle of a file, you can use the `linenostart` to specify that the line numbering to the left of the snippet should start at a number other than 1: + If your file snippet represents the middle of a file, you can use the `linenostart` parameter to specify that the line numbering to the left of the snippet should start at a number other than 1: ````file ```file {title="/path/to/file.html" lang="html" linenostart="11"} @@ -430,7 +662,7 @@ Exceptionally long files should be shown in parts, if needed. In these cases, yo ``` -- **File with highlighted lines** +- **File with highlighted lines** The `hl_lines` parameter can be used to highlight certain lines within the file. The parameter is a space-separated list of strings. Ranges of lines can also be specified: @@ -462,21 +694,20 @@ Exceptionally long files should be shown in parts, if needed. In these cases, yo export default Header; ``` -- **Using file shortcodes within lists** +- **Using file shortcodes within lists** If using a file shortcode in a list, each line of the shortcode should start at the indentation level of the list. For example: - ```file 1. List item 1 1. List item 2 + If you want to include a file shortcode, format it like this: ```file {title="/path/to/file.html" lang="html"}
Sample file text
``` - ``` ### Files (Deprecated Syntax) @@ -495,12 +726,17 @@ This is equivalent to: ````file ```file {title="/path/to/file.html" lang="html"}
+ Sample file text
``` ```` -*The older syntax should not be used for new content.* While they are rendered with the same presentation by Hugo, they are not displayed the same in the GitHub.com UI. When viewing a Markdown file in the library on GitHub, the newer code fence shortcode syntax will have enhanced styling, compared with the older shortcode syntax. +{{< note >}} + +The older syntax should not be used for new content. Use the newer code fence syntax for consistency and better cross-platform compatibility. + +{{< /note >}} ### File Paths and File Names @@ -510,21 +746,20 @@ Inline file paths and file names should be formatted as inline code blocks. | -- | -- | | ``Navigate to `/var/www/html`.`` | Navigate to `/var/www/html`. | -### Headings +## Interactive Elements -Headings should be written in title case and can be up to 3 levels deep. +### Links -| Syntax | Output | -| -- | -- | -| `## Section title (h2)` | Section title (h2) | -| `### Subsection (h3)` | Subsection (h3) | -| `#### Subsection (h4)` | Subsection (h4) | +Internal links to other Linode guides should be relative, starting at `/docs/`, and external links should be formatted as shown below and use HTTPS URLs whenever possible. + +- **Internal link example:** `[Getting Started](/docs/products/platform/get-started/)` +- **External link example:** `[Apache HTTP Server Documentation](https://httpd.apache.org/docs/)` ### Images Images can add value to the surrounding text by providing context or additional meaning. In most cases, images within documentation take the form of screenshots or diagrams, though occasionally other types of images may be necessary. -- **Image format:** All images should a PNG (*.png*) or a JPEG (*.jpg* or *.jpeg*). +- **Image format:** All images should be a PNG (*.png*) or a JPEG (*.jpg* or *.jpeg*). - **Image size:** Images are displayed in their original size, up to the maximum width of the content area. If an image's width is larger than the width of the content area, the image is scaled down to fit within the content area and a user can click on the image to view it in a modal. @@ -540,11 +775,11 @@ To add an image to a guide, first move it the same directory as the guide or sho #### Image Recommendations -- **Image sizing:** The height of our images, especially screenshots, should be as minimal as possible. This is to avoid screenshots taking up a lot of vertical space within our documentation, which often results in visually breaking up content that otherwise should appear together. Our Cloud Manager favors vertically stacked fields and options, which can make it difficult to minimize the height of our screenshots. Use your best judgement when determining what part of the UI is needed to convey the required information. +- **Image sizing:** The height of our images, especially screenshots, should be as minimal as possible. This is to avoid screenshots taking up a lot of vertical space within our documentation, which often results in visually breaking up content that otherwise would appear together. Our Cloud Manager favors vertically stacked fields and options, which can make it difficult to minimize the height of our screenshots. Use your best judgement when determining what part of the UI is needed to convey the required information. - **Favor light mode over dark mode:** When an application (such as the Cloud Manager) has different themes or appearances, favor the default theme. If the theme automatically adjusts to your system's light or dark mode setting, verify that your system is using light mode or adjust the application setting to light mode. -- **Image composition:** Avoid including too much detail or information within an image. Many images are used to either show a result of an action (like displaying a web page) or are used to supplement instructions asking the reader to perform an action (like click a button). Images that show too much may confuse the reader or otherwise call attention to details that aren't important to the task at hand. In practice, this means not taking a screenshot of the entire application or browser window and instead focusing only on the UI elements related to the instructions or text. +- **Image composition:** Avoid including too much detail or information within an image. Many images are used to either show the result of an action (like displaying a web page) or are used to supplement instructions asking the reader to perform an action (like click a button). Images that show too much may confuse the reader or otherwise call attention to details that aren't important to the task at hand. In practice, this means not taking a screenshot of the entire application or browser window and instead focusing only on the UI elements related to the instructions or text. - **Remove personal information:** Ensure that all identifying attributes such as names and IP addresses are removed, obfuscated, or replaced with example text, such as **example_user** or an IP address from the **192.0.2.0/24** range. This aligns with a previous recommendation of only providing necessary detail and it keeps the writer's personal information from being shown to readers. This may involve using the browser's built-in development tools to manually replace values or delete information. @@ -552,111 +787,35 @@ To add an image to a guide, first move it the same directory as the guide or sho Since this image is larger than the width of the content, the image is scaled to fit. When the image is clicked, a modal appears that displays the image at a larger size. -This example image might be used to supplement instructions asking the reader to select a Compute Instance. Instead of taking a screenshot of the entire page in the Cloud Manager, the area has been cropped to just include relevant information. In addition, a red outline has been used to highlight the UI element that corresponds with the action the reader should perform. - -```file {lang="md"} -![Screenshot of Cloud Manager Compute Instance page with a single instance selected](compute_instance_list-select_instance.png "Select a Compute Instance from the list") -``` - -![Screenshot of Cloud Manager Compute Instance page with a single instance selected](compute_instance_list-select_instance.png "Select a Compute Instance from the list") - -#### Example Narrow Image - -Smaller images should be displayed using their true pixel size. When taking screenshots within some software on some operating systems, the pixel size is increased (likely to account for the operating system's scaling). For instance, taking a screenshot with the Skitch tool on macOS doubles the pixel count. In these cases, use another image editing tool (like macOS's built in preview) to scale down the image to match the intended pixel width. - -```file {lang="md"} -![Screenshot of the Create Firewall panel in the Cloud Manager](cloud_firewalls-create_panel.png) -``` - -![Screenshot of the Create Firewall panel in the Cloud Manager](cloud_firewalls-create_panel.png) - -### Key Combinations - -When instructing a reader to press hotkeys or other combinations of keys, enclose each individual key within a [kbd](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd) html element as shown in the example below. - -```file {lang=html} -Use Ctrl + C to copy text. -``` - -**Output:** Use Ctrl + C to copy text. - -### Links - -Internal links to other Linode guides should be relative, starting at `/docs/`, and external links should be formatted as shown below and use HTTPS URLs whenever possible. - -- **Internal link example:** `[Getting Started](/docs/products/platform/get-started/)` -- **External link example:** `[Apache HTTP Server Documentation](https://httpd.apache.org/docs/)` - -### Lists - -#### Ordered Lists - -Ordered lists are numbered and should be used to denote a series of steps or sequential items. Use the following guidance when creating ordered lists: - -- **Longer lists that may change and where nested content is possible:** - - These lists should use *lazy* numbering (by appending a `1.` to each step regardless of the actual step number). There should also be *two* spaces between the numbering and the text (see [Nested Content Within Lists](#nested-content-within-lists)). - - ```command - 1. Step 1 - 1. Step 2 - 1. Step 3 - ``` - -- **Short lists that remain static with no nested content:** - - Optionally, you can use *true* numbering when a list is likely to remain short and static during its lifecycle. Provided there is no nested content, use a single space between the number and the text. - - ```command - 1. Step 1 - 2. Step 2 - 3. Step 3 - ``` - -#### Unordered Lists - -Unordered lists are bulleted and should be used for any collection of items that do not necessarily need to be ordered. These lists should be formatted by appending a `- ` to the beginning of each step. - -- **Lists where nested content is possible:** - - Use *three* spaces between the bullet character (`-`) and the text. (see [Nested Content Within Lists](#nested-content-within-lists)). - - ```command - - Item A - - Item B - - Item C - ``` +This example image might be used to supplement instructions asking the reader to select a Compute Instance. Instead of taking a screenshot of the entire page in the Cloud Manager, the area has been cropped to just include relevant information. In addition, a red outline has been used to highlight the UI element that corresponds with the action the reader should perform. -- **Lists with no nested content:** +```file {lang="md"} +![Screenshot of Cloud Manager Compute Instance page with a single instance selected](compute_instance_list-select_instance.png "Select a Compute Instance from the list") +``` - Provided there is no nested content, you can use a single space between the bullet character and the text. +![Screenshot of Cloud Manager Compute Instance page with a single instance selected](compute_instance_list-select_instance.png "Select a Compute Instance from the list") - ```command - - Item A - - Item B - - Item C - ``` +#### Example Narrow Image -#### Nested Content Within Lists +Smaller images should be displayed using their true pixel size. When taking screenshots within some software on some operating systems, the pixel size is increased (likely to account for the operating system's scaling). For instance, taking a screenshot with the Skitch tool on macOS doubles the pixel count. In these cases, use another image editing tool (like macOS's built in preview) to scale down the image to match the intended pixel width. -To remain consistent across all of our guides, nested content should be indented *four* spaces and a blank line should be used above and below the content. Our Markdown processor assumes nested content starts directly below the *first* character in the text of the list item above it. With this in mind, it's important to indent the text portion of the list item to match that four space indent. In practice, there should be *two* spaces after the number (for ordered lists) and *three* spaces after the bullet for unordered lists. If this spacing is not respected, the nested content may not render properly. +```file {lang="md"} +![Screenshot of the Create Firewall panel in the Cloud Manager](cloud_firewalls-create_panel.png) +``` -- **Ordered list** (`1.`): Use *two* spaces after the number. -- **Unordered list** (`-`): Use *three* spaces after the bullet. +![Screenshot of the Create Firewall panel in the Cloud Manager](cloud_firewalls-create_panel.png) -````command -- Item A +### Key Combinations - This sentence is nested under *Item A*. +When instructing a reader to press hotkeys or other combinations of keys, enclose each individual key within a [kbd](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd) html element as shown in the example below. -- Item B +```file {lang=html} +Use Ctrl + C to copy text. +``` - ```command - This command is nested under *Item B*. - ``` +**Output:** Use Ctrl + C to copy text. -- Item C -```` +## Special Features ### Note Shortcode @@ -675,22 +834,17 @@ This is an example note. {{< /note >}} **Best practices:** -- **Be concise.** The shorter the better. Notes can lose their impact when they become too long. -- **Keep things relevant.** The note should pertain directly to the surrounding paragraph, step, or list item. If the note is an unnecessary interruption to the reader, consider removing the note, moving it to a different section, or placing its contents directly in the surrounding content. -- **Use notes sparingly.** Notes draw attention away from the surrounding content. Too many notes can distract the reader, result in important information getting lost, and are often unnecessary. Consider the impact too many notes or multiple consecutive notes may have to the reader. Often, some information can be omitted and some information is better suited to be included as part of the surrounding text. -- **Use descriptive titles.** Customize the title of each note so that the reader can quickly assess if the note is relevant to them. -- **Can be used for short-lived (nonpermanent) content** *(with some caution)*: In many cases, short-lived content is better suited to notes than being hidden within paragraphs or list items. When adding temporary content to a note, always include the date when the content will be out-of-date (if available) as well as information the reader may need to know after that date. An example of this is beta notices. When a new product comes out, the documentation should mention that the product is available as a beta (and, as such, may not be feature complete or production ready). While a note at the top of the related product pages may be warranted, a note within all of our other guides that reference the product is likely not necessary and may create more complications when we need to remove this information. - -**What to avoid:** -- Lengthy notes. -- Notes not relevant to the surrounding content. -- Too many notes relative to surrounding content. -- Stacking notes (multiple consecutive notes). -- Generic or non-descriptive titles. +Notes highlight important information that relates to the surrounding content. Use notes strategically to draw attention to key details without disrupting the reading flow. +- **Avoid Lengthy Notes:** Be concise - the shorter the better. Notes can lose their impact when they become too long. Keep information focused and essential. +- **Ensure Notes Are Relevant to Surrounding Content:** The note should pertain directly to the surrounding paragraph, step, or list item. If the note is an unnecessary interruption to the reader, consider removing the note, moving it to a different section, or placing its contents directly in the surrounding content. +- **Don't Overuse Notes:** Notes draw attention away from the surrounding content. Too many notes can distract the reader, result in important information getting lost, and are often unnecessary. Consider the impact that excessive notes may have on the reader - some information can be omitted and some information is better suited to be included as part of the surrounding text. +- **Avoid Stacking Multiple Notes:** Multiple consecutive notes can overwhelm readers and diminish their effectiveness. Space out notes throughout your content and consider consolidating related information into a single note when possible. +- **Use Descriptive Titles:** Customize the title of each note so that the reader can quickly assess if the note is relevant to them. Avoid generic titles like "*Note*" or "*Important*" in favor of specific, descriptive titles. +- **When to Use Notes for Temporary Content:** (with caution) Temporary content often works better in notes than buried in paragraphs. Always include expiration dates and post-expiration guidance. For product-wide notices (like beta releases), add notes to the main product page rather than all referencing guides to simplify future updates. #### Parameters -When creating a new note, there are multiple parameters to consider pertaining to the type of note, its title, and if it can be expanded/collapsed. While not all parameters are always necessary, all should be taken into account during the note creation process. +When creating a new note, consider several options related to the note type, title, and whether it can be expanded or collapsed. While not all parameters are necessary, think though these choices during the note creation process. | Parameter | Values | Description | | -- | -- | -- | @@ -702,15 +856,15 @@ When creating a new note, there are multiple parameters to consider pertaining t #### Note Types -There are four unique types of notes: **primary**, **secondary**, **warning**, and **alert**. Each type has specific use cases and varying levels of urgency that should determine the type of note you choose to make. Below are examples of each note type and their use cases: +There are four unique types of notes: **primary**, **secondary**, **warning**, and **alert**. Each type has specific use cases and varying levels of urgency that determine the type of note you choose. Below are examples of each note type and use cases: -- **Primary** (type is unset or `type="primary"`, title defaults to "Note"): Used for additional related information that does not fit with the rest of the document. Can include alternative suggestions or solutions, developer tips, or general best practices that are not critical to the success of the task at hand. +- **Primary** (type is unset or `type="primary"`, title defaults to "Note"): Used for additional related information that doesn't fit the rest of the document. May include alternative suggestions or solutions, developer tips, or general best practices not critical to the success of the task at hand. {{< note title="Best Practice: Use Password Generators" >}} - When creating root, user, or other passwords, you can increase security by using a password generator such as [1Password](https://www.1password.com) to create and save complex, encrypted passwords. + When creating root, user, or other passwords, increase security by using a password generator such as [1Password](https://www.1password.com) to create and save complex, encrypted passwords. {{< /note >}} -- **Secondary** (`type="secondary"`, title defaults to "Note"): Most commonly used in tandem with the [collapsible parameter](#collapsible). **Secondary** notes can include non-critical information, commands, code, or output that may take up too much room or does not require visibility for the success of an action. +- **Secondary** (`type="secondary"`, title defaults to "Note"): Most commonly used in tandem with the [collapsible parameter](#collapsible). This type can include non-critical information, commands, code, or output that takes up too much room or doesn't require visibility for success of an action. {{< note type="secondary" title="Amsterdam Data Center: Lish SSH Gateway Fingerprints" isCollapsible=true >}} ```command @@ -720,13 +874,13 @@ There are four unique types of notes: **primary**, **secondary**, **warning**, a ``` {{< /note >}} -- **Warning** (`type="warning"`, title defaults to "Warning"): Notices that warn the reader to proceed with caution, including notices for beta programs, warnings of limited resource availability, etc. Not as urgent as alert notes. +- **Warning** (`type="warning"`, title defaults to "Warning"): Notices warning the reader to proceed with caution, including notices for beta programs, warnings of limited resource availability, etc. Not as urgent as alert notes. {{< note type="warning" title="VPC Beta Notice" >}} VPCs are now publicly available in beta, providing customers with another method of isolating network traffic between Compute Instances (in addition to the [VLANs](/docs/products/networking/vlans/) feature). Not all data centers are currently supported. For more information, review the [Availability](/docs/products/networking/vpc/#availability) section. {{< /note >}} -- **Alert** (`type="alert"`, title defaults to "Important"): The most urgent of all note types. **Alert** notes should be used to notify of potential *destructive* actions such as situations resulting in data loss or where there is no undoing what has been done. Anything critical to the success of a task should still be included in the primary content and not solely live in the note. +- **Alert** (`type="alert"`, title defaults to "Important"): The most urgent of all note types. **Alert** notes should be used to notify of potential *destructive* actions (i.e., situations resulting in data loss or where there is no undoing what has been done). Anything critical to the success of a task is still included in the primary content and not solely live in the note. {{< note type="alert" title="Back up files to prevent data loss" >}} Formatting a Block Storage Volume will delete all data stored on that Volume. To prevent data loss, verify that any files you wish to retain have been successfully backed up to another storage device. @@ -734,7 +888,7 @@ There are four unique types of notes: **primary**, **secondary**, **warning**, a #### Titles -Each note can also have a custom title, which is set using the `title` parameter. Titles can specify or summarize the purpose of the note, as well as help define the authority and urgency of the note in the form of tips, best practices, or calls to attention. **Default titles may also be used, but custom titles are preferred for their additional context.** +Use the title parameter to give each note a descriptive title that explains its purpose or summarizes its content. **Avoid generic default titles like "Note" or "Important" - custom titles help readers assess relevance at a glance.** - Example summary titles: "Use a strong password", "The token is valid for 24 hours", "A valid payment method is required" - Example tip or best practice titles: "Developer Tip", "Common Practice" - Example calls to attention: "Before moving forward", "This may result in data loss" @@ -745,7 +899,7 @@ Each note can also have a custom title, which is set using the `title` parameter ```file {lang="text"} {{}} -This is an example note with a helfpful custom title. +This is an example note with a helpful custom title. {{}} ``` @@ -781,9 +935,9 @@ This content is hidden until the user expands the note. #### Indentation -Content within the opening and closing note shortcode tags must respect the expected indentation of any parent elements, such as list items. Since content within a list is indented (using 4 spaces), the content of a note shortcode must be indented by the same number of spaces. +Content within note shortcode tags must match the indentation of parent elements, such as list items. Since list content uses 4 spaces indentation, note content within lists must also be indented 4 spaces. -By default, content between the shortcode tags is rendered using `.InnerDeindent`, which allows the shortcode to respect the indentation of any parent elements (such as lists). When set to `false`, `.Inner` is used instead, which does not de-indent the content and does not respect the indentation of parent elements. Defaults to true. +By default, content between shortcode tags uses `.InnerDeindent`, which automatically adjusts indentation to match parent elements (like lists). When set to `false`, `.Inner` is used instead, which maintains the original indentation regardless of parent elements. Defaults to true. ```file - First list item. @@ -795,243 +949,138 @@ By default, content between the shortcode tags is rendered using `.InnerDeindent - Second list item. ``` -If this indentation is not respected, which should only be the case for older note shortcodes made before this change, the following option is set: `respectIndent=false`. If one of these is encountered when editing an existing guide, remove `respectIndent=false` and properly indent the shortcode. +If this indentation is not properly indented (which should only occur in older note shortcodes created before this change), the following option is set: `respectIndent=false`. If you encounter this when editing an existing guide, remove `respectIndent=false` and properly indent the shortcode content. ```file - First list item. {{}} -This content appears within the first list item but does not respect its indentation. +This content appears within the first list item but isn't properly indented to match it. {{}} - Second list item. ``` -### Numerical Values - -| 1-10 | Greater than 10 | -| -- | -- | -| Use words (one, two, three, etc.) | Use numerical digits (11, 22, 33). | - -### Placeholders - -The placeholder shortcode applies special formatting to highlight the user-replaceable portion of a command or file. It can also be used within a paragraph as a way to reference what the user should replace. - -- **Syntax:** `{{}}`
-- **Output:** {{< placeholder "VARIABLE_NAME" >}} - -When creating a placeholder, you can either use a descriptive variable name (as shown above) or example text. +### Hugo Shortcodes and VS Code Preview -- **Placeholder example text:** A generic example that represents the expected user input. For instance, example IP addresses (`192.0.2.17`) and example domain names (`example.com`). This should be in the same case as the surrounding text, using whatever formatting is appropriate for the example text. For IP addresses, review the [Example IP Addresses](#example-ip-addresses) section. -- **Placeholder variable:** A short descriptive variable name. This should be formatted in uppercase with an underscore (`_`) used instead of spaces. For instance, `REGION_ID` and `FILE_NAME`. - -The following example demonstrates a common use case for the placeholder shortcode. - -- **Markdown syntax:** - - ```` - Within the default NGINX configuration file, replace {{}} with your website's domain. +When writing guides, Hugo shortcodes (like {{< note >}}, {{< file >}}, {{< command >}}, etc.) doesn't display properly in VS Code's markdown preview ("Shift + Ctrl + V") - they appear as raw text. This is expected behavior. The shortcodes render correctly when the documentation site is built with Hugo. - ```file {title="/etc/nginx/sites-available/default"} - server { - listen 80; - listen [::]:80; - server_name {{}}; - } - ``` - ```` +### Extend Markdown Using Shortguides -- **Output:** +Shortguides allow you to extend a Markdown file by inserting content from another file. For common tasks such as basic software installation, you can create reusable shortguides and insert them using the content shortcode. This allows our library to maintain consistent and up-to-date installation instructions for frequently used tools such as Python, MySQL, and Docker. - Within the default NGINX configuration file, replace {{< placeholder "example.com" >}} with your website's domain. +To create one, start by drafting a standalone Markdown file that contains the task-specific instructions. Once saved, it can be referenced across multiple guides using the content shortode, ensuring consistency and reducing duplication. - ```file {title="/etc/nginx/sites-available/default"} - server { - listen 80; - listen [::]:80; - server_name {{< placeholder "example.com" >}}; - } - ``` +1. Create a directory using the name of your shortguide anywhere within the docs/ folder. -### Sentence Spacing +1. Create an index.md file in that directory for your shortguide content (e.g., example-shortguide-name/index.md). -Use single spaces between sentences; do not double-space. +1. Set or add headless: true to the front matter of index.md to exclude the shortguide from site navigation and search results. -### Tables +When using shortguides: -You can create tables using standard Markdown syntax. Additionally, you can embed a Markdown table within the [table shortcode](#table-shortcode) for additional functionality. +- **To embed a shortguide**: Use the content shortcode with the shortguide's directory name as the parameter (e.g., example-shortguide-name) +- **To include images in a shortguide**: Add the image to your shortguide's directory and embed it using the image shortcode: -```file {lang="md"} -| Column Header 1 | Column Header 2 | -| -- | -- | -| **Example** | This is an example of text in the second column. | +```file +{{}} ``` -| Column Header 1 | Column Header 2 | -| -- | -- | -| **Example** | This is an example of text in the second column. | - -#### Column Text Alignment +#### Example Usage -To align text within a table, modify the second row. This row separates the header from the body of the table and can be used for additional metadata, like text alignment. +The following shortguide demonstrates how to install Python using Miniconda. Create a directory named `install_python_miniconda` and an `index.md` file within it: -- Left aligned: Default behavior (if there is a need to be explicit, use `| :-- |`) -- Center aligned: `| :--: |` -- Right aligned: `| --: |` +```file {title="install_python_miniconda/index.md" lang="yaml"} +--- +title: "Install Python with Miniconda" +description: 'A shortguide that shows how to install Python via Miniconda.' +keywords: [] +license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' +contributors: ["Author's FirstName LastName"] +published: 2023-03-07 +modified: 2023-03-07 +headless: true +show_on_rss_feed: false +--- + -```file {lang="md"} -| Left-Aligned Text | Center-Aligned Text | Right-Aligned Text | -| -- | :--: | --: | -| Example | Example | Example | -``` +1. Download and install Miniconda: -| Left-Aligned Text | Center-Aligned Text | Right-Aligned Text | -| -- | :--: | --: | -| Example | Example | Example | + ```command + curl -OL https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh + bash Miniconda3-latest-Linux-x86_64.sh + ``` -#### Table Shortcode +1. During installation you're prompted to review the terms and conditions. Select "yes" to accept for each prompt. -The table shortcode can be used to add additional functionality to Markdown tables. By default, it adds a scrollbar when the table width is larger than the content area. This means that it can accommodate wide tables with lots of columns. It also adds alternating row background colors so that tables are easier to parse. +1. Check your Python version: -```file {lang="md"} -{{}} -| Column Header | Column Header | Column Header | -| -- | -- | -- | -| **Row 1** | Example | Example | -| **Row 2** | Example | Example | -| **Row 3** | Example | Example | -{{}} + ```command + python --version + ``` ``` -{{< table >}} -| Column Header | Column Header | Column Header | -| -- | -- | -- | -| **Row 1** | Example | Example | -| **Row 2** | Example | Example | -| **Row 3** | Example | Example | -{{< /table >}} - -#### Fixed First Column - -If you are creating a wide table and need the first column to be fixed when scrolling, use the **"first-sticky"** class. +To use this shortguide in another guide, use the following syntax: -```file {lang="text"} -{{}} -| Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | -| -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -| **Row1**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | -| **Row2**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | -| **Row3**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | -{{}} +```file {title="sample_embedding_guide/index.md"} +{{%/* content "install_python_miniconda" */%}} ``` -{{< table class="first-sticky" >}} -| Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | Column Header | -| -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -- | -| **Row1**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | -| **Row2**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | -| **Row3**| Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | Example | -{{< /table >}} - -### Tabs - -Using a tabbed interface allows you to separate content into user-selectable tabs. This can be used to provide specific instructions for different versions of a software application (like MySQL 5.7 or 8), different operating systems (like macOS, Windows, or a Linux distribution), or different user tools (like the Cloud Manager, Linode CLI, or Linode API). - -````file -{{}} -{{}} -The content only appears when *Tab 1* is selected. -{{}} -{{}} -When *Tab 2* is selected, this content appears. -{{}} -{{}} -```` - -{{< tabs >}} -{{< tab "Tab 1" >}} -The content only appears when *Tab 1* is selected. -{{< /tab >}} -{{< tab "Tab 2" >}} -When *Tab 2* is selected, this content appears. -{{< /tab >}} -{{< /tabs >}} - -When a user selects a tab, the first item in each tab set that has a matching title is also selected. This means that if multiple tab sets are on a page, each with the same items, the user only needs to select an item within one tab set and all tab sets will show that item. - -{{< tabs >}} -{{< tab "Tab 1" >}} -This is *Tab 1* in the second tab set. When *Tab 1* is selected on any tab set, this content is visible. -{{< /tab >}} -{{< tab "Tab 2" >}} -And here is *Tab 2* in the second tab set. When *Tab 2* is selected on any tab set, this content is visible. -{{< /tab >}} -{{< /tabs >}} - -When a tab is selected, a `tab` parameter string appears in the URL along with the title of all selected tabs. For instance, if *Tab 2* is selected in the tab sets above, `?tabs=tab-2` is appended to the URL. This allows the URL to be saved or shared, keeping the same tabs selected on the page. +{{< note >}} +Be sure to use the `%` delimiter inside the surrounding `{{ }}` braces when embedding `content` shortcodes. +{{< /note >}} -### Terminal Output +## Standards and Best Practices -Output from terminal commands should be displayed with the *output shortcode*: +### Example IP Addresses -````file -```output -Hello world! -``` -```` +When referencing IP addresses in documentation, any real address should be obscured unless it's explicitly intended for the reader to access it. When possible, use example IP addresses from the reserved documentation blocks: -The above shortcode is rendered as: +- `192.0.2.0/24` +- `198.51.100.0/24` +- `203.0.113.0/24` -```output -Hello world! -``` + These subnets are allocated specifically for documentation and prevent accidental routing or conflict in production environments. -Here's an example of a command (using the code shortcode) and its output (using the output shortcode) displayed together: +Use these blocks in order: begin with `192.0.2.0/24` for the first example IP address. If additional examples are needed, draw from the next available block. -````file -```command -echo "Hello world!" -``` +{{< warning >}} -```output -Hello world! -``` -```` +When referencing the IPv4 address of a Compute Instance, avoid using `.0` or `.1` as the final octet, since those addresses are typically reserved and assigned to Compute Instances. For example, `192.0.2.17` is appropriate, while `192.0.2.0` and `192.0.2.1` should be avoided. -The above shortcodes are rendered as: +{{< /warning >}} -```command -echo "Hello world!" -``` +{{< warning >}} -```output -Hello world! -``` +For IPv6 examples, use the reserved documentation block: +- `2001:db8::/32` + The IPv6 block 2001:db8::/32 is similarly reserved to ensure example addresses don't interfere with live traffic. -### Terminal Output (Deprecated Syntax) +{{< /warning >}} -In some existing guides, you may see this older shortcode syntax for displaying terminal output: +### Numerical Values -```file -{{}} -Hello world! -{{}} -``` +| 1-10 | Greater than 10 | +| -- | -- | +| Use words (one, two, three, etc.) | Use numerical digits (11, 22, 33). | -This is equivalent to: +### External Resources/More Information -````file -```output -Hello world! -``` -```` +If you wish to provide links to external sites for the user to review after going through your guide, do so using the `external_resources` parameter in the [page header](#metadata-header). This will automatically appear as a text block with links at the bottom of the page. -*The older syntax should not be used for new content.* While they are rendered with the same presentation by Hugo, they are not displayed the same in the GitHub.com UI. When viewing a Markdown file in the library on GitHub, the newer code fence shortcode syntax will have enhanced styling, compared with the older shortcode syntax. +> More Information +> +> You may wish to consult the following resources for additional information on this topic. While these are provided in the hope that they will be useful, please note that we cannot vouch for the accuracy or timeliness of externally hosted materials. +> +> - [Link Title 1](http://www.example.com) +> - [Link Title 2](http://www.example.net) +> +> This approach keeps the body of your content clean and ensures consistent formatting across guides. ## Author Pages -Profile pages for authors are listed at https://www.linode.com/docs/authors/. These are automatically generated from the `authors` frontmatter of the guides in the library. These pages list all of the guides that an author has published in the docs library. +Profile pages for [Contributors](https://www.linode.com/docs/contributors/) are listed. These are automatically generated from the `authors` frontmatter of the guides in the library. These pages list all of the guides that an author has contributed in the docs library. Docs contributors can create author pages by following these steps: @@ -1045,10 +1094,10 @@ The second step is optional. If you do not follow this step, a profile page is s contributors: ["FirstName LastName"] ``` -1. (Optional) Create a new directory and Markdown file for your author page under the `docs/authors` directory in the docs repository. The new directory should named after you, with uppercase letters replaced by lower case, and spaces replaced by a dash. For example, an author with the name `Nathan Smith` would have a new profile page created at `docs/authors/nathan-smith/_index.md`. +1. (Optional) Create a new directory and Markdown file for your author page under the `docs/authors` directory in the docs repository. The new directory (folder) should be named after you. Replace uppercase letters with lower case, and replace spaces with a dash. For example, an author with the name `Nathan Smith` would have a new profile page created at `docs/authors/nathan-smith/_index.md`. {{< note >}} - Note that the Markdown file is named `_index.md`, not `index.md` + Markdown file name is named `_index.md`, not `index.md` {{< /note >}} A [Hugo archetype](https://gohugo.io/content-management/archetypes/) is available to create new author pages. For the example author `Nathan Smith`, you would run this command to create the Markdown file for their profile page: @@ -1070,7 +1119,7 @@ The second step is optional. If you do not follow this step, a profile page is s A short biography of the docs author/contributor. This biography text is displayed above a listing of their published docs/content. ``` - You can set an email, website link, and short meta description in the frontmatter of this file. You can also update the body of the file with a biography of the author. This biography will be displayed above the author's published guides listing. + You can add an email, website links, and a short meta description in the frontmatter of this file. You can also update the body of the file with a biography of the author. This biography displays above the author's published guides listing. ## Legal Information @@ -1078,4 +1127,4 @@ COPYRIGHT OWNERSHIP. Writer agrees that the Work is being created by the writer CREDIT. Nothing contained in this Agreement shall be deeded to require Linode to use the Work, or any part thereof, in connection with Linode Guides & Tutorials or otherwise. Credit for the Work shall read, "Contributed by [writer's name]." -PAYMENT. Upon publication of a submission to the Linode Guides & Tutorials Repository, the writer will be paid the sum agreed to by email by both Linode and the author. Author may choose payment either in the form of a credit to their Linode account, a hardcopy check, or as an electronic payment via PayPal. \ No newline at end of file +PAYMENT. Upon publication of a submission to the Linode Guides & Tutorials Repository, the writer will be paid the sum agreed to by email by both Linode and the author. Author may choose payment either in the form of a credit to their Linode account, a hardcopy check, or as an electronic payment via PayPal. diff --git a/docs/guides/uptime/loadbalancing/how-to-configure-haproxy-http-load-balancing-and-health-checks/index.md b/docs/guides/uptime/loadbalancing/how-to-configure-haproxy-http-load-balancing-and-health-checks/index.md index deb72fcbe7a..4c8a8c9756c 100644 --- a/docs/guides/uptime/loadbalancing/how-to-configure-haproxy-http-load-balancing-and-health-checks/index.md +++ b/docs/guides/uptime/loadbalancing/how-to-configure-haproxy-http-load-balancing-and-health-checks/index.md @@ -4,7 +4,7 @@ title: "How to Configure HAProxy HTTP Load Balancing and Health Checks" description: "Learn how to configure HAProxy for HTTP load balancing, with instructions on updating frontend and backend settings, path-based routing, and health checks." authors: ["Tom Henderson"] contributors: ["Tom Henderson"] -published: 2024-09-18 +published: 2025-01-28 keywords: ['haproxy','http load balancing','http health checks','haproxy acl'] license: '[CC BY-ND 4.0](https://creativecommons.org/licenses/by-nd/4.0)' ---