diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml new file mode 100644 index 0000000..81a630f --- /dev/null +++ b/.github/workflows/docs.yml @@ -0,0 +1,81 @@ +name: Docs + +# Builds the documentation site and publishes it to GitHub Pages. +# +# Replaces static.yml, which uploaded the entire repository as the site. That +# published the Makefile, codemeta.json, deno.json, page.tmpl and everything +# else in the root -- all of them fetchable from software.library.caltech.edu +# today -- and it served whatever HTML happened to be committed rather than +# rendering the Markdown. +# +# The build itself lives in caltechlibrary/workflows, so a fix there reaches +# this site -- and every other Caltech Library site -- on the next run, with +# nothing written back into this repository. +# +# This calls the build action rather than the docs-pandoc.yml reusable +# workflow, because the site publishes compiled component bundles and a +# reusable workflow gives the caller nowhere to add a Deno setup step. +# +# The Pandoc Lua filters come from the shared repository; both are identical to +# the copies that used to live in this root. + +on: + push: + branches: [main] + pull_request: + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: pages + cancel-in-progress: false + +jobs: + build: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 + + - uses: denoland/setup-deno@v2 + with: + deno-version: v2.x + + - name: Bundle components + run: deno task build + + - uses: caltechlibrary/workflows/.github/actions/build-pandoc@v1 + with: + docs-dir: docs + # Markdown in the root is published too. cmt writes README.md and + # INSTALL.md there and can only write to the root. + extra-sources: "*.md" + template: pandoc/page.tmpl + include: | + dist/*.js + mod.js + LICENSE + css + src + + # Pagefind is pinned in the shared action. 1.5.2 is current; the + # accessibility improvements in 1.5.0 come from its new Component UI, + # which is a separate migration and does not require a version change. + - uses: caltechlibrary/workflows/.github/actions/index-site@v1 + + - uses: caltechlibrary/workflows/.github/actions/deploy-site@v1 + + deploy: + needs: build + # Pull requests build but do not publish. + if: github.event_name != 'pull_request' + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + steps: + - id: deployment + uses: actions/deploy-pages@v5 diff --git a/.github/workflows/static.yml b/.github/workflows/static.yml deleted file mode 100644 index 460f782..0000000 --- a/.github/workflows/static.yml +++ /dev/null @@ -1,43 +0,0 @@ -# Simple workflow for deploying static content to GitHub Pages -name: Deploy static content to Pages - -on: - # Runs on pushes targeting the default branch - push: - branches: ["main"] - - # Allows you to run this workflow manually from the Actions tab - workflow_dispatch: - -# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages -permissions: - contents: read - pages: write - id-token: write - -# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. -# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. -concurrency: - group: "pages" - cancel-in-progress: false - -jobs: - # Single deploy job since we're just deploying - deploy: - environment: - name: github-pages - url: ${{ steps.deployment.outputs.page_url }} - runs-on: ubuntu-latest - steps: - - name: Checkout - uses: actions/checkout@v4 - - name: Setup Pages - uses: actions/configure-pages@v5 - - name: Upload artifact - uses: actions/upload-pages-artifact@v3 - with: - # Upload entire repository - path: '.' - - name: Deploy to GitHub Pages - id: deployment - uses: actions/deploy-pages@v5 diff --git a/.gitignore b/.gitignore index 7d4560c..0f8a8f1 100644 --- a/.gitignore +++ b/.gitignore @@ -9,6 +9,9 @@ bin/ dist/ scratch/ +# The site is assembled by CI and uploaded as an artifact, never committed. +/_site/ + # macOS system files .DS_Store diff --git a/add-col-scope.lua b/add-col-scope.lua deleted file mode 100644 index f3eb08e..0000000 --- a/add-col-scope.lua +++ /dev/null @@ -1,9 +0,0 @@ --- add-col-scope.lua adds a scope="col" to table header elements -function Table(tbl) - for _, head in ipairs(tbl.head.rows) do - for _, cell in ipairs(head.cells) do - cell.attr.attributes["scope"] = "col" - end - end - return tbl -end diff --git a/deno.json b/deno.json index 6c2e795..e73060a 100644 --- a/deno.json +++ b/deno.json @@ -1,6 +1,6 @@ { "tasks": { - "build": "deno bundle --platform browser --outdir=./ src/*.js ; deno bundle --platform browser mod.js --output=cl-web-components.js", + "build": "deno bundle --platform browser --outdir=./dist src/*.js ; deno bundle --platform browser --output=dist/cl-web-components.js mod.js", "release": "deno bundle --platform=browser --outdir=./dist src/*.js ; deno bundle --platform=browser --output=dist/cl-web-components.js mod.js" }, "imports": { diff --git a/DEPLOYMENT.md b/docs/DEPLOYMENT.md similarity index 74% rename from DEPLOYMENT.md rename to docs/DEPLOYMENT.md index 3d63e91..5f7f20c 100644 --- a/DEPLOYMENT.md +++ b/docs/DEPLOYMENT.md @@ -25,54 +25,42 @@ This file is included in gitignore and is **not committed to git**. Use this workflow when **only documentation (`.md`) files have changed**. -## Step 1. Convert mardown files to html files +## Step 1. Edit and push -```bash -make website -``` - -This command: - -- Converts all `*.md` files to `*.html` using **Pandoc** -- Rebuilds the **Pagefind search index** - -## Step 2. Save and push your working branch - -If you added **new files**, stage them first: +Documentation sources live in `docs/`. Edit the Markdown, then commit and push: ```bash git add +git commit -m "your commit message" +git push ``` -Then commit and push: +There is no HTML to build by hand. The **Docs** workflow renders the site with +Pandoc and publishes it to GitHub Pages on every push to `main`. The build +lives in [caltechlibrary/workflows](https://github.com/caltechlibrary/workflows), +so a fix there reaches this site on the next run. The Pandoc template is this +repository's own, in `pandoc/`; the Lua filters come from the shared repository. -```bash -make save msg="your commit message" -``` - -`make save` uses `git commit -am` which only commits already-tracked files. New files must be staged with `git add` first. - -## Step 3. Publish html files to GitHub Pages +## Step 2. Confirm the deployment ```bash -./publish.bash +gh run watch ``` -This script will prompt you: +The site updates at +when the workflow completes. Pull requests build the site but do not publish +it, so a change that breaks the docs fails in review rather than after merge. -``` -You're in main branch -You need to pull in changes to the gh-pages branch to publish -process Y/n -``` +### Previewing locally -Enter `y` to proceed. +Clone the shared repository once and put its `bin/` on your `PATH`, then: -It will: +```bash +build-pandoc.sh --docs-dir docs --extra-source "*.md" --template pandoc/page.tmpl +open _site/index.html +``` -- Merge your current branch into `gh-pages` -- Push the update to GitHub Pages -- Switch you back to your working branch +That is the same script CI runs. --- @@ -101,12 +89,6 @@ This command runs `deno task build` and bundles: This shows which files will be uploaded without making changes. -## Step 3. Build the documentation website - -```bash -make website -``` - ## Step 4. Save and push your working branch If you added **new files**, stage them first: @@ -135,21 +117,7 @@ This script: - Places them under `/cl-webcomponents/` in the S3 bucket - Creates a **CloudFront cache invalidation** so the CDN serves the new files -## Step 6. Publish html files to GitHub Pages - -```bash -./publish.bash -``` - -This script will prompt you: - -``` -You're in main branch -You need to pull in changes to the gh-pages branch to publish -process Y/n -``` - -Enter `y` to proceed. +The documentation site redeploys on its own when the push lands on `main`. --- @@ -241,9 +209,8 @@ https://github.com/caltechlibrary/CL-web-components/releases | Task | Command | |-----|---------| | Compile source code | `make build` | -| Build documentation website | `make website` | | Save and push working branch | `make save msg="your message"` | -| Publish docs to GitHub Pages | `./publish.bash` | +| Deploy the docs site | Automatic on push to `main` | | Preview S3 deployment | `./publish_to_s3.bash dry-run` | | Deploy JS to S3 and invalidate CDN cache | `./publish_to_s3.bash` | | Invalidate CDN cache only | `./invalidate_cdn.bash` | diff --git a/DEVELOPERS.md b/docs/DEVELOPERS.md similarity index 100% rename from DEVELOPERS.md rename to docs/DEVELOPERS.md diff --git a/building_web_components_with_deno.md b/docs/building_web_components_with_deno.md similarity index 100% rename from building_web_components_with_deno.md rename to docs/building_web_components_with_deno.md diff --git a/card-layout.md b/docs/card-layout.md similarity index 100% rename from card-layout.md rename to docs/card-layout.md diff --git a/demo_a-to-z-list_long.html b/docs/demo_a-to-z-list_long.html similarity index 100% rename from demo_a-to-z-list_long.html rename to docs/demo_a-to-z-list_long.html diff --git a/demo_a-to-z-list_multiple.html b/docs/demo_a-to-z-list_multiple.html similarity index 100% rename from demo_a-to-z-list_multiple.html rename to docs/demo_a-to-z-list_multiple.html diff --git a/demo_a-to-z-list_short.html b/docs/demo_a-to-z-list_short.html similarity index 100% rename from demo_a-to-z-list_short.html rename to docs/demo_a-to-z-list_short.html diff --git a/demo_agent-list.html b/docs/demo_agent-list.html similarity index 100% rename from demo_agent-list.html rename to docs/demo_agent-list.html diff --git a/demo_card-layout.html b/docs/demo_card-layout.html similarity index 100% rename from demo_card-layout.html rename to docs/demo_card-layout.html diff --git a/demo_csv0.html b/docs/demo_csv0.html similarity index 100% rename from demo_csv0.html rename to docs/demo_csv0.html diff --git a/demo_csv1.html b/docs/demo_csv1.html similarity index 100% rename from demo_csv1.html rename to docs/demo_csv1.html diff --git a/demo_csv2.html b/docs/demo_csv2.html similarity index 100% rename from demo_csv2.html rename to docs/demo_csv2.html diff --git a/demo_csv3.html b/docs/demo_csv3.html similarity index 100% rename from demo_csv3.html rename to docs/demo_csv3.html diff --git a/demo_csv4.html b/docs/demo_csv4.html similarity index 100% rename from demo_csv4.html rename to docs/demo_csv4.html diff --git a/demo_csv5.html b/docs/demo_csv5.html similarity index 100% rename from demo_csv5.html rename to docs/demo_csv5.html diff --git a/demo_csv_autocomplete0.html b/docs/demo_csv_autocomplete0.html similarity index 100% rename from demo_csv_autocomplete0.html rename to docs/demo_csv_autocomplete0.html diff --git a/demo_csv_autocomplete1.html b/docs/demo_csv_autocomplete1.html similarity index 100% rename from demo_csv_autocomplete1.html rename to docs/demo_csv_autocomplete1.html diff --git a/demo_csv_basic.html b/docs/demo_csv_basic.html similarity index 100% rename from demo_csv_basic.html rename to docs/demo_csv_basic.html diff --git a/demo_csv_customCleanupFilter.html b/docs/demo_csv_customCleanupFilter.html similarity index 100% rename from demo_csv_customCleanupFilter.html rename to docs/demo_csv_customCleanupFilter.html diff --git a/demo_csv_submit.html b/docs/demo_csv_submit.html similarity index 100% rename from demo_csv_submit.html rename to docs/demo_csv_submit.html diff --git a/demo_footer_global.html b/docs/demo_footer_global.html similarity index 100% rename from demo_footer_global.html rename to docs/demo_footer_global.html diff --git a/demo_footer_global_lite.html b/docs/demo_footer_global_lite.html similarity index 100% rename from demo_footer_global_lite.html rename to docs/demo_footer_global_lite.html diff --git a/demo_organization_list.html b/docs/demo_organization_list.html similarity index 100% rename from demo_organization_list.html rename to docs/demo_organization_list.html diff --git a/demo_people_list.html b/docs/demo_people_list.html similarity index 100% rename from demo_people_list.html rename to docs/demo_people_list.html diff --git a/demo_table-sortable.html b/docs/demo_table-sortable.html similarity index 100% rename from demo_table-sortable.html rename to docs/demo_table-sortable.html diff --git a/enhance_code_blocks.md b/docs/enhance_code_blocks.md similarity index 100% rename from enhance_code_blocks.md rename to docs/enhance_code_blocks.md diff --git a/footer-global.md b/docs/footer-global.md similarity index 100% rename from footer-global.md rename to docs/footer-global.md diff --git a/integrating_CSS_in_web_components.md b/docs/integrating_CSS_in_web_components.md similarity index 100% rename from integrating_CSS_in_web_components.md rename to docs/integrating_CSS_in_web_components.md diff --git a/docs/search.md b/docs/search.md new file mode 100644 index 0000000..e398413 --- /dev/null +++ b/docs/search.md @@ -0,0 +1,30 @@ + + +# CL-web-components + + + + + diff --git a/table-sortable.md b/docs/table-sortable.md similarity index 100% rename from table-sortable.md rename to docs/table-sortable.md diff --git a/textarea-agent-list-test.html b/docs/textarea-agent-list-test.html similarity index 100% rename from textarea-agent-list-test.html rename to docs/textarea-agent-list-test.html diff --git a/textarea-agent-list.md b/docs/textarea-agent-list.md similarity index 100% rename from textarea-agent-list.md rename to docs/textarea-agent-list.md diff --git a/textarea-csv.md b/docs/textarea-csv.md similarity index 100% rename from textarea-csv.md rename to docs/textarea-csv.md diff --git a/textarea-csv_test.html b/docs/textarea-csv_test.html similarity index 100% rename from textarea-csv_test.html rename to docs/textarea-csv_test.html diff --git a/ul-a-to-z-list.md b/docs/ul-a-to-z-list.md similarity index 100% rename from ul-a-to-z-list.md rename to docs/ul-a-to-z-list.md diff --git a/user_manual.md b/docs/user_manual.md similarity index 100% rename from user_manual.md rename to docs/user_manual.md diff --git a/web_component_naming.md b/docs/web_component_naming.md similarity index 100% rename from web_component_naming.md rename to docs/web_component_naming.md diff --git a/links-to-html.lua b/links-to-html.lua deleted file mode 100644 index 935304b..0000000 --- a/links-to-html.lua +++ /dev/null @@ -1,6 +0,0 @@ --- links-to-html.lua converts links to local Markdown documents to --- there respective .html counterparts. -function Link(el) - el.target = string.gsub(el.target, "%.md", ".html") - return el -end diff --git a/page.tmpl b/pandoc/page.tmpl similarity index 95% rename from page.tmpl rename to pandoc/page.tmpl index 5d2c971..0e39f29 100644 --- a/page.tmpl +++ b/pandoc/page.tmpl @@ -21,7 +21,7 @@
  • DEPLOYMENT
  • User Manual
    • - +
  • Search
  • Code Repository
    • diff --git a/website.mak b/website.mak deleted file mode 100644 index 8f2845a..0000000 --- a/website.mak +++ /dev/null @@ -1,27 +0,0 @@ - -# generated with CMTools 0.0.15 50d2dd2 - -# -# Makefile for running pandoc on all Markdown docs ending in .md -# -PROJECT = CL-web-components - -PANDOC = $(shell which pandoc) - -MD_PAGES = $(shell ls -1 *.md) - -HTML_PAGES = $(shell ls -1 *.md | sed -E 's/\.md/\.html/g') - -build: $(HTML_PAGES) $(MD_PAGES) - -$(HTML_PAGES): $(MD_PAGES) .FORCE - if [ -f $(PANDOC) ]; then $(PANDOC) --metadata title=$(basename $@) -s --to html5 $(basename $@).md -o $(basename $@).html \ - --lua-filter=links-to-html.lua \ - --lua-filter=add-col-scope.lua \ - --template=page.tmpl; fi - @if [ $@ = "README.html" ]; then mv README.html index.html; fi - -clean: - @rm *.html - -.FORCE: diff --git a/website.ps1 b/website.ps1 deleted file mode 100644 index af07829..0000000 --- a/website.ps1 +++ /dev/null @@ -1,37 +0,0 @@ -<# -generated with CMTools 0.0.15 50d2dd2 - -.SYNOPSIS -PowerShell script for running pandoc on all Markdown docs ending in .md -#> -$project = "CMTools" -Write-Output "Building website for ${project}" -$pandoc = Get-Command pandoc | Select-Object -ExpandProperty Source - -# Get all markdown files except 'nav.md' -$mdPages = Get-ChildItem -Filter *.md | Where-Object { $_.Name -ne "nav.md" } - -# Generate HTML page names from markdown files -$htmlPages = $mdPages | ForEach-Object { [System.IO.Path]::ChangeExtension($_.Name, ".html") } - -function Build-HtmlPage { - param($htmlPages, $mdPages) - - foreach ($htmlPage in $htmlPages) { - $mdPage = [System.IO.Path]::ChangeExtension($htmlPage, ".md") - if (Test-Path $pandoc) { - & $pandoc "--metadata" "title=$($htmlPage.Replace('.html', ''))" "-s" "--to" "html5" $mdPage "-o" $htmlPage ` - "--lua-filter=links-to-html.lua" ` - "--lua-filter=add-col-scope.lua" ` - "--template=page.tmpl" - } - - if ($htmlPage -eq "README.html") { - Move-Item -Path "README.html" -Destination "index.html" -Force - } - } -} - -# Build HTML page -Build-HtmlPage -htmlPages $htmlPages -mdPages $mdPages -