helixml / docs

Hugo Functionality - helixml/docs

Hugo is a static site generator built in Go, and it is the engine that powers the Helix Docs. Here are some of its features relevant to the Helix Docs project:

Shortcodes

Shortcodes are a simple way to add custom functionality to Hugo pages. They are written in Go’s text/template language and can be used to generate dynamic content. Here’s an example of a shortcode that generates a table of contents for a page:

{{ $pages := .Site.RegularPages }}
{{ $toc := .Params.toc }}
<div id="toc">
<h2>Table of Contents</h2>
<ul>
{{ range $pages }}
{{ if eq $toc "on" }}
{{ if ne .File.Ext ".md" }}
<li><a href="{{ .RelPermalink }}">{{ .Title }}</a></li>
{{ else }}
{{ $sections := index .Params.sections 0 }}
{{ range $sections }}
<li><a href="{{ .Permalink }}">{{ .Title }}</a></li>
{{ end }}
{{ end }}
{{ end }}
{{ end }}
</ul>
</div>

This shortcode generates a list of links to the pages in the site, grouped by the sections parameter in the page’s front matter. It is used in the Helix Docs by including it in a page’s markdown file like this:

{{< toc >}}

Partials

Partials are reusable pieces of HTML that can be included in multiple pages. They are useful for defining common elements like headers, footers, and navigation menus. Here’s an example of a partial that defines a navigation menu:

<nav>
<ul>
<li><a href="/">Home</a></li>
<li><a href="/docs/">Docs</a></li>
<li><a href="/blog/">Blog</a></li>
</ul>
</nav>

Partials can be included in a page using the partial function in a Hugo template:

{{ partial "nav.html" . }}

Markdown Support

Hugo supports the CommonMark flavor of Markdown, which is a widely used and well-documented markup language. Here’s an example of a markdown file that uses some of CommonMark’s features:

# My Page

This is a paragraph of text. It can contain **bold** and *italic* text, as well as links to other pages: [My Other Page](/other-page/).

## My Subheading

Here is a list of items:

- Item 1
- Item 2
- Item 3

And here is a code block:

```javascript
function myFunction() {
console.log("Hello, world!");
}

This markdown file can be rendered by Hugo as HTML using a template like this:

go

{{ define “main” }}

{{ .Content }}

{{ end }}

### Resources

* [Hugo Documentation](https://gohugo.io/documentation/)
* [CommonMark Specification](https://spec.commonmark.org/)
* [Writing for Developers: Take your Project Docs to the Next Level - Celeste Horgan, CNCF](https://www.youtube.com/watch?v=vz_5EdhHrmI)
* [Webinar: YAML Is Optional: Exploring an App Developer’s Kubernetes Options](https://www.youtube.com/watch?v=m-0KSfPwXas)
* [Docs from the ground up | Flux](https://fluxcd.io/contributing/docs/writing-docs)
* [Contributing new content | Kubernetes](https://kubernetes.io/docs/contribute/new-content)
* [Documentation style overview | Kubernetes](https://kubernetes.io/docs/contribute/style)
* [Lint prose with the Vale linter | Writers' Toolkit documentation](https://grafana.com/docs/writers-toolkit/review/lint-prose)
* [Test documentation changes | Writers' Toolkit documentation](https://grafana.com/docs/writers-toolkit/review/run-a-local-webserver)
* [Automated validation with doc-validator | Writers' Toolkit documentation](https://grafana.com/docs/writers-toolkit/review/doc-validator)
* [Links and cross references | Writers' Toolkit documentation](https://grafana.com/docs/writers-toolkit/write/references)
* [Tutorial: Build, test, and deploy your Hugo site with GitLab | GitLab](https://docs.gitlab.com/ee/tutorials/hugo)
* [Content organization | Kubernetes](https://kubernetes.io/docs/contribute/style/content-organization)
* [Front matter | Writers' Toolkit documentation](https://grafana.com/docs/writers-toolkit/write/front-matter)