openbao/website

OpenBao Website

This subdirectory contains the content for the OpenBao Website. It is built using Docusaurus, a modern static site generator.

Table of Contents

• Contributions
• Running the Site Locally
• Versioned Documentation
• Editing Markdown Content
• Editing Navigation Sidebars
• Deployment

Contributions Welcome!

If you find a typo or you feel like you can improve the HTML, CSS, or JavaScript, we welcome contributions. Feel free to open issues or pull requests like any normal GitHub project, and we'll merge it in 🚀

Running the Site Locally

The website can be run locally through node.js. If your local development environment has a supported version (v18.0.0+) of node installed you can run:

• make

...and then visit http://localhost:3000/openbao.

Versioned Documentation

By default only the documentation for the main branch is built. When deploying to GitHub pages we enable versioned documentation and build the docs for the main branch and the last two minor releases (e.g. 2.4.x and 2.3.x). To build the versioned docs locally, run:

make build-versioned
make serve

The doc versions can be configured in the doc-versions.json file. Have a look at the Docusaurus docs for all available config options.

{
    "current": {
        "label": "Development"
    },
    "2.4.x": {
        "label": "Version 2.4.x"
    },
    "2.3.x": {
        "label": "Version 2.3.x"
    }
}

Editing Markdown Content

Documentation content is written in Markdown and you'll find all files listed under the /content directory.

To create a new page with Markdown, create a file ending in .mdx in a content/<subdirectory>. The path in the content directory will be the URL route. For example, content/docs/hello.mdx will be served from the /docs/hello URL.

This file can be standard Markdown and also supports YAML frontmatter. YAML frontmatter is optional, there are defaults for all keys.

---
title: 'My Title'
description: "A thorough, yet succinct description of the page's contents"
---

The significant keys in the YAML frontmatter are:

• title (string) - This is the title of the page that will be set in the HTML title.
• description (string) - This is a description of the page that will be set in the HTML description.

Markdown Enhancements

There are several custom markdown plugins that are available by default that enhance standard markdown to fit our use cases. This set of plugins introduces a couple instances of custom syntax, and a couple specific pitfalls that are not present by default with markdown, detailed below:

• If you see @include '/some/path.mdx', this is a markdown include. It's worth noting as well that all includes resolve from website/content/partials by default, and that changes to partials will not live-reload the website.
• If you see # Headline {#slug}, this is an example of a heading ID. It adds an extra permalink to a headline for compatibility and is removed from the output.
• Due to automatically generated headline IDs, any text changes to headlines can and will break existing permalinks. Be very cautious when changing either of these.

Custom Components

A number of custom mdx components are available for use within any .mdx file. Please consult the Docusaurus documentation for more information about them.

Syntax Highlighting

When using fenced code blocks, the recommendation is to tag the code block with a language so that it can be syntax highlighted. For example:

```
// BAD: Code block with no language tag
```

```javascript
// GOOD: Code block with a language tag
```

Check out the supported languages list for the syntax highlighter we use if you want to double check the language name.

It is also worth noting specifically that if you are using a code block that is an example of a terminal command, the correct language tag is shell-session. For example:

🚫BAD: Using shell, sh, bash, or plaintext to represent a terminal command

```shell
$ terraform apply
```

✅GOOD: Using shell-session to represent a terminal command

```shell-session
$ terraform apply
```

Editing Navigation Sidebars

The structure of the sidebars are controlled by the sidebar.ts and sidebarApi.ts files. For example, sidebar.ts controls the docs sidebar. Please consult the Docusaurus documentation on how to edit the sidebars.

Deployment

This website is hosted on GitHub Pages and configured to automatically deploy anytime you push code to the gh-pages branch. To perform a manual deployment run the following command:

$ GIT_USER=<Your GitHub username> yarn deploy