Skip to content

Latest commit

 

History

History
242 lines (156 loc) · 9.28 KB

README.md

File metadata and controls

242 lines (156 loc) · 9.28 KB
Raw

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:

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

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

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:

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).

Docs page layout guidelines

Title icons

If you are updating a page in Docs which doesn't already have a title icon, please add one. Title icons can be added in the frontmatter for each page by adding a Font Awesome class in the icon entry:

---
layout: src/layouts/Default.astro
pubDate: 2023-01-01
modDate: 2024-05-24
title: Octopus Cloud
subtitle: We host Octopus for you
icon: fa-solid fa-cloud
navTitle: Overview
navSection: Octopus Cloud
navOrder: 10
description: How to work with Octopus Cloud.
hideInThisSectionHeader: true
---

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
![](/docs/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