Skip to content

Commit 63aac92

Browse files
theunrepentantgeekBevan ArpsCopilot
authored
Update Hugo and Docsy (#5708)
* Update Hugo and Docsy Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> * Address documentation toolchain review Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> --------- Co-authored-by: Bevan Arps <bevan.arps@micosoft.com> Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
1 parent 9b59c9c commit 63aac92

13 files changed

Lines changed: 198 additions & 44 deletions

File tree

‎.devcontainer/Dockerfile‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,7 +15,7 @@ ENV DEBIAN_FRONTEND=noninteractive
1515
RUN curl -fsSL https://download.docker.com/linux/debian/gpg | gpg --dearmor -o /usr/share/keyrings/docker-archive-keyring.gpg \
1616
&& echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/docker-archive-keyring.gpg] https://download.docker.com/linux/debian $(lsb_release -cs) stable" > /etc/apt/sources.list.d/docker.list \
1717
&& apt-get update \
18-
&& apt-get -y install --no-install-recommends bash-completion lsb-release graphviz zip nodejs npm python3-pip docker-ce-cli docker-compose-plugin gnuplot\
18+
&& apt-get -y install --no-install-recommends bash-completion lsb-release graphviz zip python3-pip docker-ce-cli docker-compose-plugin gnuplot\
1919
# install az-cli
2020
&& curl -sL https://aka.ms/InstallAzureCLIDeb | bash - \
2121
# Temporary fix to avoid regression in v2.77

‎.devcontainer/install-dependencies.sh‎

Lines changed: 77 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -205,8 +205,8 @@ go-install kustomize sigs.k8s.io/kustomize/kustomize/v4@v4.5.7
205205

206206
# for docs site
207207

208-
#doc# | hugo | v0.152.2 | https://gohugo.io/ |
209-
go-install hugo -tags extended github.com/gohugoio/hugo@v0.152.2
208+
#doc# | hugo | v0.166.0 | https://gohugo.io/ |
209+
go-install hugo -tags extended github.com/gohugoio/hugo@v0.166.0
210210

211211
#doc# | htmltest | latest | https://github.com/wjdp/htmltest (but see https://github.com/theunrepentantgeek/htmltest for our custom build )
212212
# Restore this to github.com/wjdp/htmltest@v?? once PR#215 is merged with the feature we need
@@ -313,12 +313,87 @@ if should-install "$TOOL_DEST/azwi"; then
313313
fi
314314

