From c83e0f5525883afaf5f02f24d5327918302429a8 Mon Sep 17 00:00:00 2001 From: Adrian Date: Wed, 17 Sep 2025 16:40:55 -0600 Subject: [PATCH 1/3] add GitHub Pages deployment guide --- README.md | 1 + guides/deploying-to-github-pages.md | 129 ++++++++++++++++++++++++++++ mix.exs | 7 ++ 3 files changed, 137 insertions(+) create mode 100644 guides/deploying-to-github-pages.md diff --git a/README.md b/README.md index 50ac352..5c4630f 100644 --- a/README.md +++ b/README.md @@ -61,6 +61,7 @@ Documentation can be found at . | Site | Template | Styling | Template | Source | |------------------------------------------------------------|-------------------------------------------------------------------------------|------------|----------|-----------------------------------------------------------------------------------| +| [acrogenesis.com](https://acrogenesis.com) | [HEEx](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#sigil_H/2) | CSS | | [acrogenesis/acrogenesis.com](https://github.com/acrogenesis/acrogenesis.com) | | [www.elixir-tools.dev](https://www.elixir-tools.dev) | [Temple](https://github.com/mhanberg/temple) | Tailwind | | [elixir-tools/elixir-tools.dev](https://github.com/elixir-tools/elixir-tools.dev) | | [www.mitchellhanberg.com](https://www.mitchellhanberg.com) | [Temple](https://github.com/mhanberg/temple) | Tailwind | | [mhanberg/blog](https://github.com/mhanberg/blog) | | [pdx.su](https://pdx.su) | [Temple](https://github.com/mhanberg/temple) | CSS | | [paradox460/pdx.su](https://github.com/paradox460/pdx.su) | diff --git a/guides/deploying-to-github-pages.md b/guides/deploying-to-github-pages.md new file mode 100644 index 00000000..06c8927 --- /dev/null +++ b/guides/deploying-to-github-pages.md @@ -0,0 +1,129 @@ +# Deploying to GitHub Pages + +GitHub Pages can host the static files that Tableau produces. This guide walks through a production-ready setup that you can adopt for your own site. + +## 1. Prepare your Tableau project + +1. Ensure your project exposes a `build` alias that calls `tableau.build`. The generator already includes this: + + ```elixir + # mix.exs + defp aliases do + [ + build: ["tableau.build"] + ] + end + ``` + +2. Make sure `_site/` is gitignored. Tableau writes the built site there and your workflow will upload it as an artifact: + + ```gitignore + /_site/ + ``` + +3. Configure your production URL in `config/prod.exs`. If you use a custom domain, set it to that value: + + ```elixir + # config/prod.exs + config :tableau, :config, + url: "https://your-domain.tld" + ``` + + For GitHub Pages sites served from `.github.io/`, use the full Pages URL and optionally set `base_path: "/"` so links render correctly locally. + +4. If you serve additional assets (Tailwind, esbuild, etc.), add the corresponding Mix tasks to the `build` alias so they also run in CI. + +## 2. Add the GitHub Pages workflow + +Create `.github/workflows/deploy.yml` with the following workflow. It installs Erlang/OTP + Elixir, builds the site in production mode, and publishes the `_site` directory to GitHub Pages: + +```yaml +name: Deploy site to GitHub Pages + +on: + push: + branches: [main] + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: true + +jobs: + build: + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Set up Erlang/OTP and Elixir + uses: erlef/setup-beam@v1 + with: + otp-version: "28" + elixir-version: "1.18" + + - name: Cache Mix deps + uses: actions/cache@v4 + with: + path: | + ~/.mix + deps + _build + key: ${{ runner.os }}-mix-${{ hashFiles('**/mix.lock') }} + restore-keys: | + ${{ runner.os }}-mix- + + - name: Install dependencies + run: MIX_ENV=prod mix deps.get --only prod + + - name: Build site + run: MIX_ENV=prod mix build + + - name: Upload artifact + uses: actions/upload-pages-artifact@v4 + with: + path: _site + + deploy: + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest + needs: build + steps: + - id: deployment + uses: actions/deploy-pages@v4 +``` + +### Workflow notes + +- Set `otp-version` and `elixir-version` to match your project. +- If `mix build` already chains your asset pipelines, no other changes are needed. Otherwise, insert additional steps before "Upload artifact". +- The cache step speeds up successive runs but can be removed if you prefer. + +## 3. Enable GitHub Pages + +1. Push the workflow to your default branch (the example uses `main`). +2. In your repository, open **Settings → Pages**. +3. Under **Build and deployment**, choose **GitHub Actions**. +4. After the first successful run, the deployment will appear under the **Deployments** tab and the workflow output prints the public URL. + +## 4. Using a custom domain + +If you have a custom domain: + +- Add a `CNAME` file at the repo root containing the domain, e.g. `example.com`. +- Configure your DNS to point at GitHub Pages. +- Keep `config :tableau, :config, url: "https://your-domain"` in sync so absolute links are generated correctly. + +## Troubleshooting + +- See a 404 for nested routes? Double-check `base_path` in `config/prod.exs` when deploying under a subdirectory. +- Need to rebuild assets? Append those build steps to the `build` alias so `mix build` runs everything locally and in CI. +- Want to test locally? Run `MIX_ENV=prod mix build` and inspect `_site/` before pushing. + +With these pieces in place, every push to `main` rebuilds your Tableau site and deploys it to GitHub Pages. diff --git a/mix.exs b/mix.exs index a298a43..a4c7a1e 100644 --- a/mix.exs +++ b/mix.exs @@ -67,6 +67,13 @@ defmodule Tableau.MixProject do defp docs do [ main: "Tableau", + extras: [ + "README.md", + "guides/deploying-to-github-pages.md" + ], + groups_for_extras: [ + Guides: ~r/guides\/[^\/]+\.md/ + ], groups_for_modules: [ Site: [ Tableau, From f45cf0cc8d0142c38a53febdaded31737d331fb1 Mon Sep 17 00:00:00 2001 From: Adrian Date: Wed, 17 Sep 2025 21:07:19 -0600 Subject: [PATCH 2/3] suggestions --- README.md | 2 +- guides/deploying-to-github-pages.md | 34 ++++++++--------------------- 2 files changed, 10 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 5c4630f..2c916ea 100644 --- a/README.md +++ b/README.md @@ -61,7 +61,6 @@ Documentation can be found at . | Site | Template | Styling | Template | Source | |------------------------------------------------------------|-------------------------------------------------------------------------------|------------|----------|-----------------------------------------------------------------------------------| -| [acrogenesis.com](https://acrogenesis.com) | [HEEx](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#sigil_H/2) | CSS | | [acrogenesis/acrogenesis.com](https://github.com/acrogenesis/acrogenesis.com) | | [www.elixir-tools.dev](https://www.elixir-tools.dev) | [Temple](https://github.com/mhanberg/temple) | Tailwind | | [elixir-tools/elixir-tools.dev](https://github.com/elixir-tools/elixir-tools.dev) | | [www.mitchellhanberg.com](https://www.mitchellhanberg.com) | [Temple](https://github.com/mhanberg/temple) | Tailwind | | [mhanberg/blog](https://github.com/mhanberg/blog) | | [pdx.su](https://pdx.su) | [Temple](https://github.com/mhanberg/temple) | CSS | | [paradox460/pdx.su](https://github.com/paradox460/pdx.su) | @@ -72,6 +71,7 @@ Documentation can be found at . | [joelkoch.dev](https://joelkoch.dev) | [HEEx](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#sigil_H/2) | Tailwind | | [joelpaulkoch/joelkoch.dev](https://github.com/joelpaulkoch/joelkoch.dev) | | [www.ethangunderson.com](https://www.ethangunderson.com/) | [HEEx](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#sigil_H/2) | Tailwind | | [ethangunderson/website](https://github.com/ethangunderson/website) | | [https://adrienanselme.com/](https://adrienanselme.com/) | [HEEx](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#sigil_H/2) | Tailwind | | [adanselm/adanselm.github.io](https://github.com/adanselm/adanselm.github.io) | +| [acrogenesis.com](https://acrogenesis.com) | [HEEx](https://hexdocs.pm/phoenix_live_view/Phoenix.Component.html#sigil_H/2) | CSS | | [acrogenesis/acrogenesis.com](https://github.com/acrogenesis/acrogenesis.com) | ## Getting Started diff --git a/guides/deploying-to-github-pages.md b/guides/deploying-to-github-pages.md index 06c8927..22d213d 100644 --- a/guides/deploying-to-github-pages.md +++ b/guides/deploying-to-github-pages.md @@ -2,26 +2,9 @@ GitHub Pages can host the static files that Tableau produces. This guide walks through a production-ready setup that you can adopt for your own site. -## 1. Prepare your Tableau project +## Prepare your Tableau project -1. Ensure your project exposes a `build` alias that calls `tableau.build`. The generator already includes this: - - ```elixir - # mix.exs - defp aliases do - [ - build: ["tableau.build"] - ] - end - ``` - -2. Make sure `_site/` is gitignored. Tableau writes the built site there and your workflow will upload it as an artifact: - - ```gitignore - /_site/ - ``` - -3. Configure your production URL in `config/prod.exs`. If you use a custom domain, set it to that value: +1. Configure your production URL in `config/prod.exs`. If you use a custom domain, set it to that value: ```elixir # config/prod.exs @@ -29,11 +12,9 @@ GitHub Pages can host the static files that Tableau produces. This guide walks t url: "https://your-domain.tld" ``` - For GitHub Pages sites served from `.github.io/`, use the full Pages URL and optionally set `base_path: "/"` so links render correctly locally. +2. If you serve additional assets (Tailwind, esbuild, etc.), add the corresponding Mix tasks to the `build` alias so they also run in CI. -4. If you serve additional assets (Tailwind, esbuild, etc.), add the corresponding Mix tasks to the `build` alias so they also run in CI. - -## 2. Add the GitHub Pages workflow +## Add the GitHub Pages workflow Create `.github/workflows/deploy.yml` with the following workflow. It installs Erlang/OTP + Elixir, builds the site in production mode, and publishes the `_site` directory to GitHub Pages: @@ -105,20 +86,23 @@ jobs: - If `mix build` already chains your asset pipelines, no other changes are needed. Otherwise, insert additional steps before "Upload artifact". - The cache step speeds up successive runs but can be removed if you prefer. -## 3. Enable GitHub Pages +## Enable GitHub Pages 1. Push the workflow to your default branch (the example uses `main`). 2. In your repository, open **Settings → Pages**. 3. Under **Build and deployment**, choose **GitHub Actions**. 4. After the first successful run, the deployment will appear under the **Deployments** tab and the workflow output prints the public URL. -## 4. Using a custom domain +## Custom domains & pages.io URLs If you have a custom domain: - Add a `CNAME` file at the repo root containing the domain, e.g. `example.com`. - Configure your DNS to point at GitHub Pages. - Keep `config :tableau, :config, url: "https://your-domain"` in sync so absolute links are generated correctly. +- GitHub’s docs cover the DNS details in depth: . + +If you deploy to `.github.io/`, use the full Pages URL (e.g. `https://username.github.io/my-site`) and optionally set `base_path: "/my-site"` in `config/prod.exs` so local links match production. ## Troubleshooting From bc272f915ed901c567942dc6ee99d8f6256cb6f0 Mon Sep 17 00:00:00 2001 From: Adrian Date: Thu, 18 Sep 2025 18:30:12 -0600 Subject: [PATCH 3/3] suggestions --- guides/deploying-to-github-pages.md | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/guides/deploying-to-github-pages.md b/guides/deploying-to-github-pages.md index 22d213d..b628236 100644 --- a/guides/deploying-to-github-pages.md +++ b/guides/deploying-to-github-pages.md @@ -4,7 +4,7 @@ GitHub Pages can host the static files that Tableau produces. This guide walks t ## Prepare your Tableau project -1. Configure your production URL in `config/prod.exs`. If you use a custom domain, set it to that value: +1. Set the production `url` in `config/prod.exs` (your custom domain or the full GitHub Pages URL): ```elixir # config/prod.exs @@ -54,9 +54,9 @@ jobs: ~/.mix deps _build - key: ${{ runner.os }}-mix-${{ hashFiles('**/mix.lock') }} + key: ${{ runner.os }}-otp-28-elixir-1.18-mix-${{ hashFiles('**/mix.lock') }} restore-keys: | - ${{ runner.os }}-mix- + ${{ runner.os }}-otp-28-elixir-1.18-mix- - name: Install dependencies run: MIX_ENV=prod mix deps.get --only prod @@ -83,6 +83,7 @@ jobs: ### Workflow notes - Set `otp-version` and `elixir-version` to match your project. +- Update the cache key when you bump OTP or Elixir so a fresh build occurs. - If `mix build` already chains your asset pipelines, no other changes are needed. Otherwise, insert additional steps before "Upload artifact". - The cache step speeds up successive runs but can be removed if you prefer. @@ -108,6 +109,6 @@ If you deploy to `.github.io/`, use the full Pages URL (e.g. `https: - See a 404 for nested routes? Double-check `base_path` in `config/prod.exs` when deploying under a subdirectory. - Need to rebuild assets? Append those build steps to the `build` alias so `mix build` runs everything locally and in CI. -- Want to test locally? Run `MIX_ENV=prod mix build` and inspect `_site/` before pushing. +- Want to test locally? Run `MIX_ENV=prod mix build` and inspect the output directory (which defaults to `_site/`) before pushing. With these pieces in place, every push to `main` rebuilds your Tableau site and deploys it to GitHub Pages.