Import Script: Hugo

import-in-hugo.sh imports a Maven site generated with the StILi skin into a Hugo project.

Prerequisites

bash
jq (JSON processor)
perl with HTML::Entities module (for <pre> block conversion)

Usage

Run the script from the Maven site output directory (target/site/):

bash target/site/import-in-hugo.sh <HUGO_ROOT> [OPTIONS]

Parameters

Parameter	Description
`<HUGO_ROOT>`	Path to the Hugo project root (required).
`--base <path>`	URL prefix prepended to all generated URLs. With `--current`: URL becomes `/<base>/<project>/`. With `--archived`: `/<base>/<project>/<version>/`. Also prepended to explicit `<url>` given to `--current`/`--archived`. Default: none (project at root).
`--project <name>`	Overrides the project name derived from `artifactId`.
`--current [<url>]`	(Default) Marks this version as the current (visible) release. If `<url>` is given, it replaces `<project>` in the URL: `/<base>/<url>/`.
`--archived [<url>]`	Marks this version as archived. `params.canonical` points to the corresponding current-version page. If `<url>` is given, it replaces `<project>/<version>` in the URL: `/<base>/<url>/`.
`--canonical <url>`	Explicitly sets the canonical URL base written to `params.canonical`. Not affected by `--base`. With `--archived`: defaults to `<base>/<project>` if not given. With `--current`: only written when this flag is given. Valid with both `--current` and `--archived`.
`--clean-only`	Remove the directories created by a previous import (content, static assets) and exit without importing. Mutually exclusive with `--no-clean`.
`--no-clean`	Skip cleaning the target directories before import. Mutually exclusive with `--clean-only`.

Only one of --current and --archived may be specified.

What the Script Produces

Content files

Each HTML page becomes a Hugo content file at:

content/<base>/<project>/<version>/<page-path>

Content files have YAML frontmatter with title, weight, outputs: [html], url, layout: article, and params.current / params.canonical.

Section nodes (pages with children) become _index.html files in a subdirectory. Leaf pages keep their .html filename.

Static files

Generated content directories (apidocs/, xref/, etc.) are copied to:

static/<url-base>/<directory>/

For each directory that also has a pages entry in stili-json, a redirect page is created in the content tree so that the nav link works correctly.

`<pre>` block conversion

<pre> blocks in the HTML body are converted to Hugo {{< highlight guess >}} shortcodes via perl. This ensures syntax-highlighted rendering in Hugo.

URL Defaults

Mode	URL Base
`--current`, no `--base`	`/<project>/`
`--current --base /path`	`/path/<project>/`
`--current <url>`, no `--base`	`/<url>/`
`--current <url> --base /path`	`/path/<url>/`
`--archived`, no `--base`	`/<project>/<version>/`
`--archived --base /path`	`/path/<project>/<version>/`
`--archived <url>`, no `--base`	`/<url>/`

Examples

Import the current release directly under the site root:

bash target/site/import-in-hugo.sh \
    /path/to/hugo-project

Import an archived version under /projects/ with explicit canonical:

bash target/site/import-in-hugo.sh \
    /path/to/hugo-project \
    --base /projects \
    --archived \
    --canonical /my-project

Import an old version at a historically-used URL (e.g., /my-project-2.0.0/):

bash target/site/import-in-hugo.sh \
    /path/to/hugo-project \
    --archived /my-project-2.0.0

The auto-computed canonical will point to /<project>/ (the current version's URL).