hugo-tools

Command line tools to extend hugo's functionality.

Prerequisites

• Hugo Extended : You can install it by following this tutorial
• Node 12: You can install it via nvm
• postcss-cli: You can install it by running npm install -g postcss-cli on terminal

Installation

• Install hugo-tools globally

npm install -g hugo-tools

• And then you should be able to run the CLI with

hugo-tools --help
Usage: cli [options] [command]

Options:
  -h, --help              display help for command

Commands:
  init [options]          initialize .hugo-site directory
  build [options]         Build website
  start                   start server
  update-theme [options]  Change the theme
  watch [options]         Watch changes in source directory and build website when it changes
  help [command]          display help for command

Configuration

Configuration for the application is at config/default.js. The following parameters can be set in env variables or using hugo-tools config key value to set:

• MERMAID_EXTENSIONS: mermaid extensions, default value is ['mermaid']
• PUML_EXTENSIONS: puml extensions, default value is ['puml', 'plantuml']
• HUGO_DIRECTORY: hugo directory, default value is .hugo-site
• THEME_PATH: theme path, default value is themes/theme/
• SITE_CONFIG_NAME: site config name, default value is config.toml
• HUGO_CONFIG_PATH: hugo config name, default value is config.toml
• GITLAB_PRIVATE_TOKEN: gitlab private token
• DEFAULT_THEME_SOURCE: default theme source
• SOURCE_DIR: source dir, default value is content

Usage

• cd into the directory that contains wiki folder in it.

cd folder

• Create a config.toml in that directory. You should use this template . You can also find information about environment variables supported by hugo-tools in Configuration docs

• Initialize .hugo-site directory that contains website files

hugo-tools init --theme <theme-path> --config-toml <config-path>

<theme-path> corresponds to either a git url or the local path of theme e.g. https://gitlab.com/tmo-poc/hugo-dep/tmo-hugo-themes.git

<config-path> corresponds to local path of config.toml by default config.toml file in the current working directory will be used.

• To build the website

hugo-tools build --index-file <index-file-name> --source-dir <source-directory>

index-file-name is the name of the file that you want to use as home page. If the option is not provided Home.md file will be used by default.

source-dir is the folder that contains markdown source files, if the option is not provided wiki folder will be used by default.

• To serve website

hugo-tools start

Now you can access the site through http://localhost:1313/

• To rebuild the website automatically when you change the content run this command.

hugo-tools watch

Now you can access the site through http://localhost:1313/

Unless you add or remove a directory to content, the page will be reloaded automatically when build completes. You have to reload manually if you add or remove a folder.

Updating theme

If you want to update the theme after initializing .hugo-site directory, you can use this command.

hugo-tools update-theme --theme <theme-path>

Help command

You can run hugo-tools --help to see all the options for the CLI.

Features

1. Include Remote or Local file

You can include remote or local file contents in your content using file inclusion expression. e.g.

@[title](<file-path-relative-to-this-md-file>) # or
@[title](https://path-to-file.com/file.ext) # or
@[title](http://path-to-file.com/file.ext)
@[title](http://gitlab.com/fake-repo/fake-file.json)
@[title]($parent/file.ext)

This will put contents of the file inside a code block with the right file extension. You can use it to include puml or mermaid files as well, they will be replaced with charts.

You can also include a file from a gitlab repo, but make sure the GITLAB_PRIVATE_TOKEN is configured first in order for the tool to read the file.

You can use the $parent to include a file from parent folder relative to the source-dir.

If the included file is an image file with one of these extensions '.bmp', '.jpg', '.jpeg', '.png', '.gif', '.webp' the image will be displayed in the page.

You can also resize the image by adding ?width=<width>&height=<height> to image url. e.g. @[title](http://path-to-file.com/file.jpg?width=100&height=200). You can also specify the unit (e.g. px, em, vw, vh) like @[title](http://path-to-file.com/file.jpg?width=50vw&height=50vh)

Image resizing is also available for markdown image expressions i.e.

2. PlantUML charts

You can render PlantUML charts anywhere in your content using plantuml scripts such as

Alice -> Bob : hi
Bob -> Alice : hello

This will be replaced with the chart image.

You can also include a plantuml file using file-include-expression. The file must have a puml extension. @[title](directory/file.puml?height=10vh&width=150px)

3. Mermaid charts

You can render mermaid charts any in your content using mermaid scripts such as

sequenceDiagram
    Alice->>John: Hello John
    %% this is a comment
    John-->>Alice: Great!

You can also include a mermaid file using file-include-expression. The file must have a mermaid extension. @[title](directory/file.mermaid?height=10vh&width=150px)

4. Swagger File

You can render a Swagger UML diagram anywhere in your content by including a swagger-2.0 or openapi-3.0 JSON or YAML file, like this: @[title](directory/openapi.yaml?height=100vh&width=150px)

Theswagger-to-plantuml package is used to convert the swaggger file into plantuml, which is finally rendered as image.

Also Swagger UI page for the specification will be generated and a link to that page will be added following the UML chart.

5. Markdown File

You can render contents of another markdown file anywhere in your content by including it. e.g. @[Markdown file](path/to/markdown.md)

Local Setup with docker-compose

You can find instructions for running hugo-tools with docker-compose here

Configuration

You can find information about configuration in Configration Docs

Hugo Guide

Your markdown files should follow the Hugo Guide in order to be processed by the pre-processing scripts and the Hugo properly.

CI / CD

You can find instructions on automatically building and deploying site on CI/CD Guide

Developer Guide

You can find development docs here