site: add blog anchors

build.gradle.kts

@@ -76,6 +76,9 @@ tasks.named<RatTask>("rat").configure {
   excludes.add("site/layouts/partials/community_links.html")
   excludes.add("layouts/partials/head.html")
 
+  // Hugo render hook - HTML comments would appear in rendered output
+  excludes.add("site/layouts/_default/_markup/render-heading.html")
+
   // Files copied from OpenAPI Generator (ASLv2 licensed) don't have header
   excludes.add("server-templates/*.mustache")
 

site/README.md

@@ -23,15 +23,16 @@ This folder contains the source for the Apache Polaris website, built using [Hug
 
 ## Quickstart
 
-Just run the following command to let Hugo serve files from the Polaris `site/`.
+Run the following command from the project root to start the Hugo development server:
 ```bash
 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. 
+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. 
 
 ### Dealing with `--userns and --pod cannot be used together` errors
 

site/hugo.yaml

@@ -277,6 +277,9 @@ markup:
     style: 'monokai'
     tabWidth: 4
   goldmark:
+    parser:
+      autoHeadingID: true
+      autoHeadingIDType: github
     renderer:
       unsafe: true
 

site/layouts/_default/_markup/render-heading.html

@@ -0,0 +1,8 @@
+{{- /*
+  Render hook for headings that adds anchor links.
+  See https://gohugo.io/render-hooks/headings/
+*/ -}}
+<h{{ .Level }} id="{{ .Anchor | safeURL }}"{{ with .Attributes }} {{ range $k, $v := . }} {{ $k }}="{{ $v }}"{{ end }}{{ end }}>
+  {{- .Text | safeHTML -}}
+  <a class="heading-anchor" href="#{{ .Anchor | safeURL }}" aria-label="Anchor">#</a>
+</h{{ .Level }}>