Internal documentation only

This page has been marked as a draft.

Design guidelines

Design README Copied

This page describes the structure of the core-docs and covers some best practices that apply to all Hugo docs projects. For information about commands and builds see README.md

Main Hugo docs can be found here: https://gohugo.io/documentation/

There are many variants of Markdown, we use Commonmark following Hugo defaults and converging with Github. The full spec can be found here: https://spec.commonmark.org/

More project guidelines can be found in:

Caution: This page may not contain the latest guidelines. For up-to-date information, see https://github.com/ITRS-Group/core-docs/blob/master/DESIGN.md

Folder structure Copied

The standard discussion of Hugo directories can be found here https://gohugo.io/getting-started/directory-structure/ and it is also important to understand that files in the root of the config folder override files in the themes folder, this is covered by https://gohugo.io/templates/lookup-order/. Once you have read and understood those docs, we can consider how we will use all these options in our projects.

Because we have separated content projects into separate repos the standard hugo structure is composed from core-docs and project-docs at build time. This is configured in core-docs/docker-compose.yml and core-docs/build.yml.

core-docs Copied

Core-docs contains shared configuration, importantly per project parameters and the ITRS theme.

The project directory structure is similar to:

├── config
│   ├── capacity-planner
│   ├── global
│   ├── obcerv
│   ├── obcerv-app-alerting
│   ├── ...
└── core
    ├── archetypes
    ├── config
    ├── content
    ├── layouts
    ├── resources
    ├── static
    └── themes

The ITRS theme looks like:

├── archetypes
├── assets
│   ├── css
│   ├── js
│   └── sprites
├── layouts
│   ├── _default
│   │   └── _markup
│   ├── partials
│   │   ├── dev
│   │   ├── head
│   │   ├── shortcodes
│   │   │   └── links
│   │   └── third-party
│   ├── release-notes
│   ├── shortcodes
│   │   └── snippets
│   │       ├── capacity-planner
│   │       ├── global-only
│   │       └── netprobe
│   └── whats-new
└── static
    ├── images
    └── less
        ├── base
        └── extend

project-docs Copied

Each project has a separate repo that contains the markdown content, images, and some configuration specific to that project.

The project directory structure is similar to:

├── config
│   ├── config.toml
│   ├── menu.toml
│   ├── params.toml
├── content
│   ├── troubleshooting
│   ├── upgrade
│   └── user-guide
└── static
    └── images

Where the config files provide:

Config approach Copied

We are taking advantage of the Hugo config inheritance properties so build configuration loads in the following order:

  1. config.toml from core folder (Shared across all projects)
  2. config.toml, params.toml… from config/proj-name/_default in core docs (Shared across proj-name project)
  3. config.toml, params.toml… from config folder in each project repo (Specific per version)

Hugo applies a merge approach except for repeated keys which take the one with higher priority.

The latest key has greater priority than the prior and so on. As a result the project-content parameters have the highest priority.

The config.toml file contains:

Parameters can also be set in a params.toml file, which is useful when overriding defaults for specific projects.

Left navigation menu Copied

We use a menu.toml file to provide a custom table of contents whole projects. This allows us to centrally manage information architecture updates and link to topics outside of a repo. This feature is described in Menus.

The project-docs/config/menu.toml file is similar to the project-docs/Project/TOCs/Master.fltoc file used in flare, and is loaded in the navigation-menu-left-nav.html and main-footer-left-nav.html partials. If no menu.toml file is found, then Hugo will fallback to using the autogenerated menu that is set either by the frontmatter weights or, where those do not exist, alphabetical order.

The syntax of menu entries is as follows:

[[left_nav]]
identifier='getting-started/introduction'
name='Introduction'
pageRef='getting-started/introduction'
parent='getting-started'
weight=100

Note that:

Layouts or templates Copied

Layouts in Hugo are similar to masterpages in Flare but much more modular. Layouts are a type of golang template specialised for Hugo layouts, the name layout and template are used interchangeably. In Hugo, layouts tell the build process how to transform the markdown content we write into html that can be rendered by a browser.

In core-docs we build up the index page, section pages, and topics from partials and layouts in the core-docs/core/themes/itrs/layouts directory. Below is an incomplete example of that flow:

