Content Guide

What’s allowed

Armory docs contains content that documents Armory software products and platforms.

What’s not allowed

Dual sourced content

Armory docs does not host dual sourced content since that requires double the effort to maintain and can quickly become outdated. For example, if you are documenting an open source product or demo app, create content in Armory docs. Then link to the specific Armory docs page in the project’s README. In other words, don’t maintain the same content in Armory docs and a repo’s README.

Third party content

Armory docs does not repeat content from third party product documentation. For example, don’t tell the reader how to create an app OAuth token in GitHub. Instead, link to the GitHub docs and optionally point out Armory-specific information that the user needs in order to perform a third party task. See the Configure GitHub OAuth for Spinnaker for an example.

Where to add content

Markdown files go into content/en/<section>. Each section has its own _index file that generates a landing page for that section. The index page can display a simple list of the contents in the section or no list (set with frontmatter variable no_list: true).

You can go one directory down and have content/en/<section>/<subsection>. This is useful for a series of pages that you want to group together.

File names

Use simple, human-readable, and logical URL paths for your pages that provide clear and direct internal links within the site.

If/as applicable include the priority keyword in the url.

Use only lower case only and hyphens, not underscores, to connect words.

Common page elements

Page frontmatter

Page frontmatter is YAML and appears between ---:

---
title: "Spinnaker Architecture"
description: "Learn about the services that work together in Spinnaker."
weight: 20
linkTitle: "Architecture"
---

• title Required.
  • Create short, meaningful titles that accurately reflect the page content.
  • Include relevant keywords. Do not sacrifice accuracy (or keyword) for brevity.
  • Use natural language and ensure that the content of the page is clearly expressed in the title.
  • The docs site search indexes the page title and page description, so be sure the title contains some nouns a reader would search for.
  • When listing search results, Google truncates longer page titles but still finds keywords in the entire title when building the index.
  • The title should be no longer than 55 characters and must be unique to the site.
• description Required.
  • This is one or two sentences that describe the topic of your page. This summary appears in site search results, on the landing pages generated by _index.md, and in search engine results.
  • Should be no longer than 160 characters and also contain keywords and phrases.
  • Make sure that the language is natural and clearly describes what the user is going to find on the page. Make it enticing and clear - e.g., what you will learn, what problems it solves.
  • Do not make it a duplicate of the title.
  • Hugo generates meta tags using the value of description. If omitted, Hugo uses the first 70 words of your content for the meta tags and nothing for landing pages.
• weight Usually required.
  • If no weight, the content is placed after all content with weight and gets sorted alphabetically.
  • If the weight is the same, pages within that weight are sorted alphabetically
• linkTitle Optional.
  • his is a short, meaningful version of your title for site navigation. Use a linkTitle if your title is more than 2 or 3 words.
  • Generally one or two words, maybe three.

Headings

• No H1. That is the page title.
• H2s and H3s are rendered in the page TOC.
• You can use H4s, but they are not rendered in the page TOC.

Use the same heading on multiple pages

If you want to use the same heading across multiple pages, you can define a common heading in i18n/en.toml in the # common headings section. Then you reference the heading like this:

## {{% heading "<heading-name>" %}}

If you have a heading defined in i18n/en.toml:

[heading_prereq]
other = "Before you begin"

you use it like this:

## {{% heading "prereq" %}}

Content page types

Concept

Use this page type when you want to introduces a single concept or feature. The content is objective, containing architecture, definitions, rules, and guidelines. Rather than containing a sequence of steps, these pages link to related tasks and tutorials.

A concept page explains what something is, not how to use it. You can link to a task/guide page that explains how to use the feature.

If you start explaining a second concept on your page, create a new page for the new concept and link to it.

Structure

frontmatter

Each page must have frontmatter at the top of the page so Hugo can compile it into HTML.

---
title: <descriptive page title>
linkTitle: <short title for site navigation>
description: >
   <what the page is about; site search and search engines display this value in results>
---

For a concept page, you can think of the page title as the title of a research paper. Your reader should know the page is a concept page by the title alone.

Examples:

Pull request approvers check the frontmatter fields and can help with good wording for search engine optimization.

body

The body of your page should have one or more headings that organize your page into meaningful sections.

## < heading for concept overview >

## < {{% heading "prereq" %}} >

## < heading for body >

## < {{%  heading "nextSteps" %}} >

