apple / pkl-lang.org

The pkl-lang.org website

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 off commits to the main branch.

Install dependencies

$ ./gradlew downloadPklHtmlHighlighter 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 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

pkl-lang.org's Issues

Missing blog feed

The blog doesn't include a RSS or Atom feed.

It would be nice to have.

Search bar is missing from homepage

https://pkl-lang.org/index.html doesn't have a search bar.
The search bar only appears after clicking one of "Language", "Bindings", "Frameworks", etc.

Thank you for not forgetting neovim

It's an amazing surprise, thank you to the people involved.

Install/build instructions are broken

Following the README instructions resulted in an error:

Install dependencies
$ ./gradlew downloadPklHtmlHighlighter npmInstall

$ ./gradlew downloadPklHtmlHighlighter npmInstall
FAILURE: Build failed with an exception.

* What went wrong:
Task 'downloadPklHtmlHighlighter' not found in root project 'pkl-lang.org'.

I tried to run gw buildLocalSite nevertheless, but it failed with:

> Task :pklHtmlHighlighter FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':pklHtmlHighlighter'.
> A problem occurred starting process 'command 'cargo''

Ideally, a Gradle build shouldn't require "manual" installation steps.

Add installation option

Wrote a plugin to manage a pkl installation with the popular polyglot version manager, mise, and should work nicely with asdf as well. I think that should be put as an installation option on the website.

https://github.com/mise-plugins/asdf-pkl

Hamburger button not working on mobile

trim.762CB825-532D-48BD-8EC0-18A4C5B325E2.MOV

Docs use wrong Maven repo and wrong Gradle syntax

Example: https://pkl-lang.org/main/current/pkl-core/index.html#gradle

Is:

dependencies {
  compile "org.pkl-lang:pkl-core:0.25.2"
}

repositories {
  maven { url "https://s01.oss.sonatype.org/content/groups/public" }
}

Should be:

dependencies {
  implementation "org.pkl-lang:pkl-core:0.25.2"
}

repositories {
  mavenCentral()
}

compile was replaced with implementation long ago and might no longer work at this point.

Gradle snippets should use mavenCentral(). Maven snippets don't need a repo because Maven Central is the default.

PS: I tried to come up with a permalink for https://pkl-lang.org/main/current/pkl-core/index.html, but replacing current with 0.25.2 didn't work.