BASEOF│
      │head/meta
      │title
      │head/favicons                        │
      │head/css                             │home-header
      │third-party/gtm-top                  │topbar
      │head/js                              │sidebar-navigation
      │third-party/gtm-body                 │content
      │header                               │looking-for-more
      │breadcrumb                           │
      │topbar                     │         │
      │MAIN ◄─────────────────────┤INDEX ◄──┘
      │main-footer                │               │
      │footer                     │LIST  ◄────────┤sidebar-navigation
      │js-bottom                  │               │content
      │svg-sprites                │SINGLE◄──┐     │
      │                           │         │
                                            │sidebar-navigation
                                            │content
                                            │toc
                                            │rate-this-topic
                                            │

Read from left to right for the program flow or follow the arrows to see composition flow. It may help to have the layouts folder open while reading this diagram.

Partials Copied

Partials are small layout files used to compose the main layouts and provide content reuse. In this way partials and short codes are similar, but partials can only be used in other layouts and not in markdown topics. For more information, see partial templates.

To create a partial, add a template in the /layouts/partials/ directory of your project or theme. You need to include the full path including the file extension when calling a partial.

For example, core-docs/core/themes/itrs/layouts/partials/home-header.html can be called with {{ partial "core-docs/core/themes/itrs/layouts/partials/home-header.html" . }} where the . refers to the ‘here’ context.

Markdown processing Copied

In addition to the layout of our pages we can also configure in general how markdown is processed, for example the default syntax highlighting settings.

There are two things that effect how markdown is rendered, the goldmark settings in the main config file and the render hooks layout files in /themes/itrs/layouts/_default/_markup. We use the render hooks to provide the anchor links on each heading.

Global docs Copied

Global docs deviates from the typical structure of our documentation projects. To accommodate this, additional layouts and parameters have been created.

The full details of these layouts can be found in https://ice.itrsgroup.com/display/TC/Global+docs and global-docs readme.

Shortcodes Copied

Content shortcodes provide content reuse for text and code samples in markdown topics.

Shortcodes are a specific type of template used to provide either content reuse (like snippets in flare) or additional functionality not available in basic markdown. For more information, see shortcodes and create your own shortcodes.

To create a shortcode, place a template in the layouts/shortcodes directory of your project or theme. The shortcode name will mirror that of the file but without the .html extension.

For example, layouts/shortcodes/snippets/hub-highlights-2-5-x.md can be called like:

Images Copied

Images live in each project under:

<project>/static/images/descriptive-filename-<created-version>

To add an image to a topic use the standard markdown syntax:

![Alt text here](/project/images/image.jpg "Title here")

which generates html during the build following the layout in /layouts/_default/_markup/render-image.html.

More information can be found here: https://gohugo.io/getting-started/configuration-markup/

When adding links to other docs projects in hugo (i.e in a capacity planner app topic you might want to link to the main capacity planner docs) you need to adjust the url a bit to ensure it grabs the correct devdocs/uatdocs/docs environment.

So overall:

The use of __tcproject__ is so that the redirect RewriteRule ^\/docs\/obcerv(\/.*)/__tcproject__/(.*)$ /$2 [R=301,L,R,NC] can be applied.

Static Copied

Files placed in the static directory are copied into the output without modification as part of the build. Typically, this is used for images, js and css as described in static files.

However, in our case we do want to process the .less files in this directory since these must be compiled to css. To do this you must install the Easy LESS extension for VS Code which will automatically compile the .less files to css whenever you make a change. You can then commit both changes normally.

LESS Copied

LESS is a superset of css and compiles down to css files. This means we gain power but avoid lock-in. LESS is described in detail here.

LESS files are loaded in order from core-docs/core/themes/itrs/static/less/styles.less.

Assets Copied

Files intended to be processed by Hugo pipes are placed in the assets directory. We use this to provide asset minification of js and css which helps improve page load times.

Data directory Copied

We do not currently use a data directory.

However, Hugo’s data processing abilities may be useful for importing release notes from automated process for rolling release products, see https://gohugo.io/templates/data-templates/#get-remote-data for an example.

["Obcerv"] ["User Guide"]

Was this topic helpful?