• heading for concept overview: Avoid using “Overview” or “Introduction” as the sole word in the heading. This paragraph should set the context in one or two sentences. You can omit this section if you put your concept overview in the frontmatter’s description field. Headings should be short, descriptive, and optimized for search engines.
• {{% heading "prereq" %}}: (Optional) Include links to prerequisite material that the reader should know in order to understand your concept. This heading is a Hugo shortcode that compiles to “Before you begin”.
• < heading for body >: The body should explain the concept or feature. You can include additional headings and subheadings.
• {{% heading "nextSteps" %}}: (Optional) Link to related concepts, tasks, and/or tutorials. This heading is a Hugo shortcode that compiles to “Next steps”.

Task

Think of a task as a simple, discreet use case. A Task page shows you how to do a single procedure by following a short series of steps that produce an intended outcome. Task content expects a minimum level of background knowledge, and each page links to conceptual content that you should be familiar with before you begin the task. Additionally, a task should list prerequisite steps the reader needs to complete before starting the task.

Structure

frontmatter

Each page must have frontmatter at the top of the page so Hugo can compile it into HTML.

---
title: <descriptive page title>
linkTitle: <short title for site navigation>
description: >
   <what the page is about; search engines display this in results>
---

• title: Your page title should start with an active verb and contain keyword nouns that search engines can use. For example, if you want to explain how to configure mTLS in the Armory Agent, you could create a page title such as “Configure Mutual TLS Authentication”.

Examples:

Pull request approvers check the frontmatter fields and can help with good wording for search engine optimization.

body

The body of your page should have one or more headings that organize your page into meaningful sections.

## < heading for task overview >

## < {{% heading "prereq" %}} >

## < task steps >

## < {{%  heading "nextSteps" %}} >

• heading for task overview: Avoid using “Overview” or “Introduction” as the sole word in the heading. This paragraph should set the objectives in one or two sentences. You can omit this section if you put your task overview in the frontmatter’s description field. Headings should be short, descriptive, and optimized for search engines. If the task guide has several steps, list the steps with links to the section headings.
• {{% heading "prereq" %}}: Include a bullet list of links to prerequisite material that the reader should know or have done in order to perform the task. This heading is a Hugo shortcode that compiles to “Before you begin”.
• < task steps >: The body should contain steps to complete the task. The steps can be in a numbered list or separate headings.
• {{% heading "nextSteps" %}}: (Optional) Link to related concepts, tasks, and/or tutorials. This heading is a Hugo shortcode that compiles to “Next steps”.

Tutorial

A tutorial is an end-to-end example of how to do accomplish a goal and is comprised of several tasks performed in sequence. For example, a CD-as-a-Service tutorial might show you how to deploy an demo app by cloning a repo, logging in using the CLI, creating a deployment file, and finally deploying the app. Like a task, a tutorial should link to content you should know and items you should complete before starting the tutorial.

Structure

frontmatter

Each page must have frontmatter at the top of the page so Hugo can compile it into HTML.

---
title: <descriptive page title>
linkTitle: <short title for site navigation>
description: >
   <what the page is about; search engines display this in results>
---

• title: Your page title should start with an active verb and contain keyword nouns that search engines can use. For example, if you want to explain how to deploy a demo app that uses a GitHub webhook-based approval in CD-as-a-Service, you could create a page title such as “”.

Examples:

Pull request approvers check the frontmatter fields and can help with good wording for search engine optimization.

body

The body of your page should have one or more headings that organize your page into meaningful sections.

## < tutorial objectives >

## < {{% heading "prereq" %}} >

## < steps >

## Clean up

## < {{%  heading "nextSteps" %}} >

• tutorial objectives: This section should contain a brief overview and set the objectives in bullet points.
• {{% heading "prereq" %}}: Include a bullet list of links to prerequisite material that the reader should know or have done in order to perform the task. This heading is a Hugo shortcode that compiles to “Before you begin”.
• < steps >: The body should contain steps to complete the tutorial. The steps should be in separate headings, which should be short, descriptive, and optimized for search engines.
• Clean up: Include a section on how to clean up the resources, apps, etc that were created in the tutorial.
• {{% heading "nextSteps" %}}: (Optional) Link to related concepts, tasks, and/or tutorials. This heading is a Hugo shortcode that compiles to “Next steps”.

Examples:

• Kubernetes StatefulSet Basics tutorial

Reference

A Reference page contains the same frontmatter as other page types. The body format is less structured. Content is generally autogenerated material such as API and CLI references.

Troubleshooting

A Troubleshooting page contains the same frontmatter as other page types. The body format is less structured. Be sure to list the exact error the reader could encounter and the solution.

What’s next

Style Guide