-
Notifications
You must be signed in to change notification settings - Fork 54
Hugo and the Sensu docs
The Sensu docs project requires Hugo version 0.101.0 or later.
We expect that there may be desirable new features, breaking changes to Hugo's API, and other changes that require updating the minimum required Hugo version. That said, we also want to ensure we're using a known-good version of Hugo for building our site.
The Gruntfile.js implements tasks that automatically install Hugo as needed. The version to be installed is determined by the value of HUGO_VERSION environment variable in the Gruntfile, which grunt will default to 0.34.0 if not otherwise set.
The package.json file handles dependencies for /sensu-docs.
Except for the landing page and special cases like some tables on the Platforms and Distributions page, the Sensu docs are written in Markdown.
Most docs pages are stored in the /content/ subdirectory. Inside /content/, each Sensu project has its own section (e.g. sensu-go, sensu-core).
Each Sensu project requires configuration in the /config.toml file.
Use the static.json file to create redirects for docs pages and versions.
Read Add a docs version in the release-related page of this wiki to learn how to add a docs version to the docs site.
Front matter is the page-level attributes that are defined in yaml at the top of each page of Markdown. You can define default front matter with archetypes (in the /archetypes/ folder).
For pages in the Sensu Go project, here is the standard front matter:
---
title: "Supported versions"
linkTitle: "Supported Versions"
description: "Get details about Sensu's supported versions of official distributions, including packages, Docker images, and binary-only distributions."
version: "6.7"
weight: -30
offline: false
toc: false
product: "Sensu Go"
menu: "sensu-go-6.7"
---
---
title: "Populate metrics in InfluxDB with handlers"
linkTitle: "Populate Metrics in InfluxDB"
guide_title: "Populate metrics in InfluxDB with handlers"
type: "guide"
description: "Follow this guide to populate Sensu metrics into the time-series database InfluxDB with a handler, an action the Sensu backend executes when an event occurs."
weight: 160
version: "6.9"
product: "Sensu Go"
platformContent: false
menu:
sensu-go-6.9:
parent: observe-process
---
---
title: "Pipelines reference"
linkTitle: "Pipelines Reference"
reference_title: "Pipelines"
type: "reference"
description: "Pipelines are observation event processing workflows made up of filters, mutators, and handlers. Read the reference doc to learn about pipelines."
weight: 40
version: "6.9"
product: "Sensu Go"
platformContent: false
menu:
sensu-go-6.9:
parent: observe-process
---
---
title: "Supported platforms and distributions"
linkTitle: "Platforms and Distributions"
description: "Get Sensu Go for your platform: Linux, Windows, macOS, FreeBSD, and Solaris. Sensu Go is available as a package, Docker image, or binary-only distribution."
weight: -60
version: "6.9"
product: "Sensu Go"
platformContent: true
platforms: ["Linux", "Windows", "macOS", "FreeBSD", "Solaris"]
menu: "sensu-go-6.9"
---
| Attribute | Description | Required? |
|---|---|---|
| title | Text to display as the top-most header for the page. In sentence case. | Yes |
| linkTitle | Text to display in the left navigation menu as the title for the page. In title case. Usually a shortened verson of the title. If a page does not have a linkTitle, the docs site defaults to using the title instead. |
No |
| guideTitle | For guide pages only. Text to display as the page title in the Guides Index. In sentence case. | Yes (for guides) |
| reference_title | For reference pages only. Text to display as the page title in the Reference Index. In sentence case | Yes (for references) |
| type | Page type. Allowed values are guide or reference. Indicates that the page should be listed in the Guides Index](https://docs.sensu.io/sensu-go/latest/guides/) or Reference Index. |
Yes (for guides and references only) |
| description | Meta description for the page. Include a call to action, like "Read this page to..." Keep between 130 and 160 characters. In sentence case. | Yes |
| weight | Numeral used to specify the order of pages in the left navigation menu. If omitted, the docs site defaults to alphabetical order by title. | No |
| toc | Indicate whether to include a floating table of contents in right margin of the page. Boolean. If false, the docs site will not display the right nav table of contents. Helpful for pages with too many level 2 headings to list, like the release notes, or no level 2 headings, like the supported versions. |
No |
| offline | Indicate whether to include the page in the offline docs layout for PDF generation. Boolean. If false, the docs site will exclude the page from the offline layout. |
No |
| version | Major or minor Sensu Go version that the page belongs to. | Yes |
| product | Project that the page belongs to, in human-readable format. For example, "Sensu Go". |
Yes |
| platformContent | Indicate whether the page includes platform-specific code blocks or instructions. Boolean. If true, the docs site will display a dropdown menu for platform selection at the top of the page. |
No |
| platforms | Array of comma-separated platform names to display in the platform dropdown menu at the top of the page. | No |
| menu | Project that the page belongs to in a specific format. For top-level pages that are not nested within a category, see the Supported platforms and distributions example above. For pages that are nested within a category, see the guide and reference examples above. |
Yes |
| parent | Category the page is nested within. For categorized pages only (not top-level pages). See the guide and reference examples above. | Yes (for nested pages) |
Some front matter attributes like version are only needed because Hugo doesn't have a way of understanding a sub-section. A section is the first-level folder inside /content/. Any subsequent folders keep that folder name as their .Section. This means that /sensu-go/6.9/examplePage.md does not know that it's contained within the 6.9 folder without some parsing of its location. For the time being it's easier to assign a front matter attribute and track it that way.
In the /archetypes/ folder, name the file after the section it will be used for. Don't forget to include the .md extension. For example: sensu-go.md.
Here's an example of pre-defined front matter for any content that will be created for Sensu Go:
---
title: "{{ replace .TranslationBaseName "-" " " | title }}"
linkTitle: ""
guide_title: ""
reference_title: ""
type: ""
description: ""
weight:
version: ""
product: "Sensu Go"
platformContent: false
menu:
---
To create a new top-level page in the Sensu Go 6.9 docs from the command line, run:
hugo new sensu-go/6.9/new-page-name.md
This command will generate a new new-page-name.md file in /content/sensu-go/6.9/ with pre-defined front matter from the sensu-go.md archetype file at the top. Add and remove front matter in the new file as desired.
To create a new page in the Observability Pipeline > Entities subsection from the command line, run:
hugo new sensu-go/6.9/observability-pipeline/entities/new-page-name.md
Adjust the file path in the command as needed.
Create an index.html page for each section or sub-section.
Pre-built themes have limitations. However, Hugo makes it easy to override them. You should never edit any content in the /themes/ folder. If you wish to alter things, copy the corresponding files to the /layouts/, /layouts/_default/, or /layouts/partials/ folders respectively.
The main index page for the site is /layouts/index.html/.
The /layouts/_default/ directory contains single.html which is used as the main template for the site. We've also defined indexes for section and sub-section landing pages here.
The /layouts/partials/ directory contains small .html files which are components used in the other larger templates. There are things such as the header, dropdown menus, and footers here.
View the full list of Hugo variables.
Use variables with Go's templating.
A page's front matter can be accessed through the .Params variable.
You can also set global site variables inside the config.toml. Here's an example of global variables for a project:
[params.products.sensu_go]
identifier = "sensu-go"
name = "Sensu Go"
description = "The next-generation monitoring event pipeline"
notice = "Replaces Sensu Core and Enterprise"
weight = 1
latest = "6.9"
[[params.products.sensu_go.versions]]
version = "6.9"
platforms = []
[[params.products.sensu_go.versions]]
version = "6.8"
platforms = []
[[params.products.sensu_go.versions]]
version = "6.7"
platforms = []
[[params.products.sensu_go.versions]]
version = "6.6"
platforms = []
You can gain access to all the products with .Site.Params.Products. You can access a product's attributes like: .Site.Params.sensu-core.description.