Getting Started

The skin generates the documentation in a comman format, that includes meta-data for each generated page.

The generated documents can be imported into a frontend project afterwards with the help of the included import scripts:

The following import scripts are included:

  • Astro: import-in-astro.sh
  • Hugo: import-in-hugo.sh
  • Standalone: import-in-standalone.sh

These scripts have to be called with the Bash-Shell explicitly.

Prerequisites

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

Usage example for Astro

Current version

To import the current release directly under the site root, call the generated script from the root of your project with the path to the frontend-project, where the documentation should be copied to:

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

Archived version

Import an archived version:

bash target/site/import-in-astro.sh \
    ../path/to/frontend-project \
    --archived

Publish archived versions in the subfolder /projects/

Import the current release directly under the site root as above:

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

Import the archived version under /projects/<artifact-id>/<version>:

bash target/site/import-in-astro.sh \
    ../path/to/frontend-project \
    --base projects \
    --archived \
    --canonical <artifact-id>

Usage example for Standalone

Current version

Publish the current release into the document root of a web server:

bash target/site/import-in-standalone.sh \
    /var/www/html

Archived version

Publish an archived version with a canonical link pointing to the current one:

bash target/site/import-in-standalone.sh \
    /var/www/html \
    --base projects \
    --archived \
    --canonical /projects/<artifact-id>

Common parameters of all scripts

Parameter Description
<PROJECT_ROOT> Path to the project root (required).
--base <path> URL and content path prefix. The project name and version are always appended. 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 overrides the computed URL base.
--archived [<url>] Marks this version as archived. params.canonical points to the corresponding current-version page. If <url> is given, it overrides the computed URL base.
--canonical <url> Explicitly sets the canonical URL base. Only valid with --archived. Default: <base>/<project>.

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

URL Defaults

Mode URL Base
--current, no --base /<artifact-id>/
--current --base /path /path/artifact-id>/
--archived, no --base /<project>/<version>/
--archived --base /path /path/<artifact-id>/<version>/