Import Script: Astro

import-in-astro.sh imports a Maven site generated with the StILi skin into an Astro project.

Prerequisites

bash
jq (JSON processor)

Usage

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

bash target/site/import-in-astro.sh <ASTRO_ROOT> [OPTIONS]

The script checks for package.json in <ASTRO_ROOT> to verify that the path points to an Astro project.

Parameters

Parameter	Description
`<ASTRO_ROOT>`	Path to the Astro 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 omitted. With `--current`: only written when this flag is given. Valid with both.
`--clean-only`	Remove the directories created by a previous import (content, routing, 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 content file with YAML frontmatter at:

src/content/projects/<project>/<version>/<page-path>

The content is always placed under src/content/projects/ regardless of --base. The --base flag controls only the generated URL structure. Frontmatter fields: title, weight, url, params.current, and (for archived or explicit --canonical) params.canonical. The HTML body follows the frontmatter delimiter.

Section nodes (pages with children) become _index files in a subdirectory; leaf pages keep their name without extension:

Maven output	Content path	URL (current, no `--base`)
`index.html`	`projects/<project>/<version>/_index`	`/<project>/`
`project-reports.html` (has children)	`projects/<project>/<version>/project-reports/_index`	`/<project>/project-reports/`
`configuration.html` (leaf)	`projects/<project>/<version>/configuration`	`/<project>/configuration/`

URLs are always flat (no URL nesting matching the content hierarchy), reflecting Maven's own flat site structure.

Routing files

For each content file a minimal Astro routing file is created at the path corresponding to the page URL:

src/pages/<base>/<project>/index.astro               (current, root page)
src/pages/<base>/<project>/configuration.html.astro  (current, leaf page)
src/pages/<base>/<project>/<version>/index.astro     (archived, root page)

The import depth (number of ../ segments in the ProjectPage.astro import) is computed dynamically from the actual URL depth, so --base values of any nesting level are handled correctly.

Static files (generated content)

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

public/<url-base>/<directory>/

where <url-base> is the effective URL base (from --base combined with the project/version path, or the explicit <url> given to --current/--archived).

Relative links inside content pages that point to generated directories (e.g. href="apidocs/") are rewritten to absolute URLs with an explicit index.html (e.g. href="/<url-base>/apidocs/index.html").

Known Generated Content Directories

The following directories are recognised as generated content (defined by GENERATED_DOC_NAMES in the consuming Astro project):

Directory	Typical content
`apidocs/`	JavaDocs
`testapidocs/`	Test JavaDocs
`xref/`	Source cross-reference
`xref-test/`	Test source cross-reference

Visibility and Discoverability

--current and --archived determine not only the URL structure but also whether a version is publicly visible:

Current versions (--current) appear on the project overview page (/projects/) and in the site-wide navigation menu (SitemapNav), so search engines can discover them automatically by following links.

Archived versions (--archived) are not listed on the overview page and do not appear in the navigation menu of any other page. They are therefore not automatically discoverable — but remain accessible by direct URL (and can be read by search engines that already know the URL).

The consuming Astro project does not configure @astrojs/sitemap, so no automatic sitemap is generated either.

Use case — pre-publication testing: When a new project's documentation has not yet been published (--current never used), it can be imported with --archived to review it in the live site without accidentally making it publicly visible or discoverable by search engines.

URL Defaults

Mode	URL base	Content path
`--current`, no `--base`	`/<project>/`	`src/content/projects/<project>/<version>/`
`--current --base /path`	`/path/<project>/`	`src/content/projects/<project>/<version>/`
`--current <url>`, no `--base`	`/<url>/`	`src/content/projects/<project>/<version>/`
`--current <url> --base /path`	`/path/<url>/`	`src/content/projects/<project>/<version>/`
`--archived`, no `--base`	`/<project>/<version>/`	`src/content/projects/<project>/<version>/`
`--archived --base /path`	`/path/<project>/<version>/`	`src/content/projects/<project>/<version>/`
`--archived <url>`, no `--base`	`/<url>/`	`src/content/projects/<project>/<version>/`

The content path is always src/content/projects/… regardless of --base or explicit URL overrides.

Examples

Import the current release at /<project>/ (default):

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

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

bash target/site/import-in-astro.sh \
    /path/to/astro-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-astro.sh \
    /path/to/astro-project \
    --archived /my-project-2.0.0

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