This folder contains the source for the Apache Polaris website, built using Hugo and (the Docsy theme)[https://www.docsy.dev/docs/].

Run the following command from the project root to start the Hugo development server:

site/bin/run-hugo-in-docker.sh

Then point your browser to http://localhost:1313/

Then edit files from your IDE - you will see the changes in your browser.

When changing the site structure, it is often necessary to restart Hugo - just run site/bin/run-hugo-in-docker.sh again.

The scripts in the bin/ directory are built to work with both Docker and podman. There are nuances in how both behave, especially wrt docker/podman-compose. Some local environment specifics require the use of podman-compose, others the use of docker-compose. The default behavior is to prefer the podman and podman-compose binaries, if those exist and fall back to docker and docker-compose. Some setups using podman however require the use of docker-compose even if podman-compose is installed. This may manifest in an error message stating that --userns and --pod cannot be used together. In that case create a file .user-settings in the site/ folder and add these two lines:

DOCKER=docker COMPOSE=docker-compose

This builds the static Apache Polaris site into site/build/localhost-site to be served using a http daemon. The base URL will be https://localhost:8080/, which is the URL to be used when running the command below. (Note: static sites generated by Hugo do not work when opening the files from the local file system!)

Run

site/bin/create-static-site.sh --local

This builds the static Apache Polaris site into site/build/apache-site. The base URL will be https://polaris.apache.org/ (as configured in hugo.yaml). (Note: static sites generated by Hugo do not work when opening the files from the local file system!)

Run

site/bin/create-static-site.sh

(See /releases/ page as well.)

The idea here is that docs of releases live in either a separate branch or a separate Git repo.

The /releases folder would not be in the main Polaris repository (at least not in any code branch). It would be mounted either via git worktree or git clone. Building and testing the site locally works without the /releases folder. For developers, it is probably much easier to have a separate branch in the main Polaris GitHub repository and leverage Git worktrees.

Docs for the current code branch (e.g. main branch) are maintained in the /in-dev/unreleased folder. While we could maintain the docs right in the /in-dev folder, having the in-dev docs in /in-dev/unreleased provides the ability to use relative links that still work when the docs are in an /releases/x.y.z folder (think: links like ../../guides/foo-bar.md).

Within a release's versioned docs folder, the release version number can be included in the markdown using the custom Hugo shortcode {{< releaseVersion >}}.

The content/releases/ folder is maintained in the separate versioned-docs branch. The whole content/releases/ folder is .gitignored in the main source tree, otherwise Git complains about content/releases not being versioned and if added to the main source tree (possible, Git allows that), the git worktree add below would complain about the existing directory.

cd site/ cd content/releases/ # Create a new empty branch 'versioned-docs' git worktree add --orphan -b versioned-docs . # (add some content to the content/releases/ directory - at least the "top-level" _index.adoc git add . git commit -m "Initial set of releases"

Use the following script to checkout the versioned release docs

cd site/ # Checkout the versioned-docs branch locally bin/checkout-releases.sh

bin/remove-releases.sh removes the content/releases folder, if it does not contain uncommitted changes.

When a release is created, a bunch of things would happen via an automated GitHub workflow calling a shell script in the main source tree:

1. The releases versioned docs folder is created - for example: /releases/0.1.0
2. The contents of the /in-dev/unreleased folder are copied into the directory for the new release.
   1. The file release_index.md would be copied as _index.md into the new release's versioned docs folder, the /in-dev/unreleased/_index.md would not end in the release's versioned docs folder.
3. The front-matter of the release's _index.md would be rewritten.
4. The new release is added to params.active_releases in hugo.yaml
5. When publishing a new release for the most recent major/minor version:
   1. The new release's _index.md would be generated with exclude_search: false
   2. The front-matter of the previous release's _index.md would be updated, exclude_search: false changed to exclude_search: true.
6. When publishing a new release for an older major/minor version:
   1. The new release's _index.md would be generated with exclude_search: true
7. Update the "latest" redirect to point to the new release:
   1. Edit /releases/latest/index.md in the versioned-docs branch (i.e., site/content/releases/latest/index.md if using the Git worktree)
   2. Update the redirect_to parameter in the front matter to point to the new release (e.g., change redirect_to: '/releases/1.3.0/' to redirect_to: '/releases/1.4.0/')
   3. Edit site/static/.htaccess in the main branch and update the version in the RewriteRule for releases/latest/ (e.g., change /releases/1.3.0/$1 to /releases/1.4.0/$1). This rule handles deep links like /releases/latest/getting-started/.
8. Changes to the site added and committed to Git
9. Changes pushed to GitHub - both the main and the versioned-docs folder
10. The last step triggers the job to publish the web site

To build a site locally (not required for hugo serve -D, but required for hugo) - with your local user.

This would be a GitHub workflow.

1. Triggered when the main branch or the versioned-docs branch changes.
2. Checkout the main branch

3. cd site/

4. git worktree add content/releases/ versioned-docs

5. npm i -D postcss postcss-cli autoprefixer

6. rm -rf public ; hugo --minify --gc

7. Publish the contents of the public folder to the website.

The statically built web site in public does not work when opened from the file system.

Instead, do something like this:

1. rm -rf public ; hugo --minify --gc --baseURL http://localhost:8080/ (cd public/ ; http-server -p 8080 --cors)

2. Then use your web browser to open http://localhost:8080/

• The redoc shortcode works fine with hugo serve and on the static site configured via the baseURL in hugo.yaml. To test the static build result locally, it is mandatory to pass the --baseURL option to hugo.
• The embedded redoc looks awful with a dark theme.
• The swaggerui shortcode doesn't seem to work?
• Some changes, especially those that change the site structure, requires a restart of hugo serve -D. This is also true when the layout for the robots.txt is changed.

https://gohugo.io/installation/

To develop the site locally (aka hugo serve -D), install the following dependencies using the root user:

apt install asciidoctor snap install hugo snap install dart-sass

If you want to build the static site locally as well (aka build with hugo + serve using another http server), the following dependencies are needed as well (non-root user):

npm i -D postcss postcss-cli autoprefixer npm install http-server -g

To develop the site locally (aka hugo serve -D), install the following dependencies:

brew install go brew install hugo brew install asciidoctor

If you want to build the static site locally as well (aka build with hugo + serve using another http server), the following dependencies are needed as well (non-root user):

brew install npm npm -i -D postcss postcss-cli autoprefixer npm install http-server -g

• Hugo: https://gohugo.io/
• Docsy theme: https://www.docsy.dev/docs/ and https://github.com/google/docsy/
• Asciidoc help: https://docs.asciidoctor.org/asciidoc/latest/
• Fontawesome logos/icons: https://fontawesome.com/v6/search?o=r&m=free