Octopus docs

This repository contains the documentation for Octopus Deploy.

Contributions to help improve this documentation are welcome, however, you must sign the Contribution License Agreement (CLA) before we can accept your contribution.

See the Octopus style guide for information including:

• Markdown quick reference
• Octopus features and terminology
• Grammar rules
• Working with images

How to contribute a change to the docs

• The main branch has the latest version of the docs
• Fork this repo and create a branch for your changes
• Make the changes you'd like to contribute
• Submit a pull request (PR) to master with your changes and include a comment explaining the changes
• Sign the Contribution License Agreement (CLA)
• We'll review your PR and accept it or suggest changes

Default values

When you need to use an example value in docs, please use the below:

• Octopus URL: https://your-octopus-url
• Octopus API key: API-YOUR-KEY
• Snapshot name: Snapshot XXXXX
• SubscriptionId: g3662re9njtelsyfhm7t
• Fake password: your-secret-password

In general, try to use "your" rather than "my". For example, your-value.

Required checks

When you raise a pull request, the following checks will take place:

1. A full test
2. A spell-check

Test

You can run the tests locally using:

pnpm test

The most common failures are:

• A new image is referenced with the wrong path
• An internal link has a bad address

Markdown linting

Markdown files are linted in CI using markdownlint. The rules are configured in .markdownlint.json.

To catch issues locally, install the markdownlint VS Code extension (already included in the recommended extensions). It will highlight errors on save.

You can also run the linter from the command line using markdownlint-cli2. Lint both trees, not just src/pages — the include files in src/shared-content render into pages and are linted by CI too:

npx markdownlint-cli2 "src/{pages,shared-content}/**/*.{md,mdx}"

To lint only files changed in the current branch (matching the CI behavior):

git diff origin/main --name-only --diff-filter=ACMRTUXB -- '*.md' '*.mdx' | xargs -n 30 npx markdownlint-cli2

Or in PowerShell:

git diff origin/main --name-only --diff-filter=ACMRTUXB -- '*.md' '*.mdx' | ForEach-Object { npx markdownlint-cli2 $_ }

The -n 30 matters on Windows: passing several hundred paths at once exceeds the command line length limit.

Common issues include missing blank lines around headings, fenced code blocks without a language, duplicate headings, and trailing whitespace.

Images need alt text

Every image needs alt text describing what it shows. MD045 fails the build without it, which is the safety net that keeps the docs accessible and readable by search crawlers and AI assistants.

![](/docs/img/infrastructure/images/infrastructure-overview-dashboard.png)
![The Infrastructure overview dashboard in the Octopus Web Portal](/docs/img/infrastructure/images/infrastructure-overview-dashboard.png)

A genuinely decorative image should have empty alt per the WCAG specs, but MD045 does not allow that in markdown syntax. Use an HTML <img alt=""> tag in that case, or reword so the image is the thing being named.

Content inside a numbered list

Indent figures, code blocks and hints so they sit inside the step they belong to. A block at column 0 ends the list, and the following steps start a new one:

1. Open the project.

    :::figure
    ![The project settings page](/docs/img/example.png)
    :::

2. Click **Save**.

Numbering may also run on across headings, which renders as <ol start="7"> and is intentional. MD007, MD005 and MD029 are turned off in .markdownlint.json so the linter leaves list indentation and numbering alone.

Four auto-fixes to avoid

markdownlint-cli2 --fix is safe for most rules, but check the diff for these:

• MD009 deletes hard line breaks. Two trailing spaces are a <br>, and that is what the rule allows, but a line with three or more gets trimmed to zero rather than back to two, so the break disappears. Trim those lines to exactly two spaces by hand.
• MD034 rewrites bare URLs and email addresses as <url> autolinks, which is unsafe in both file types. In .mdx the angle brackets parse as JSX and the build fails. In .md a URL with no scheme, such as www.example.com, is not a valid autolink, so the brackets survive into the page and the reader sees them. Write an explicit [text](url) link in either case.
• MD039 strips spaces from inside link text. Where that space sat against the neighbouring word, code span or link, removing it joins the two together in the rendered page. Move the space outside the brackets rather than deleting it.
• MD010 rewrites a leading tab as a single space, which is too shallow to nest a list item, so the item silently escapes its parent. Use four spaces instead.

None of these show up as a lint failure afterwards, because the fix leaves the file passing. They only show up in the rendered page, so the diff is the only place to catch them.

Spell check

You can run the spell check locally using:

pnpm spellcheck

Only changed files are checked for spelling. If a file hasn't been edited since this check was introduced, you may have to fix some old spelling issues.

For each error detected, you'll need to decide whether to:

• Correct your spelling, or
• Propose an addition to the custom dictionary

For example, if you added MySQL to an article and it was flagged as an unknown word, you could propose the addition of MySQL by adding it word list in the file dictionary-octopus.txt.

Some consideration should be given as to whether it should be MySQL or MySql and just a single entry should be added to dictionary-octopus.txt to promote consistency.