315315
# Ensure tooling for Hugo is available
316+
#doc# | Node.js | v24.21.0 | https://nodejs.org/ |
317+
node_version=v24.21.0
318+
if [[ -x "$TOOL_DEST/node" && -e "$TOOL_DEST/npm" ]]; then
319+
export PATH="$TOOL_DEST:$PATH"
320+
fi
321+
322+
install_node=false
323+
if [[ "$DEVCONTAINER" == true ]]; then
324+
install_node=true
325+
elif ! command -v node > /dev/null 2>&1 || ! command -v npm > /dev/null 2>&1; then
326+
install_node=true
327+
elif [[ $(node --version) =~ ^v([0-9]+)\. ]] && [[ ${BASH_REMATCH[1]} -lt 24 ]]; then
328+
install_node=true
329+
fi
330+
331+
if [[ "$install_node" == true ]]; then
332+
write-info "Installing Node.js"
333+
case "$os-$arch" in
334+
linux-amd64)
335+
node_platform=linux-x64
336+
;;
337+
linux-arm64)
338+
node_platform=linux-arm64
339+
;;
340+
darwin-amd64)
341+
node_platform=darwin-x64
342+
;;
343+
darwin-arm64)
344+
node_platform=darwin-arm64
345+
;;
346+
*)
347+
write-error "Node.js is not available for $os-$arch"
348+
exit 1
349+
;;
350+
esac
351+
352+
rm -rf "$TOOL_DEST/nodejs"
353+
mkdir -p "$TOOL_DEST/nodejs"
354+
curl -sL "https://nodejs.org/dist/${node_version}/node-${node_version}-${node_platform}.tar.gz" |
355+
tar xz --strip-components=1 -C "$TOOL_DEST/nodejs"
356+
ln -sf "$TOOL_DEST/nodejs/bin/node" "$TOOL_DEST/node"
357+
ln -sf "$TOOL_DEST/nodejs/bin/npm" "$TOOL_DEST/npm"
358+
ln -sf "$TOOL_DEST/nodejs/bin/npx" "$TOOL_DEST/npx"
359+
export PATH="$TOOL_DEST:$PATH"
360+
fi
361+
362+
#doc# | Dart Sass | v1.102.0 | https://sass-lang.com/dart-sass/ |
363+
write-verbose "Checking for $TOOL_DEST/sass"
364+
if should-install "$TOOL_DEST/sass"; then
365+
write-info "Installing Dart Sass"
366+
case "$os-$arch" in
367+
linux-amd64)
368+
sass_platform=linux-x64
369+
;;
370+
linux-arm64)
371+
sass_platform=linux-arm64
372+
;;
373+
darwin-amd64)
374+
sass_platform=macos-x64
375+
;;
376+
darwin-arm64)
377+
sass_platform=macos-arm64
378+
;;
379+
*)
380+
write-error "Dart Sass is not available for $os-$arch"
381+
exit 1
382+
;;
383+
esac
384+
385+
rm -rf "$TOOL_DEST/dart-sass"
386+
curl -sL "https://github.com/sass/dart-sass/releases/download/1.102.0/dart-sass-1.102.0-${sass_platform}.tar.gz" | tar xz -C "$TOOL_DEST"
387+
ln -sf "$TOOL_DEST/dart-sass/sass" "$TOOL_DEST/sass"
388+
fi
389+
316390
#doc# | PostCSS | latest | https://postcss.org/ |
317391
write-verbose "Checking for /usr/bin/postcss"
318392
if ! which postcss > /dev/null 2>&1; then
319393
write-info "Installing postcss"
320394
npm config set fund false --location=global
321395
npm install --global postcss postcss-cli autoprefixer
396+
ln -sf "$(npm prefix --global)/bin/postcss" "$TOOL_DEST/postcss"
322397
fi
323398

324399
if [ "$VERBOSE" == true ]; then

‎Taskfile.yml‎

Lines changed: 1 addition & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1404,11 +1404,9 @@ tasks:
14041404
deps:
14051405
- doc:frontmatter-check
14061406
cmds:
1407+
- npm ci --ignore-scripts
14071408
- hugo
14081409
- htmltest
1409-
env:
1410-
NODE_PATH:
1411-
sh: npm root -g
14121410

14131411
doc:render-diagrams:
14141412
desc: Render all GraphViz diagrams

‎docs/hugo/README.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,16 @@
11
# Docs
22

3-
The documentation site is generated by Hugo. To run Hugo locally, install it, then run:
4-
3+
The documentation site is generated by Hugo with the Docsy theme. From the repository root, start the development shell
4+
to install the required tooling:
5+
6+
```sh
7+
./dev.sh
8+
```
9+
10+
Then build and validate the site inside the shell:
11+
512
```sh
6-
hugo server
13+
task doc:build-site
714
```
815

916
Markdown files go under `/content/`, static files like images under `/static/`.

‎docs/hugo/config.toml‎

Lines changed: 12 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
baseURL = 'https://azure.github.io/azure-service-operator/'
2-
languageCode = 'en-us'
2+
locale = 'en-US'
33
title = 'Azure Service Operator'
44

55
# for API docs rendering
@@ -17,7 +17,7 @@ enableRobotsTXT = true
1717
enableGitInfo = false
1818

1919
# Comment out to enable taxonomies in Docsy
20-
disableKinds = ["taxonomy", "taxonomyTerm"]
20+
disableKinds = ["taxonomy"]
2121

