sensu / sensu-docs

Sensu documentation

Welcome to the Sensu Docs project! This repository is the home of docs.sensu.io.

Read the docs | Contributing guide | Style guide | Code of conduct | [Contact admins][discourse] | Open an issue

---

We welcome all contributions! Read the contributing guide to get started.

For details on formatting and style, see the Sensu Docs style guide. If you have any questions, please submit an issue, or feel free to reach out in #documentation in the Sensu Community Slack.

Contributing quick start

From the docs site, select "Edit this page" to go to the corresponding markdown file in GitHub. From there, GitHub will prompt you to create a fork and submit a pull request. You can also submit documentation feedback by opening an issue.

Run the Sensu Docs site locally

The Sensu Docs site is a static site built with Hugo and markdown. These instructions will help you get the site running locally.

To contribute to the Sensu Docs, please read the contributing guide.

NOTE: You must install node version 12 through 18 to run the docs locally.

1. Install Git and Yarn

• Install Git on your computer and authenticate using HTTPS or SSH. Skip this step if you already have Git set up and authenticated on your computer.

• Install Yarn on your computer. Sensu Docs uses Yarn to manage dependencies and the build process.

2. Clone the Sensu Docs repo

You can clone the repo using either HTTPS or SSH.

Clone using HTTPS:

git clone https://github.com/sensu/sensu-docs.git && cd sensu-docs

Clone using SSH:

git clone [email protected]:sensu/sensu-docs.git && cd sensu-docs

If you prefer, download the repo from GitHub.

3. Run yarn

Run:

yarn

This will install Hugo and build the site into the public directory.

4. Run the site locally

If the site builds successfully, run:

yarn run server

This builds the Hugo server so you can view the site in your local web browser at http://localhost:1313/.

NOTE: If you navigate to a URL that uses the latest rewrite, such as http://localhost:1313/sensu-go/latest/, the local site will return a 404 error. Replace latest in the URL with a published docs version (for example, http://localhost:1313/sensu-go/6.9/) when running the docs locally.

Troubleshooting

Here are some things to try if you encounter an issue working with the site:

• Run yarn hugo-version to print the running version of Hugo. Version 0.101.0 or newer is required.
• Make sure you are running node version 12 through 18.
• If you're still having trouble viewing the site, open an issue, and we'll be happy to help!

Internet Explorer Users

The docs site displays incorrectly in Internet Explorer. If you cannot use a different browser, you can access a PDF copy of the Sensu documentation on our supported versions page.

Developing Offline Docs

Offline documentation uses a set of layouts located in the offline directory. To preview them:

yarn run server --layoutDir=offline

To exclude content from the offline documentation, add this line to the front matter in the markdown file:

offline: false

Deploying the site

Whenever changes are merged to the main branch, this project is automatically deployed to docs.sensu.io. For additional details on Heroku configuration and deployment, see our wiki page.

sensu-docs's Issues

Stylize the project/product page

We all seem to love what InfluxDB did at http://docs.influxdata.com/

Let's begin with a similar design/layout for our project/product page.

Add documentation for Sensu Enterprise 2.6

Migrate Sensu Enterprise 2.6 content from sensu-docs

Hide platform selector if there are none for the project

Projects like "Plugins" do not have a platform, it feels very strange to have the platform selector at the top of every page.

Y U NO DOCKER?

This is going to be my new default issue for all projects. 😛

Homepage on mobile

The new stylized homepage does not work well on mobile (in portrait and landscape). The homepage currently displays 3 rows of 2 tiles on my Pixel and the tile content is clipped.

Going to rows of a single tile would be awesome.

Specify Hugo version for users on other OS's

A quick note here:

When building on another OS, different Hugo versions may be installed based on what the OS repos provide (e.g., there are 2 Fedora copr repos, each offering a different version (.16, and .30 respectively), and Ubuntu/Debian will likely be lagging behind offering a more updated version(currently at .16)). My assumption is that as we move to make this repo public, we'll have quite a few folks using different OS's, and it would make things a bit easier on us in the long term to ensure that the README specifies the version of Hugo we're using, if nothing more so that when folks install it, they avoid any issues created by using something < .30.

Improve/change the JSON syntax highlighting theme

Current theme:

Reassess search scoping

After getting some content into the doc site project, determine how best to scope search results.