Exclusions

You can see files excluded from the spell check in cspell.json.

Deploying to preview environment (Octopus Developers)

Before merging to main it's possible you'd like to see your changes in a preview environment. It's simple to do this:

1. You need Node.js installed to run the site locally
2. Run pnpm install to obtain the dependencies
3. Run pnpm dev to run a local preview of the site
4. Open localhost:3000 to view the site, the first page load usually takes a little time

You can generate a static copy of the site using pnpm build and run it in a browser with pnpm preview.

Note! We use Sharp to generate images. You may need to install a specific flavour of Sharp depending on your operating system. If you see an error, such as "Error: Could not load the "sharp" module using the linux-x64 runtime", you can follow the instruction on the Sharp cross-platform page. You can also refer to issue 2142.

Astro hints and tips

Editor setup

We have configured Front Matter CMS, which works through a VS Code extension. This can help guide you during the editing process as there are snippets to help with images and other common components. Front Matter also helps you with the markdown YAML front matter.

Here's the recommended setup for VS Code:

• Astro
• Code Spell Checker
• Front Matter CMS
• Markdown All in One

You can use the Front Matter dashboard to find content, media, and snippets - or the Front Matter toolbar to interact in markdown files (.md or .mdx).

Finding pages to edit

The pages are in the exact page shown on the website, so you can easily translate them. For example:

https://octopus.com/docs/infrastructure/deployment-targets/tentacle

Can be found in the exact same path within src/pages/

\docs\src\pages\docs\infrastructure\deployment-targets\tentacle

The file is either in the tentacle folder, and named index.md(x), or will be in the parent deployment-targets folder and named tentacle.md.

The only exception are include files, which are noted below.

Redirects

No page should ever be deleted! When a page moves or is retired, it should be changed into a redirect file. The redirect ensures users with old links still land on a useful page.

The below shows the complete contents of a redirect page that sends users from:

/docs/administration/authentication/authentication-providers/azure-ad-authentication

To the new location:

/docs/security/authentication/azure-ad-authentication

---
layout: src/layouts/Redirect.astro
title: Redirect
redirect: https://octopus.com/docs/security/authentication/azure-ad-authentication
pubDate:  2023-01-01
navSearch: false
navSitemap: false
navMenu: false
---

Having the file kept in place helps future authors as they can easily see where the content has moved. It also prevents a new content item being added that can’t be accessed due to redirects being in place.

Search engines are happy to process meta redirects, just like DNS redirects.

Include files

Include files let you re-use a chunk of content across many pages. When the information in the shared file changes, all the pages that use it get the update. This can be better than finding all references to a concept, but the trade off is it is more complex to reason.

Shared content

Shared content is placed in /src/shared-content/

You can organize the content in folders within the shared content folder.

Referencing shared content

Shared content can be referenced from mdx files. If you have a markdown file and want to reference shared content, follow these steps.

Change the file extension from .md to .mdx

After the front matter ends with --- you can import the content:

import DisableDefaultSpace from 'src/shared-content/administration/disable-default-space.include.md'

You can then place the content wherever it needs to be shown:

<DisableDefaultSpace />

MDX file differences

When you convert a file from Markdown to MDX, you may encounter some common errors.

Headings

The integration for headings allows custom ids to be specified:

## Switching between spaces {#switching-between-spaces}

Within an MDX file, this looks like a code block and will error. Escape the statement with a \ character:

## Switching between spaces \{#switching-between-spaces}

MDX files don't allow short-form links, instead of using <https://example.com> use [https://example.com](https://example.com), or even better - put in useful link text, like [example website](https://example.com).

Footer

The footer is built in this repo by src/components/Footer.astro. It renders the page's last-updated date, the copyright line, and a row of links. Edit the links in src/data/footer.ts; edit the wording in src/data/language.json under octopus_footer.

Styles live in src/styles/main.css under /* Footer */. The footer repeats the page's column template (--page-grid-columns) so its content lines up with the article column above it.

Docs page layout guidelines

Product screenshots

Product screenshots used in Docs should reflect the UI in the latest version of Octopus. The figure component will automatically add a curved border and outline to your image:

:::figure
![The Octopus Cloud architecture](/docs/img/octopus-cloud/images/octopus-cloud-architecture-diagram.png)
:::

Images should be uploaded to the folder that relates to the position of the page in the Docs hierarchy. In the example above, where the image is destined for the Octopus Cloud overview page, the image has been uploaded to the Docs > Octopus Cloud > Images folder. If a folder has not been created for the page you are uploading an image to, create a new folder or use the Docs > Images folder as a backup.

Move version notes for older versions of Octopus to the bottom of Docs pages

Do not use call out / info boxes in the main body of docs pages to reference how features worked in earlier versions of Octopus. This information should be moved to the bottom of docs pages under an 'Older versions' heading. For example, you might add a note like this under the 'Older versions' heading:

In versions earlier than 2024.x, you'll find the page to add a feed under the Projects menu -> Tenant Variables