This page includes the basics you need to get started, as does the basic blog template. You’ll find more detailed instructions in the rest of this guide.
If you’re writing for the blog, please read the following:
Markdown
The blog and the docs are both written with Markdown.
The following is the minimum Markdown you need:
- Headings: ## H2 Heading , ### H3 heading.
- Use bold for tool/feature names and UI elements, use italics to add emphasis, and use back ticks for parameters and file paths: `~/.ssh/id_rsa.pub`
- Add a [link](https://www.octopus.com)
-
Create a code block:
``` Write-Host "Hello, World! ``` -
Add an image:
Sentence case
Use sentence case for titles. Sentence case uses the same capitalization rules as normal sentences, whereas title case capitalizes most words in the title. We don’t use title case.
Images
Use images and screenshots to help illustrate your point, but don’t rely on images alone to convey your meaning. Use a screenshot if:
- The user might struggle to locate an item in the UI.
- The procedure jumps from one place in the UI to another.
- You want to reassure the user they’re in the right place.
For more information, see working with images.
Adding resources to your post
If you're adding resources to your post, please avoid using specific resource strings. These may get released over time and be susceptible to takeover or squatting. This activity could be benign or malicious in nature, and readers may blindly trust what's in the resource is still legitimate.
It's possible to take over resources released in AWS or other public cloud providers like ec2-12-134-1-3.compute-1.amazonaws.com, so we should use something like {ec2 instance path}. While the instance is randomly assigned, it's possible to iterate through to get what you want.
For cloud storage like Azure Blob or AWS S3, if you’re referencing a full S3 bucket path in your post, and there’s no need for the full bucket path, please use placeholders. For example {s3 bucket path}.
Please host example files from the i.octopus.com S3 bucket. This bucket isn't tied to a specific user account and we use it to host most of Octopus' public files related to the website.
Proofread
Proofread your work to make sure it’s error-free. Octopus has a Grammarly account that can help spot simple mistakes and apply our style. You should also use the browser version of the Hemingway app to remove passive voice and make sure your sentences are easy to read.
For more information, please read the self-editing tips.
Create a PR
When your work is ready, create a PR so the work can be reviewed, edited, scheduled (if it’s for the blog), and merged.
Common validation errors
We use an in-house tool to convert the docs and the blog from markdown to HTML for publication on the web.
These are some of the common validation errors that will cause your PR to fail. If you see the build has failed, check the following:
YAML front matter
If the YAML front matter is missing entirely or in part validation will fail. See the basic template for details.
File or directory names are not all lowercase
Check you have only used lowercase characters, dashes (-) and full stops (.) in your filenames.
Broken links
Validation will fail if you include links that don’t resolve.
Best practices for creating a folder (the name of which becomes the URL) for a blog post
- Use lowercase letters only
- Use hyphens to separate words, not spaces, underscores, or other characters
- The URL should be similar to the title of the post, making use of keywords
- URLs don’t need to include function words like ‘a’, ‘of’, ‘the’, ‘are’, ‘have’, etc
- Keep the URL readable enough so people know what to expect when they click your link