ci(github/workflows/docs): deploy GitHub Pages site

Deploy the GitHub Pages site by uploading the `result/usr/share/doc` directory after running `nix build .#docs` in a GitHub Action. Due to GitHub limitations, the `docs` package generates a `result/usr/share/doc/index.html` file redirecting to the documentation entry point at `result/usr/share/doc/docs/index.html`: > If your publishing source is a GitHub Actions workflow, the artifact > that you deploy must include the entry file at the top level of the > artifact. > > (Source: https://docs.github.com/en/pages/getting-started-with-github-pages) References: - https://docs.github.com/en/pages/getting-started-with-github-pages/creating-a-github-pages-site#creating-your-site - https://github.com/danth/stylix/blob/fcff15ac5ffbe81f1c66e352f3167c270d79cdab/.github/workflows/docs.yml - https://github.com/nix-community/nixvim/blob/8b500ef1db8c65ebb94b31434146e00efe4e8b9f/.github/workflows/build_documentation.yml
trueNAHO · Mar 14, 2024 · f0e3554 · f0e3554
1 parent 250aaf7
commit f0e3554
Show file tree

Hide file tree

Showing 2 changed files with 57 additions and 1 deletion.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -0,0 +1,36 @@
+---
+name: Docs
+
+on:
+  push:
+    branches:
+      - master
+
+permissions:
+  contents: read
+  id-token: write
+  pages: write
+
+concurrency:
+  cancel-in-progress: true
+  group: "pages"
+
+jobs:
+  docs:
+    runs-on: ubuntu-22.04
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: DeterminateSystems/nix-installer-action@v9
+      - uses: DeterminateSystems/magic-nix-cache-action@v3
+      - run: nix build .#docs
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: result/usr/share/doc
+
+      - uses: actions/deploy-pages@v4
diff --git a/flake.nix b/flake.nix
@@ -134,12 +134,32 @@
           out = "${placeholder "out"}/usr/share/doc";
         in
           pkgs.stdenv.mkDerivation {
-            buildPhase = ''
+            buildPhase = let
+              redirectURL = "docs/index.html";
+            in ''
               asciidoctor-multipage \
                 --attribute attribute-missing=warn \
                 --destination-dir "${out}/docs" \
                 --failure-level INFO \
                 docs/index.adoc
+
+              cat >"${out}/index.html" <<EOF
+              <!DOCTYPE html>
+              <html>
+
+              <head>
+                  <meta http-equiv="refresh" content="0; url=${redirectURL}">
+              </head>
+
+              <body>
+                  <p>
+                      If you are not redirected automatically,
+                      <a href="${redirectURL}">click here</a>.
+                  </p>
+              </body>
+
+              </html>
+              EOF
             '';
 
             installPhase = let