Redirect Uchiwa product to existing site

Bring back Sensu Metric Format documentation

Add the Sensu Metric Format documentation to sensu-enterprise/1.0/built-in-mutators/#enterprise-mutators and update the "proprietary intermediate format" link to point at its anchor.

Product & version menu on mobile

We have noticed a few areas for improvement on mobile. This issue serves as a place to note issues on mobile, in regards to the product and version menu. Once we have a collection of mobile issues, this issue will serve as a checklist.

Support multiple projects/products

The current Sensu docs site includes several Sensu tools in a single "bucket". We need a way to separate documentation on a per-product/product basis. InfluxDB does a fantastic job of this, see: http://docs.influxdata.com/

This issue will likely need to "explode" into several, more technical, github issues.

Project Objectives

This issues incapsulates the high level project objectives.

The current Sensu documentation site can be found at: http://sensuapp.org/docs

We need a new Sensu documentation site, separate from the Sensu website.

Some of the following bullets come from the discussion at: #543

Requirements:

• Supports writing docs in markdown (or something similar)
• Generates static site we can host in S3 or similar (not hard requirement)
• Local development/preview possible without access to existing private website project
• Online search
• Support for multiple projects/products
• Support for multiple versions

Other projects that "do it right":

• http://docs.influxdata.com/ (https://github.com/influxdata/docs.influxdata.com) (Hugo)

Working example of search

As search is one of the project objectives, we need to set up search (per project?) and provide a working example.

Create comprehensive Sensu Enterprise changelog

Left nav bar needs sections, e.g. "Reference", "Guides"

