Pkl Documentation Website

Repo for Pkl’s documentation website.

The website is built with the Antora docsite generator out of Asciidoc docs maintained in upstream projects (pkl, pkl-spring, etc.).

Development

Releases

Releases of the website are triggered by commits to the main branch.

Install dependencies

The Pkl HTML highlighter is written in Rust. For now, this project’s build configuration requires cargo to be installed on the local system.

$ ./gradlew pklHtmlHighlighter npmInstall

Build Docs of Local Projects

• Takes upstream project docs from local Git repos assumed to be siblings of this repo (see site-local.yml).

• Builds the site (click the link printed in console output to open in browser).

This allows you to preview local doc changes made to upstream projects.

$ ./gradlew buildLocalSite   # shorthand: gw bLS

Validate Docs of Local Projects

• Validates HTML

• Checks for dangling links

$ ./gradlew validateLocalSite   # shorthand: gw vLS

Build Docs of Remote Projects

• Fetches upstream project docs from their GitHub repos (see site-remote.yml).

• Builds the site (click the link printed in console output to open in browser).

This is what CI runs.

$ ./gradlew buildRemoteSite   # shorthand: gw bRS

To run this task locally, you must have token-based access for GitHub.com setup,

Validate Docs of Remote Projects

• Validates HTML

• Checks for dangling links

$ ./gradlew validateRemoteSite   # shorthand: gw vRS