This directory contains the documentation site infrastructure for Apache Amoro. It's built with Hugo and hosted at https://amoro.apache.org.

The Amoro documentation site consists of both versioned and non-versioned content, organized as follows:

.
├── docs (versioned)
│   ├── admin-guides
│   ├── concepts
│   ├── engines
│   ├── formats
│   ├── images
│   └── user-guides
└── site (non-versioned)
    ├── amoro-docs
    │   ├── archetypes
    │   ├── content (symlink to ../../docs)
    │   ├── hugo.toml
    │   └── themes
    ├── amoro-site
    │   ├── archetypes
    │   ├── content
    │   ├── hugo.toml
    │   └── themes
    ├── amoro-theme
    └── README.md

The documentation is organized into versioned and non-versioned content:

• Versioned Content (/docs): All markdown pages specific to an Amoro version are maintained in the main repository's /docs directory. These include user guides, admin guides, concepts, and other technical documentation.

• Non-versioned Content (/site): The website infrastructure and common pages shared across all versions are maintained in the /site directory, which includes:

  • amoro-site: Contains the landing page and common content
  • amoro-docs: Contains the documentation site that renders versioned content (via symlink to /docs)
  • amoro-theme: Contains the Hugo theme used by both sites

During each new release, the release manager will:

1. Create a branch from master named for the release version
2. Update the latest branch HEAD to point to the release branch HEAD

• Version-specific content: Changes to the markdown contents for version-specific pages should be submitted to the /docs directory.

• Non-versioned content: Changes to common pages, website appearance (HTML, CSS), etc. should be submitted to the /site directory.

• Old version documentation: Changes to documentation of old Amoro versions should be submitted against the specific version branch.

All issues related to the doc website should be submitted to the Amoro repository.

To run the website locally:

# From the root of the repository

To start the site page locally, run:

(cd site/amoro-site && hugo serve)

To start the documentation site locally, run:

(cd site/amoro-docs && hugo serve)

In some cases, it's useful to test both the amoro site and the docs site together, especially for testing relative links between the two. This can be achieved by building both sites with custom baseURL and publishDir values:

First, build the main site:

cd site/amoro-site
hugo -b http://localhost:5500/ -d ../../public

Next, build the docs site:

cd ../amoro-docs
hugo -b http://localhost:5500/docs/latest/ -d ../../public/docs/latest

You can then serve the combined site from the public directory using any local server.

To scan for broken links, you can use the linkcheck tool available here.