The left navigation bar (or sidebar menu) needs to support named sections, to group/collect documentation. Some example sections include "Reference" and "Guides" (see https://sensuapp.org/docs/1.0/ for more sections). We probably want the sections to be collapsable, as some of them can contain a large number of pages. As usual, InfluxDB does something similar, see http://docs.influxdata.com/influxdb/v1.3/.

Rename layouts in the interest of clarity

The current layout names, e.g. index, index-2, index-3 are somewhat unintuitive and we might consider renaming them to resemble their function. Here's the current intended usage per @dabria

single is what the default layout is for content.
Index is for a landing page to a project
project/index
Index-2 is the landing page for if you’ve picked a version.
project/1.0/index
Index-3 is the landing page for a subfolder from the version.
project/1.0/reference/index
Generally the first index is never seen because we take you directly to the latest version of a project and you can select a version from any page in the project, but it’s there to not break stuff.

Add documentation for Sensu Enterprise 2.7

Migrate Sensu Enterprise 2.7 content from sensu-docs

Investigate local development/preview

Images need to be brought over from old docs

Any images from the old documentation need to be moved over.

ex:

• Screenshots from here
• Don't exist here

Include FAQ from main site here

Discussed with @cwjohnston . It might be useful to pull in the FAQ page/make a new one based off of it in the docs site. FAQ's seem like a thing that would best live in the new docs site. Can we include that here?

Investigate using Hugo

Some related resources:

https://gohugo.io/getting-started/

https://themes.gohugo.io/material-docs/

https://github.com/influxdata/docs.influxdata.com

Version pulldown should sort in logical order

Move the Sensu Core plugin reference documentation to the Sensu Plugin doc project

footer with previous and next page buttons

Enable the footer to have left and right arrows to help you navigate the content smoothly and in a more structured order.

We'll add front matter attributes next and previous (or something similar) to achieve this.

Stylize project documentation layout

Now that the homepage associates a colour with a project (tile colour), it would be nice to have it continue on to the documentation content layout itself. Adjustments to page layout padding also need to be made.

Installation guide rewrite

Rewrite the Sensu installation guides, utilizing the new features, i.e. drop down selectors.

Create and deploy a basic Hugo site

We need to begin by producing something that can drive user/customer feedback.

• Create a basic Hugo site and push it to the sensu-docs-site repository
• Deploy the basic Hugo site (AWS S3?)
• Document the deployment process in README.md

Per-product redirects/aliases for "latest" docs

Under the existing middleman site we have a symlink for latest that points to the latest revision of the documentation.

Ideally this site would have similar URLs, e.g. /sensu-core/latest or /sensu-enterprise/latest, which point to the most recent version of the docs as defined under params.products.*.versions in config.toml

From briefly reviewing hugo documentation it looks like aliases are often configured per-page using frontmatter, which doesn't seem practical for our case.

Create Sensu installation page content

We need to test the current feature set to determine if we have met our objectives. In order to do this, we need a good representation of documentation content. The installation page content should serve this purpose well.

Go to latest version from landing page tile click

Users should find themselves at the documentation for the latest version of a project after clicking on the landing page tile for a project.

Old version warning banner

We need a warning banner to be displayed when a user is viewing documentation for an older (not latest) version of the Sensu.

Migrate Enterprise Dashboard content to Sensu Enterprise Dashboard product

We've ported over the Sensu Enterprise documentation content from sensu-docs, but left the old structure intact. We need to

• Identify content under Enterprise which belongs in Enterprise Dashboard docs
• Determine which version(s) of Sensu Enterprise Dashboard correlate to supported versions of Sensu Enterprise (2.6+)
• Move identified content from Sensu Enterprise to Sensu Enterprise Dashboard
• Reorganize content under Enterprise Dashboard so that menus look ok and flow is reasonable

Once expanded, menus should remain expanded while browsing a product version

Currently menus collapse each time we navigate to a new page, which is jarring. It would be great if we could keep the menus open while reading the docs; it seems natural to me that this state would be tracked per-product-version.

document code better

There are a few different spots in the code which could benefit from being explained a bit better to help maintainers. The readme could also be updated with additional information.

Create comprehensive Sensu Enterprise Dashboard changelog

Ordered lists break with code blocks

When an ordered list item contains a code block, the next list item resets to 1 instead of incrementing.

Theme the basic Hugo site

We need to begin to improve its presentation.

• Find a desirable public Hugo theme (https://themes.gohugo.io/material-docs/)
• Apply the Hugo theme and deploy it to get feedback
• Customize a small part of the theme (e.g. make it green)

Add reference and API documentation content

We need to begin the process of porting sensu documentation content. The reference documentation, i.e. checks, represents some low hanging fruit, it will help us identify problems in the new documentation framework. Enterprise and API documentation also lacks the platform variety that requires more attention before porting, it too can be pulled in.

The current reference documentation can be found at: https://github.com/sensu/sensu-docs/tree/master/docs/1.0/reference

Support multiple software versions per project/product

The current Sensu docs site maintains a full copy of the documentation, per Sensu Core version (e.g. 0.29), with modifications for the version (some features only exist for a single version etc). The current process for adding documentation for a new release is gross and fragile, see: https://github.com/sensu/sensu-docs#new-release. We need a (better?) way of separating and maintaining documentation per-release, per-project/product. InfluxDB does a good job of this from a user's perspective (IMO), using a version drop down at the top of the pages: http://docs.influxdata.com/influxdb/v1.2/

This issue depends on: #6

In-page platform drop downs

Being able to effect page content with in-page platform (e.g. ubuntu) drop downs would dramatically improve the user experience.

Rework the README

I'd like to update the README, especially since I've learned more about working with Hugo. I'd likely add instructions on where to put certain files and information about overrides.

Investigate static site deployment to S3

Footer/Menu behaving unexpectedly when refreshing half way down page

When refreshing a page mid-way down, the menu occasionally does not stay fixed and scroll up with the viewport.

Other times it scrolls too far up.

In addition, it causes the footer to extend way past where it should.

Migrate sensu-plugins.io docs to the Sensu Plugin doc projects

Triage existing documentation issues

In light of the migration we are working on from sensu-docs to sensu-docs-site, we need to figure out a process for triaging open documentation issues in the old repo.

We also have a handful of issues tracked as Trello cards in our private Customer Success board.

The main goal here is to ensure issues are either addressed as part of our migration/reorganization from sensu-docs -> sensu-docs-site, or that the issues are reopened against the new repo.

Automate search index builds

Automate search index builds, either on deploy or startup (works with preview).

The menus on the sidebar only go a directory deep after version

There may need to be additional code written to support deep directories.

project/version/folder1/item will appear on the list. However project/version/folder1/folder2/item will not.

The logic for displaying these items will probably have to be reworked at some point.

Convert Enterprise doc lists to tables

This is split off from #28

Check and fix documentation links

Skim through documentation and verify that links (relative and absolute) still work, correcting them as you go.