docs: Add CHANGELOG.md with auto-update workflow (#2690)

* feat: Add automated changelog generation and update workflow

* feat: Add token parameter to GitHub Action for changelog updates

* fix: add error handling for missing CHANGELOG.md in workflows

* fix: also exclude docs/changelog.md from codespell

* feat: Refactor CHANGELOG.md initialization to use echo for improved readability

Author: koxudaxi

.github/workflows/changelog.yaml

@@ -0,0 +1,69 @@
+name: Update CHANGELOG
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  update-changelog:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: main
+          token: ${{ secrets.PAT }}
+
+      - name: Get release info and update CHANGELOG
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          set -euo pipefail
+
+          TAG="${{ github.event.release.tag_name }}"
+          DATE=$(gh release view "$TAG" --json publishedAt --jq '.publishedAt | split("T")[0]')
+          BODY=$(gh release view "$TAG" --json body --jq '.body // ""')
+
+          # Create new entry
+          {
+            echo "## [$TAG](https://github.com/${{ github.repository }}/releases/tag/$TAG) - $DATE"
+            echo ""
+            printf '%s\n' "$BODY"
+            echo ""
+            echo "---"
+            echo ""
+          } > new_entry.md
+
+          # Initialize CHANGELOG.md if it doesn't exist
+          if [ ! -f CHANGELOG.md ]; then
+            {
+              echo "# Changelog"
+              echo ""
+              echo "All notable changes to this project are documented in this file."
+              echo "This changelog is automatically generated from GitHub Releases."
+              echo ""
+              echo "---"
+              echo ""
+            } > CHANGELOG.md
+          fi
+
+          # Split CHANGELOG.md at first "---" separator (content-based, not line-number based)
+          # Header includes everything up to and including the first "---" line
+          # Old entries are everything after the first "---" line
+          awk '/^---$/ && !found {found=1; print > "header.md"; next} !found {print > "header.md"} found {print > "old_entries.md"}' CHANGELOG.md
+
+          # Ensure old_entries.md exists even if empty
+          touch old_entries.md
+
+          # Reassemble: header + new entry + old entries
+          cat header.md new_entry.md old_entries.md > CHANGELOG.md
+          rm -f header.md new_entry.md old_entries.md
+
+      - name: Commit and push
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "github-actions[bot]@users.noreply.github.com"
+          git add CHANGELOG.md
+          git diff --cached --quiet || git commit -m "docs: update CHANGELOG.md for ${{ github.event.release.tag_name }}"
+          git push

.github/workflows/docs.yaml

@@ -21,6 +21,15 @@ jobs:
         python-version: 3.13
     - name: Install dependencies
       run: uv sync
+    - name: Copy CHANGELOG to docs
+      run: |
+        if [ -f CHANGELOG.md ]; then
+          cp CHANGELOG.md docs/changelog.md
+        else
+          echo "# Changelog" > docs/changelog.md
+          echo "" >> docs/changelog.md
+          echo "Changelog will be available after the first release." >> docs/changelog.md
+        fi
     - name: build site
       run: zensical build --clean
     - name: Deploy