Hugo-tools NPM

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. npm.io

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.