README.md

MinIO's DirectPV Documentation

The DirectPV docs use Hugo to generate static HTML pages.

• MinIO's DirectPV Documentation
  • Prerequisites
  • Setup
  • Update Theme from Upstream Repository
  • Build Preview
  • Build for production
  • Style
    • Markup
    • Style Guides
    • Spelling
    • Code Blocks
  • Shortcodes
    • Internal linking
    • Components (Tabs, Admonitions, Cards, etc.)
  • Frontmatter

Prerequisites

• Any operating system that Hugo supports

• nodejs 16.9.x or later

  Note: Ubuntu ships with older versions of Node that Hugo does not support. Use nvm to install a later version.

• Node Package Manager installed (8.5.0 or later)

• Hugo installed (0.110.0 or later)

Setup

1. Clone this repository

2. cd to the directory (cd directpv-docs)

3. Initialize the theme directory submodule

   git submodule update --init --recursive
   

4. cd themes/kes-doc-theme

5. npm install

6. npm run build

7. cd ../../

Update Theme from Upstream Repository

The theme we use in the docs is hosted and maintained in a separate, private repository. We use a the git submodule functionality to include it here. After updating the theme, re-install node packages and then re-build the theme assets.

To pull new updates to the theme from the upstream repository, run the following:

git submodule update --recursive --remote
cd themes/hugo-docs-theme
npm install
npm run build
cd ../../
git add . && git commit -m "Update theme"

Build Preview

You can launch a live preview of the site as you work.

1. From your terminal in the repository folder, run

   hugo server

2. In your browser, go to localhost:1313/docs/directpv/

Build for production

To build the site for production or to upload to the staging server:

1. Run

   hugo

2. Contents go to the /public directory in the repo folder.

Style

Markup

We write in Goldmark Markdown as extended by Hugo shortcodes and our own shortcodes.

Goldmark is fully Commonmark compliant.

Style Guides

MinIO uses an internal style guide. Allow maintainers to modify your branch when you submit your PR so that we can adjust for internal style consistencies.

Otherwise, follow these resources in order of preference:

1. MongoDB Style Guide
2. ASD-STE-100 Simplified Technical English
3. Google Developer Style Guide

Spelling

We write in American English, using Merriam Webster's online dictionary as the standard spelling reference.

Code Blocks

To add a copy button to a code block, add {.copy} after the language format.

For example

```yaml {.copy}
tls:
  key:      ./server.key   # Path to the TLS private key
  cert:     ./server.cert  # Path to the TLS certificate
  password: ""             # An optional password to decrypt the TLS private key

The code block must have a valid language type for the copy function to work.

Shortcodes

Hugo uses shortcodes to extend what is normally available with Markdown.

Internal linking

To link to another page within the docs, use the following format.

[link text]({{< relref "path/to/page/#heading" >}})

Components (Tabs, Admonitions, Cards, etc.)

Refer to themes/hugo-docs-theme/README.md.

Frontmatter

We use YAML-formatted front matter.

Pages should have at least the following front matter tokens:

---
title: <Page Title>
date: YYYY-MM-DD ## date of file creation
lastmod: :git ## this is retrieved from git and should not be modified
draft: false ## set to true if the document is not yet ready for publication
tableOfContents: true ## creates a right-side page navigation TOC, set to `false` if not needed
---