Rebuild the website with Docusaurus

.asf.yaml

@@ -6,9 +6,9 @@ project:
     description: Apache STeVe is a collection of online voting tools, used by the ASF, to handle STV and other voting methods.
     short_description: STV Voting Tools
     homepage: https://steve.apache.org
-    download_page: https://steve.apache.org/downloads.html
+    download_page: https://steve.apache.org/downloads/
     bug_database: https://github.com/apache/steve/issues
-    mailing_lists: https://steve.apache.org/community.html
+    mailing_lists: https://steve.apache.org/community/
     repositories:
       - https://github.com/apache/steve.git
     categories:
@@ -39,7 +39,6 @@ staging:
   whoami: asf-staging
   autostage: site/*
 
-# We will publish our site using Pelican, via the asf-site branch
-pelican:
-  whoami: trunk
-  target: asf-site
+# GitHub Actions pushes the generated website to this branch.
+publish:
+  whoami: asf-site

.github/workflows/site-preview-cleanup.yml

@@ -0,0 +1,30 @@
+name: Remove website preview
+
+on:
+  pull_request:
+    types: [closed]
+
+permissions:
+  contents: write
+
+concurrency:
+  group: website-${{ github.event.pull_request.head.repo.full_name }}-refs/heads/${{ github.event.pull_request.head.ref }}
+  cancel-in-progress: true
+
+jobs:
+  cleanup:
+    if: github.event.pull_request.head.repo.full_name == github.repository && startsWith(github.event.pull_request.head.ref, 'preview/')
+    runs-on: ubuntu-latest
+    steps:
+      - name: Delete the generated preview branch
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_REPO: ${{ github.repository }}
+          SOURCE_BRANCH: ${{ github.event.pull_request.head.ref }}
+        run: |
+          name="${SOURCE_BRANCH#preview/}"
+          [[ "$name" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || exit 0
+          branch="site/${name}-staging"
+          if gh api "repos/$GH_REPO/git/ref/heads/$branch" --silent; then
+            gh api --method DELETE "repos/$GH_REPO/git/refs/heads/$branch"
+          fi

.github/workflows/site.yml

@@ -0,0 +1,97 @@
+name: Website
+
+on:
+  pull_request:
+    branches: [trunk]
+    paths:
+      - site/**
+      - .asf.yaml
+      - .github/workflows/site.yml
+  push:
+    branches:
+      - trunk
+      - preview/*
+    paths:
+      - site/**
+      - .asf.yaml
+      - .github/workflows/site.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: website-${{ github.repository }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7
+        with:
+          persist-credentials: false
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7
+        with:
+          node-version: 24
+      - name: Enable pnpm
+        run: corepack enable pnpm
+      - name: Select the site URL
+        env:
+          SOURCE_BRANCH: ${{ github.head_ref || github.ref_name }}
+        run: |
+          if [[ "$SOURCE_BRANCH" == preview/* ]]; then
+            name="${SOURCE_BRANCH#preview/}"
+            [[ "$name" =~ ^[a-z0-9]+(-[a-z0-9]+)*$ ]] || { echo 'Use preview/<lowercase-name> for website previews.' >&2; exit 1; }
+            echo "SITE_URL=https://steve-${name}.staged.apache.org" >> "$GITHUB_ENV"
+          fi
+      - name: Install dependencies
+        working-directory: site
+        run: pnpm install --frozen-lockfile
+      - name: Validate and build
+        working-directory: site
+        run: pnpm validate
+      - uses: actions/upload-artifact@b7c566a772e6b6bfb58ed0dc250532a479d7789f # v6
+        if: github.event_name != 'pull_request'
+        with:
+          name: website
+          path: site/build
+          include-hidden-files: true
+          if-no-files-found: error
+
+  publish:
+    needs: build
+    if: github.event_name != 'pull_request' && (github.ref == 'refs/heads/trunk' || startsWith(github.ref, 'refs/heads/preview/'))
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: website
+          path: build
+      - name: Select the publishing branch
+        id: target
+        env:
+          SOURCE_BRANCH: ${{ github.ref_name }}
+        run: |
+          if [[ "$SOURCE_BRANCH" == trunk ]]; then
+            echo 'branch=asf-site' >> "$GITHUB_OUTPUT"
+            echo 'url=https://steve.apache.org' >> "$GITHUB_OUTPUT"
+          else
+            name="${SOURCE_BRANCH#preview/}"
+            echo "branch=site/${name}-staging" >> "$GITHUB_OUTPUT"
+            echo "url=https://steve-${name}.staged.apache.org" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Publish generated files
+        uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: build
+          publish_branch: ${{ steps.target.outputs.branch }}
+          force_orphan: false
+          enable_jekyll: true
+      - name: Link to the website
+        env:
+          SITE_URL: ${{ steps.target.outputs.url }}
+        run: echo "Website submitted to ASF publishing — [open site]($SITE_URL). Publication may take a few minutes." >> "$GITHUB_STEP_SUMMARY"

README.md

@@ -53,16 +53,20 @@ See also [`monitoring/README.md`](monitoring/README.md).
 
 ## Getting Started
 
-Getting Started documentation can be found at: http://steve.apache.org/demo.html
-Otherwise, come to the #steve channel on the Slack workspace at the-asf.slack.com, 
-and we'd be glad to help you.
+Read the [Getting Started Guide](v3/docs/quickstart.md) to set up a v3 development
+environment, or visit https://steve.apache.org/getting-started/ for an overview
+of the application and tally tools. Ask questions on the development mailing
+list below.
 
 ## Documentation
 
-Documentation may be found at http://steve.apache.org/documentation.html
+Documentation may be found at https://steve.apache.org/documentation/.
 
 Contributions to the documentation are very welcome.
 
+The website is built with Docusaurus from [`site/`](site/README.md) in this
+repository. See the site README for local development and preview publishing.
+
 ## Mailing Lists
 
 Discussion about Steve takes place on the following mailing lists:

site/.gitignore

@@ -0,0 +1,3 @@
+node_modules/
+.docusaurus/
+build/

site/.prettierignore

@@ -0,0 +1,4 @@
+build/
+.docusaurus/
+pnpm-lock.yaml
+static/images/

site/.prettierrc.json

@@ -0,0 +1,4 @@
+{
+  "singleQuote": true,
+  "printWidth": 100
+}

site/README.md

@@ -0,0 +1,43 @@
+# Apache STeVe website
+
+The public website is built with Docusaurus from this directory. The Python application and its documentation remain in `v3/`; the website links to those guides instead of maintaining another copy.
+
+## Local development
+
+Use Node.js 24 and the pnpm version pinned in `package.json` (available through Corepack).
+
+```shell
+cd site
+corepack enable pnpm
+pnpm install --frozen-lockfile
+pnpm start
+```
+
+Pages live in `src/pages/`, styles in `src/css/`, and static assets in `static/`.
+
+Before opening a pull request, run:
+
+```shell
+pnpm validate
+pnpm serve
+```
+
+Validation checks formatting, runs the metadata tests, and performs a production build, including Docusaurus's broken-link checks. Use `pnpm format` to format website sources. `pnpm serve` serves the generated `build/` directory, including the DOAP document and legacy URL redirects.
+
+## Publishing and previews
+
+The `Website` GitHub Actions workflow builds website changes in pull requests. Pushes to `trunk` also publish the generated files to `asf-site`, which ASF Infrastructure serves at <https://steve.apache.org/>. The publishing action makes ordinary commits and pushes, preserving the generated branch's history.
+
+For a hosted preview, a committer can push a branch named `preview/<name>` to this repository. Use lowercase letters, numbers, and single hyphens in the name, for example `preview/website`. The workflow publishes `site/<name>-staging`, and ASF Infrastructure serves it at `https://steve-<name>.staged.apache.org`. The workflow summary links to the preview; allow a few minutes for ASF publishing after the workflow finishes. Fork pull requests are built and validated, but do not publish a hosted preview.
+
+Closing a pull request from a preview branch deletes its generated staging branch. The cleanup workflow must already exist on the default branch to handle a closed pull request. For a preview without a pull request, delete the generated branch when it is no longer needed.
+
+The root `.asf.yaml` controls production publishing and automatic staging. The build copies it into the output because ASF reads that configuration on each generated branch. See the [ASF Infrastructure documentation](https://infra.apache.org/asf-yaml.html) for branch-specific configuration.
+
+## Project metadata
+
+Maintain project information in `project.metadata` in the root `.asf.yaml`. ATR synchronization uses that section, and the website build generates `doap.rdf` from it for consumers that require DOAP XML. The generated document identifies the project and its PMC without maintaining a list of individual maintainers.
+
+The legacy `projects.apache.org` feed still points to the separate SVN DOAP file. After this website is published and <https://steve.apache.org/doap.rdf> is available, update the STeVe entry in [`apache/comdev-projects/data/projects.xml`](https://github.com/apache/comdev-projects/blob/trunk/data/projects.xml) to that URL. Until that separate change lands, the feed continues reading SVN. Do not edit the SVN copy as an ongoing second source of metadata.
+
+Old entry points such as `demo.html`, `documentation.html`, `community.html`, and `downloads.html` are generated as redirect pages to the current content. The former privacy-policy page redirects to the ASF privacy policy.