From 38cc8152cfaceb4862e1a994f9d479bbb085289b Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 27 Aug 2026 12:24:58 -0400 Subject: [PATCH 1/7] Drop official Docker support: remove broken config, retire Docker docs --- Dockerfile | 10 --- docker-compose.yaml | 14 ---- docsy.dev/content/en/docs/contributing.md | 43 ---------- .../content/en/docs/get-started/_index.md | 5 +- .../en/docs/get-started/quickstart-docker.md | 80 ------------------- .../goldens/docs/get-started/index.md | 4 +- 6 files changed, 3 insertions(+), 153 deletions(-) delete mode 100644 Dockerfile delete mode 100644 docker-compose.yaml delete mode 100644 docsy.dev/content/en/docs/get-started/quickstart-docker.md diff --git a/Dockerfile b/Dockerfile deleted file mode 100644 index f5100785b3..0000000000 --- a/Dockerfile +++ /dev/null @@ -1,10 +0,0 @@ -FROM klakegg/hugo:0.111.3-ext-alpine as docsy-user-guide - -RUN apk update -RUN apk add git -COPY package.json /app/docsy/docsy.dev/ -WORKDIR /app/docsy/docsy.dev/ -RUN npm install --production=false -RUN git config --global --add safe.directory /app/docsy - -CMD ["serve", "--cleanDestinationDir", "--themesDir", "../..", "--baseURL", "http://localhost:1313/", "--buildDrafts", "--buildFuture", "--disableFastRender", "--ignoreCache", "--watch"] diff --git a/docker-compose.yaml b/docker-compose.yaml deleted file mode 100644 index 53f977d22a..0000000000 --- a/docker-compose.yaml +++ /dev/null @@ -1,14 +0,0 @@ -version: "3.3" - -services: - - site: - image: docsy/docsy.dev - build: - context: . - ports: - - "1313:1313" - user: "${DOCSY_USER}" - volumes: - - /app/docsy/docsy.dev/node_modules - - .:/app/docsy diff --git a/docsy.dev/content/en/docs/contributing.md b/docsy.dev/content/en/docs/contributing.md index ddc3c28087..a7e38e33c6 100644 --- a/docsy.dev/content/en/docs/contributing.md +++ b/docsy.dev/content/en/docs/contributing.md @@ -131,49 +131,6 @@ work: 1. Continue with the usual GitHub workflow to edit files, commit them, push the changes up to your fork, and create a pull request. -#### Preview your changes using a Docker container - -Docsy comes with `Dockerfile` and `docker-compose` files to run the server -locally with Docker, without installing any additional dependencies. - -- Using [Docker]: - 1. Build the Docker container: - - ```bash - docker build -t docsy/user-guide . - ``` - - 1. Run the container, mounting the repository as a shared volume: - - ```bash - docker run -it --user=$(id -u):$(id -g) -p 1313:1313 \ - -v $(pwd):/app/docsy -v /app/docsy/docsy.dev/node_modules \ - docsy/user-guide - ``` - -- Using [Docker Compose][docker-compose]: - 1. Build the container: - - ```bash - docker-compose build - ``` - - 1. Run the container: - - ```bash - DOCSY_USER=$(id -u):$(id -g) docker-compose up - ``` - -Open in your web browser to load the docsy user guide. -In most cases, docsy will automatically reload the site to reflect any changes -to the documentation or the code. Changes to some parts of the docsy code may -require manually reloading the page or re-starting the container. - -Press **Ctrl + C** to stop the container. - -[docker]: https://docs.docker.com/get-docker/ -[docker-compose]: https://docs.docker.com/compose/install/ - ### User guide formatting We use [Prettier](https://prettier.io) to format the markdown source of the User diff --git a/docsy.dev/content/en/docs/get-started/_index.md b/docsy.dev/content/en/docs/get-started/_index.md index 85536d25b0..6408c98ec6 100644 --- a/docsy.dev/content/en/docs/get-started/_index.md +++ b/docsy.dev/content/en/docs/get-started/_index.md @@ -4,7 +4,7 @@ description: >- Learn how to get started with Docsy, including the available options for installing and using the Docsy theme. date: 2018-07-30 -aliases: [getting-started] +aliases: [getting-started, /docs/get-started/quickstart-docker/] weight: 2 --- @@ -16,8 +16,7 @@ our example site, though we also provide instructions for adding the Docsy theme manually to new or existing sites. If you want to build and test your site locally you also need to be able to run -Hugo itself, either by installing it and any other required dependencies, or by -using our provided Docker container. +Hugo itself, by installing it and any other required dependencies. This page describes Docsy's installation options and helps you choose the appropriate setup guide to get started. diff --git a/docsy.dev/content/en/docs/get-started/quickstart-docker.md b/docsy.dev/content/en/docs/get-started/quickstart-docker.md deleted file mode 100644 index 992848a0c7..0000000000 --- a/docsy.dev/content/en/docs/get-started/quickstart-docker.md +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: Deploy Docsy inside a Docker container -weight: 3 -date: 2018-07-30 -description: > - Instructions on how to set up and run a local Docsy site with Docker. ---- - -We provide a Docker image that you can use to run and test your Docsy site -locally, without having to install all Docsy's dependencies. - -## Install the prerequisites - -1. On Mac and Windows, download and install - [Docker Desktop](https://www.docker.com/get-started). On Linux, install - [Docker engine](https://docs.docker.com/engine/install/) and - [Docker compose](https://docs.docker.com/compose/install/). - - The installation may require you to reboot your computer for the changes to - take effect. - -1. [Install git](https://github.com/git-guides/install-git). - -## Create your repository from the docsy-example template - -The docsy-example repository provides a basic site structure that you can use as -a starting point to create your own documentation. - -1. Use the [docsy-example template](https://github.com/google/docsy-example) to - [create your own repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/creating-a-repository-from-a-template). - -1. Download the code to your local machine by - [cloning your newly created repository](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository). - -1. Change your working directory to the newly created folder: - - ```bash - cd docsy-example - ``` - -## Build and run the container - -The docsy-example repository includes a -[Dockerfile](https://docs.docker.com/engine/reference/builder/) that you can use -to run your site. - -1. Build the docker image: - - ```bash - docker-compose build - ``` - -1. Run the built image: - - ```bash - docker-compose up - ``` - -1. Open the address `http://localhost:1313` in your web browser to load the - docsy-example homepage. You can now make changes to the source files, those - changes will be live-reloaded in your browser. - -## Cleanup - -To clean up your system and delete the container image, follow the next steps. - -1. Stop Docker Compose with **Ctrl + C**. - -1. Remove the produced images - - ```bash - docker-compose rm - ``` - -## What's next? - -- Learn about - [basic setup and configurations for Docsy](/docs/get-started/basic-configuration/). -- [Add content and customize your site](/docs/content/) -- [Publish your site](/docs/deployment/). diff --git a/docsy.dev/tests/md-output/goldens/docs/get-started/index.md b/docsy.dev/tests/md-output/goldens/docs/get-started/index.md index f833911bb1..5c3eda99c5 100644 --- a/docsy.dev/tests/md-output/goldens/docs/get-started/index.md +++ b/docsy.dev/tests/md-output/goldens/docs/get-started/index.md @@ -16,8 +16,7 @@ our example site, though we also provide instructions for adding the Docsy theme manually to new or existing sites. If you want to build and test your site locally you also need to be able to run -Hugo itself, either by installing it and any other required dependencies, or by -using our provided Docker container. +Hugo itself, by installing it and any other required dependencies. This page describes Docsy's installation options and helps you choose the appropriate setup guide to get started. @@ -71,6 +70,5 @@ Section pages: - [Use Docsy as a Hugo Module](/docs/get-started/docsy-as-module/): Learn how to get started with Docsy by using the theme as a Hugo Module. - [Other setup options](/docs/get-started/other-options/): Install Docsy as a Git submodule, a clone, or the @docsy/theme npm package, for sites not using Hugo modules. -- [Deploy Docsy inside a Docker container](/docs/get-started/quickstart-docker/): Instructions on how to set up and run a local Docsy site with Docker. - [Basic site configuration](/docs/get-started/basic-configuration/): Basic configuration for new Docsy sites. - [Troubleshooting and known issues](/docs/get-started/troubleshooting/): Troubleshooting and known issues when installing and using Docsy. From 0e2f2d79e7e8f99b7c5262da2c41fe3a6c2c7b9f Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 27 Aug 2026 12:26:58 -0400 Subject: [PATCH 2/7] Changelog: Docker-support drop --- docsy.dev/content/en/project/about/changelog.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docsy.dev/content/en/project/about/changelog.md b/docsy.dev/content/en/project/about/changelog.md index df59c4e2fe..763720c884 100644 --- a/docsy.dev/content/en/project/about/changelog.md +++ b/docsy.dev/content/en/project/about/changelog.md @@ -179,6 +179,9 @@ full list of changes, see the [0.17.0][] release page or the [git history since ([#2614][]). - Silenced Sass deprecation warnings in site builds, project style files included; see the [release report][0.17.0-blog-dart-sass] ([#2731][]). +- Dropped official Docker support: removed the broken `Dockerfile` and + `docker-compose.yaml` files and retired the Docker quickstart page + ([#2748][]). **For maintainers**: @@ -214,6 +217,7 @@ full list of changes, see the [0.17.0][] release page or the [git history since [#2724]: https://github.com/google/docsy/pull/2724 [#2726]: https://github.com/google/docsy/pull/2726 [#2731]: https://github.com/google/docsy/pull/2731 +[#2748]: https://github.com/google/docsy/pull/2748 [0.17.0 release report]: /blog/2026/0.17.0/ [0.17.0-blog-dart-sass]: /blog/2026/0.17.0/#dart-sass [0.17.0-blog-install]: /blog/2026/0.17.0/#install-command From e7b1c3fce92bd00329be1d8d1df0fefeced5ff07 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 27 Aug 2026 12:30:36 -0400 Subject: [PATCH 3/7] Update .lycheecache --- docsy.dev/.lycheecache | 1 + 1 file changed, 1 insertion(+) diff --git a/docsy.dev/.lycheecache b/docsy.dev/.lycheecache index bb50503f00..2ed9b625cb 100644 --- a/docsy.dev/.lycheecache +++ b/docsy.dev/.lycheecache @@ -539,6 +539,7 @@ https://github.com/google/docsy/pull/2722,200,1787153684 https://github.com/google/docsy/pull/2724,200,1787076569 https://github.com/google/docsy/pull/2726,200,1787137876 https://github.com/google/docsy/pull/2731,200,1787331617 +https://github.com/google/docsy/pull/2748,200,1787848215 https://github.com/google/docsy/pull/941,200,1782498225 https://github.com/google/docsy/pulls,200,1782563369 https://github.com/google/docsy/releases,200,1782563368 From 31adcb2ed86f3e2f961e3b3e4f4ad0d4b26d69f1 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 27 Aug 2026 12:42:46 -0400 Subject: [PATCH 4/7] Review: lean changelog entry; move script-dep words to workspace dictionary --- .vscode/cspell.json | 3 +++ docsy.dev/content/en/project/about/changelog.md | 7 +++---- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/.vscode/cspell.json b/.vscode/cspell.json index 7c606e5e3d..1077454c11 100644 --- a/.vscode/cspell.json +++ b/.vscode/cspell.json @@ -11,6 +11,7 @@ "words": [ "afdocs", "anchorize", + "autoloader", "basenames", "baseof", "chalin", @@ -39,11 +40,13 @@ "htmltest", "hugo", "isset", + "katex", "lastmod", "llms", "lockfiles", "magick", "markdownify", + "markmap", "mentees", "navbars", "nguyen", diff --git a/docsy.dev/content/en/project/about/changelog.md b/docsy.dev/content/en/project/about/changelog.md index 763720c884..34dad9b0e8 100644 --- a/docsy.dev/content/en/project/about/changelog.md +++ b/docsy.dev/content/en/project/about/changelog.md @@ -3,7 +3,7 @@ title: Changelog description: Docsy repository changelog aliases: [../changelog] # prettier-ignore -cSpell:ignore: deining FOUC gitmodules gtag katex lookandfeel mhchem navs notoc tabpane onedark shurup +cSpell:ignore: deining FOUC gitmodules gtag lookandfeel mhchem navs notoc tabpane onedark shurup --- We document **breaking changes** and release **highlights** in this page, with @@ -179,9 +179,8 @@ full list of changes, see the [0.17.0][] release page or the [git history since ([#2614][]). - Silenced Sass deprecation warnings in site builds, project style files included; see the [release report][0.17.0-blog-dart-sass] ([#2731][]). -- Dropped official Docker support: removed the broken `Dockerfile` and - `docker-compose.yaml` files and retired the Docker quickstart page - ([#2748][]). +- Dropped broken `Dockerfile` and `docker-compose.yaml` files and retired Docker + quickstart page ([#2748][]). **For maintainers**: From 465bd4860de697a0395af104751ac4af574baa50 Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 27 Aug 2026 12:44:05 -0400 Subject: [PATCH 5/7] Review: make quickstart-docker alias parent-relative --- docsy.dev/content/en/docs/get-started/_index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docsy.dev/content/en/docs/get-started/_index.md b/docsy.dev/content/en/docs/get-started/_index.md index 6408c98ec6..495144a6b5 100644 --- a/docsy.dev/content/en/docs/get-started/_index.md +++ b/docsy.dev/content/en/docs/get-started/_index.md @@ -4,7 +4,7 @@ description: >- Learn how to get started with Docsy, including the available options for installing and using the Docsy theme. date: 2018-07-30 -aliases: [getting-started, /docs/get-started/quickstart-docker/] +aliases: [getting-started, get-started/quickstart-docker] weight: 2 --- From 2e77ad68d453a49b440122cdc428b0b4cc6def0e Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 27 Aug 2026 12:54:46 -0400 Subject: [PATCH 6/7] Test: guard retired-URL alias redirects --- .../tests/md-output/retired-urls.test.mjs | 27 +++++++++++++++++++ 1 file changed, 27 insertions(+) create mode 100644 docsy.dev/tests/md-output/retired-urls.test.mjs diff --git a/docsy.dev/tests/md-output/retired-urls.test.mjs b/docsy.dev/tests/md-output/retired-urls.test.mjs new file mode 100644 index 0000000000..d540d89379 --- /dev/null +++ b/docsy.dev/tests/md-output/retired-urls.test.mjs @@ -0,0 +1,27 @@ +// Alias regression guard: retired URLs must keep resolving. Hugo emits the +// redirect pages only from front-matter `aliases`, and no other check reads +// them: the link check can't discover a retired URL (no inbound source link +// remains), so a dropped alias would otherwise pass green. + +import test from 'node:test'; +import assert from 'node:assert/strict'; +import { readFileSync } from 'node:fs'; + +const publicDir = new URL('../../public/', import.meta.url); + +// Retired page URL -> the path each alias page must redirect to. +const retired = { + 'docs/get-started/quickstart-docker/': '/docs/get-started/', + 'fr/docs/get-started/quickstart-docker/': '/fr/docs/get-started/', +}; + +for (const [url, target] of Object.entries(retired)) { + test(`retired URL /${url} redirects to ${target}`, () => { + const html = readFileSync(new URL(`${url}index.html`, publicDir), 'utf8'); + assert.match( + html, + new RegExp(`http-equiv="refresh" content="0; url=[^"]*${target}"`), + 'alias page carries a meta refresh to the target', + ); + }); +} From bdfdfd360de5dec670c09f7bada13bd03733232e Mon Sep 17 00:00:00 2001 From: Patrice Chalin Date: Thu, 27 Aug 2026 13:02:26 -0400 Subject: [PATCH 7/7] Revert "Test: guard retired-URL alias redirects" This reverts commit 2e77ad68d453a49b440122cdc428b0b4cc6def0e. --- .../tests/md-output/retired-urls.test.mjs | 27 ------------------- 1 file changed, 27 deletions(-) delete mode 100644 docsy.dev/tests/md-output/retired-urls.test.mjs diff --git a/docsy.dev/tests/md-output/retired-urls.test.mjs b/docsy.dev/tests/md-output/retired-urls.test.mjs deleted file mode 100644 index d540d89379..0000000000 --- a/docsy.dev/tests/md-output/retired-urls.test.mjs +++ /dev/null @@ -1,27 +0,0 @@ -// Alias regression guard: retired URLs must keep resolving. Hugo emits the -// redirect pages only from front-matter `aliases`, and no other check reads -// them: the link check can't discover a retired URL (no inbound source link -// remains), so a dropped alias would otherwise pass green. - -import test from 'node:test'; -import assert from 'node:assert/strict'; -import { readFileSync } from 'node:fs'; - -const publicDir = new URL('../../public/', import.meta.url); - -// Retired page URL -> the path each alias page must redirect to. -const retired = { - 'docs/get-started/quickstart-docker/': '/docs/get-started/', - 'fr/docs/get-started/quickstart-docker/': '/fr/docs/get-started/', -}; - -for (const [url, target] of Object.entries(retired)) { - test(`retired URL /${url} redirects to ${target}`, () => { - const html = readFileSync(new URL(`${url}index.html`, publicDir), 'utf8'); - assert.match( - html, - new RegExp(`http-equiv="refresh" content="0; url=[^"]*${target}"`), - 'alias page carries a meta refresh to the target', - ); - }); -}