Overview
To use BannoDocs head to http://docs.banno.com/
This doc site uses Hugo to compile markdown files into a rich website. There are a number of documents that contribute to the visual design and structure of the site in the /themes directory, while all viewable content resides in the /content directory.
Where did my old history go?
We recently moved the documentation site from Jekyll to Hugo. While this leads to improvements such as much quicker build times, easier deploys, and a process for local builds that actually works, the changes in file structure means GitHub is unable to track the history of each individual file prior to the Hugo cutover.
However, that history is not lost! Simply visit the most recent Git version before the cutover, find your file, and you can view the history prior to the Hugo cutover.
Structure & Organization
Our front page houses the most common points to visit, broken down into larger categories such as onboarding/guides, blog(latest news and developments), site reliability and our larger divisions(Operations, engineering, product, etc.).
Sections
In Hugo, each section denotes a grouped set of pages on the site. In order to be considered a distinct section at runtime, a folder must exist at any level under the /content folder, and the lowest level folder must contain a _index.md file with a title in the front matter. The url for this page will be the same as the folder structure that leads to it.
Creating a new section
To create a new section, simply create a new folder in the /content folder and make sure the folder has a _index.md file with front matter for the section’s name.
Pages
Front matter
In order for a page to be included in BannoDocs, it must include front matter.
Any file that contains a YAML front matter block will be processed by Hugo as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines.
At minimum you should add a title to any page you create, like so:
---
title: My new doc page
---
You can create any key/value pair in front matter that can be accessed through Hugo backend code.
From there you can write your content using Markdown syntax. If you need help writing Markdown, check out the definitive guide.
Table of contents
If your page is lengthy with lots of headings you may want to include a table of contents. Hugo has a collection of shortcodes to assist with organization, including the table of contents short code:
{{< toc >}}
Simply insert that code anywhere in your markdown file, and a table of contents will be created based on the headings in your page.
Note that the Table of Contents does not include H1s (ie, any headings prefixied with a single #). If you would like your headings to appead in the table of contents, ensure they are H2s (##) or lower.
Aliases
Aliases are typically reserved for high visibility, high traffic pages. Your doc can use aliases by adding the option to the title section. This will allow users to access the page either via its natural folder organization, or via any of the assigned aliases.
---
title: My Page
aliases: ['/my-preferred-url/', '/another-preferred-url']
---
Relative Linking
If you’d like to link to another page in BannoDocs, using relative links will allow you to view the link regardless of where the page is hosted, or whether or not you are running BannoDocs locally. While the syntax should be familiar, there are slight differences from what you’d use in normal markdown due to how Jekyll generates HTML. For example, take the following directory structure:
onboarding
-> resources/
-> data.md
-> _index.md
If you’d like to link to data.md from readme.md, you’d use this syntax:
[Link text](../resources/data)
or
[Link text](/onboarding/resources/data)
There are two important notes:
- The page you’re currently on counts as its own directory layer, so you’ll need to back up one level to reference files and folders at the same level.
- If you’re linking to a markdown file that will be rendered as HTML on BannoDocs, you’ll need to remove the extension. Seriously remove .md.
Running locally
Running a local version of the wiki is as easy as running hugo serve -D in your command line. By default, your local site will be running on localhost:1313.
If you don’t have Hugo installed on you machine, simply run brew install hugo in the command line.
Nix shell
Alternatively, a Nix development shell is provided. If you have Nix installed:
$ nix develop
warning: Git tree '/Users/ross.baker/src/wiki' is dirty
Restored session: Mon Aug 29 15:22:59 EDT 2022
🔨 Welcome to wiki
[general commands]
hugo - A fast and modern static website engine
menu - prints this menu
serve - builds and locally serves the documentation site
[wiki]$ serve
port 1313 already in use, attempting to use an available port
Start building sites …
hugo v0.101.0+extended darwin/amd64 BuildDate=unknown
Pushing updates live
Whenever a change is pushed to the master branch of the Wiki Github repo. If you don’t see changes, simply reach out in #org-documentation for assistance or kick off the Jenkins job, which will build and push any changes to the site.