2222
# Highlighting config
2323
pygmentsCodeFences = true
@@ -42,8 +42,13 @@ latexDashes = true
4242
# Image processing configuration.
4343
[imaging]
4444
resampleFilter = "CatmullRom"
45-
quality = 75
4645
anchor = "smart"
46+
[imaging.jpeg]
47+
quality = 75
48+
[imaging.webp]
49+
quality = 75
50+
[imaging.avif]
51+
quality = 75
4752

4853
[services]
4954
[services.googleAnalytics]
@@ -89,11 +94,8 @@ url_latest_version = "https://azure.github.io/azure-service-operator/"
8994
# Specify a value here if your content directory is not in your repo's root directory
9095
github_subdir = "docs/hugo"
9196

92-
# Enable Algolia DocSearch
93-
algolia_docsearch = false
94-
9597
# Enable Lunr.js offline search
96-
offlineSearch = false
98+
offlineSearch = true
9799

98100
# Enable syntax highlighting and copy buttons on code blocks with Prism
99101
prism_syntax_highlighting = false
@@ -102,8 +104,8 @@ prism_syntax_highlighting = false
102104
[params.ui]
103105
# Set to true to disable breadcrumb navigation.
104106
breadcrumb_disable = false
105-
# Set to true to disable the About link in the site footer
106-
footer_about_disable = false
107+
# Set to false to disable the About link in the site footer
108+
footer_about_enable = true
107109
# Set to false if you don't want to display a logo (/assets/icons/logo.svg) in the top navbar
108110
navbar_logo = true
109111
# Set to true if you don't want the top navbar to be translucent when over a `block/cover`, like on the homepage.
@@ -165,9 +167,7 @@ enable = false
165167

166168
[module]
167169
[[module.imports]]
168-
path = "github.com/google/docsy"
169-
[[module.imports]]
170-
path = "github.com/google/docsy/dependencies"
170+
path = "github.com/google/docsy/theme"
171171

172172
[params.mermaid]
173173
enable = true

