nginx-hugo-theme

A documentation theme for F5 NGINX projects using Hugo.

Installation

1. Add the nginx-hugo-theme theme as a module mount to your project's config file:

   [module]
   [[module.imports]]
   path="github.com/nginxinc/nginx-hugo-theme"

Usage

Create a new doc

Run hugo new <path/doc-title.md> to add a new doc.

Using the hugo new command adds all of our pre-configured frontmatter to the new file.

Build the docs

• Run hugo to build static HTML for your docs.
• Run hugo server to run the Hugo development server, so you can watch your changes as you work. Open localhost:1313 (127.0.0.1:1313) in a browser window to view the docs.

Shortcodes

See Hugo Shortcodes for an overview.

This theme contains the following custom shorcodes:

Callouts:

• caution.html
• important.html
• note.html
• see-also.html
• tip.html
• warning.html

Formatting:

• collapse.html - Make a collapsible section.
• details-disclosure.html - Renders information inside a toggleable element (open by default but can be toggled in/out of visibility).
• comment.html - Insert a comment that won't be rendered at build time.
• raw-html.html - Insert raw HTML into a markdown doc.

Custom data:

• openapi.html - Render an OpenAPI spec using ReDoc.
• metrics.html - Imports data from a JSON file and presents it in table format.
• ghcode.html - Rendering code from github

ghcode example

To render code directly from github at build time, you can use the ghcode shortcode.

Param 1 - The url for the raw github file you want to render

Param 2 - Options for highlighting following Hugo's Highlight shortcode

{{< ghcode "https://raw.githubusercontent.com/nginxinc/kubernetes-ingress/refs/heads/main/examples/custom-resources/access-control/access-control-policy-allow.yaml" "hl_lines=4" >}}

Includes

This theme contains a custom shortcode called "includes" that lets you reuse content.

To use this shortcode:

1. Add an "includes" folder to the folder that contains your site content (for example, content/includes).

2. In the includes folder, create an index.md file and add these lines:

   ---
   headless: true
   ---
   

You can reuse the content of any file in the includes directory using the following shortcode syntax:

{{< include "filename.md" >}}