‎docs/hugo/content/contributing/dependencies.md‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -15,15 +15,17 @@ If you prefer to install those dependencies manually (instead of using the `.dev
1515
| controller-gen | v0.19.0 | https://book.kubebuilder.io/reference/controller-gen |
1616
| conversion-gen | v0.34.1 | https://pkg.go.dev/k8s.io/code-generator/cmd/conversion-gen |
1717
| crddoc | latest | https://github.com/theunrepentantgeek/crddoc |
18+
| Dart Sass | v1.102.0 | https://sass-lang.com/dart-sass/ |
1819
| Go | 1.25 | https://golang.org/doc/install #
1920
| go-vcr-tidy | latest | https://github.com/theunrepentantgeek/go-vcr-tidy |
2021
| gofumpt | v0.10.0 | https://github.com/mvdan/gofumpt |
2122
| golangci-lint | 2.12.1 | https://github.com/golangci/golangci-lint |
2223
| Helm | v3.19.0 | https://helm.sh/ |
2324
| htmltest | latest | https://github.com/wjdp/htmltest (but see https://github.com/theunrepentantgeek/htmltest for our custom build )
24-
| hugo | v0.152.2 | https://gohugo.io/ |
25+
| hugo | v0.166.0 | https://gohugo.io/ |
2526
| kind | v0.31.0 | https://kind.sigs.k8s.io/ |
2627
| kustomize | v4.5.7 | https://kustomize.io/ |
28+
| Node.js | v24.21.0 | https://nodejs.org/ |
2729
| Pip3 | latest | https://pip.pypa.io/en/stable/installation/ |
2830
| PostCSS | latest | https://postcss.org/ |
2931
| setup-envtest | v0.23.1 | https://book.kubebuilder.io/reference/envtest.html |

docs/hugo/content/design/ADR-2026-04-Secrets/_index.html renamed to docs/hugo/content/design/ADR-2026-04-Secrets/_index.md

File renamed without changes.

‎docs/hugo/go.mod‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,6 +3,5 @@ module github.com/azure/azure-service-operator/docs/hugo
33
go 1.20
44

55
require (
6-
github.com/google/docsy v0.11.1-0.20250428233416-f4ea6a1ebdef // indirect
7-
github.com/google/docsy/dependencies v0.7.2 // indirect
6+
github.com/google/docsy/theme v0.17.0 // indirect
87
)

‎docs/hugo/go.sum‎

Lines changed: 2 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,20 +1,2 @@
1-
github.com/FortAwesome/Font-Awesome v0.0.0-20220831210243-d3a7818c253f/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
2-
github.com/FortAwesome/Font-Awesome v0.0.0-20230327165841-0698449d50f2/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
3-
github.com/FortAwesome/Font-Awesome v0.0.0-20240402185447-c0f460dca7f7/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
4-
github.com/FortAwesome/Font-Awesome v0.0.0-20240716171331-37eff7fa00de/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
5-
github.com/FortAwesome/Font-Awesome v0.0.0-20241216213156-af620534bfc3/go.mod h1:IUgezN/MFpCDIlFezw3L8j83oeiIuYoj28Miwr/KUYo=
6-
github.com/google/docsy v0.6.0 h1:43bVF18t2JihAamelQjjGzx1vO2ljCilVrBgetCA8oI=
7-
github.com/google/docsy v0.6.0/go.mod h1:VKKLqD8PQ7AglJc98yBorATfW7GrNVsn0kGXVYF6G+M=
8-
github.com/google/docsy v0.10.0 h1:6tMDacPwAyRWNCfvsn/9qGOZDQ8b0aRzjRZvnZPY5dg=
9-
github.com/google/docsy v0.10.0/go.mod h1:c0nIAqmRTOuJ01F85U/wJPQtc3Zj9N58Kea9bOT2AJc=
10-
github.com/google/docsy v0.11.0 h1:QnV40cc28QwS++kP9qINtrIv4hlASruhC/K3FqkHAmM=
11-
github.com/google/docsy v0.11.0/go.mod h1:hGGW0OjNuG5ZbH5JRtALY3yvN8ybbEP/v2iaK4bwOUI=
12-
github.com/google/docsy v0.11.1-0.20250428233416-f4ea6a1ebdef h1:FVx7GCZFsd/88/dzoUj/P/RuB6DoBPyFcWXRDnFvGCI=
13-
github.com/google/docsy v0.11.1-0.20250428233416-f4ea6a1ebdef/go.mod h1:jafNHER7YZwS1P24oXqemNBfGLXbGmcXX0HTQIip/N4=
14-
github.com/google/docsy/dependencies v0.6.0/go.mod h1:EDGc2znMbGUw0RW5kWwy2oGgLt0iVXBmoq4UOqstuNE=
15-
github.com/google/docsy/dependencies v0.7.2 h1:+t5ufoADQAj4XneFphz4A+UU0ICAxmNaRHVWtMYXPSI=
16-
github.com/google/docsy/dependencies v0.7.2/go.mod h1:gihhs5gmgeO+wuoay4FwOzob+jYJVyQbNaQOh788lD4=
17-
github.com/twbs/bootstrap v4.6.2+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
18-
github.com/twbs/bootstrap v5.2.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
19-
github.com/twbs/bootstrap v5.3.3+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
20-
github.com/twbs/bootstrap v5.3.5+incompatible/go.mod h1:fZTSrkpSf0/HkL0IIJzvVspTt1r9zuf7XlZau8kpcY0=
1+
github.com/google/docsy/theme v0.17.0 h1:eQaQcvg20bxI21nKylsERCK/xkCITj0Sqf3ae/NDRdo=
2+
github.com/google/docsy/theme v0.17.0/go.mod h1:NX/JqXCbZBn9Q2Hj7ez9Xeh9z4XcLiwmDYZXhB4RhRM=

‎docs/hugo/package-lock.json‎

Lines changed: 64 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)