From 4e94b20124ed22469269a2645546a33b1d6b2580 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Fri, 5 Dec 2025 19:13:00 +0900 Subject: [PATCH 1/4] chore: add docs assets download script --- .github/workflows/ci.yaml | 41 +--------- mise.toml | 2 + scripts/fetch-docs-assets.sh | 146 +++++++++++++++++++++++++++++++++++ 3 files changed, 149 insertions(+), 40 deletions(-) create mode 100644 scripts/fetch-docs-assets.sh diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 08c8e0e..1a69279 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -64,7 +64,6 @@ jobs: uses: jdx/mise-action@13abe502c30c1559a5c37dff303831bab82c9402 # v2.2.3 - name: Install dependencies run: bun install --frozen-lockfile - - name: Fetch docs assets if: ${{ matrix.kind == 'ja-JP' }} run: bun run fetch-docs-ja-jp @@ -73,45 +72,7 @@ jobs: shell: bash run: | set -euxo pipefail - - # Prepare docs.json - curl -L https://github.com/typst-community/dev-builds/releases/download/docs-${{ matrix.tag }}/docs.json \ - -o public/docs.json - sd '/DOCS-BASE/' '${{ matrix.base }}' public/docs.json - - # Prepare docs assets - curl -LO https://github.com/typst-community/dev-builds/releases/download/docs-${{ matrix.tag }}/docs-assets.zip - unzip docs-assets.zip - mv assets public/assets - - # Prepare favicon - curl -L https://github.com/typst-community/org/raw/main/design/typst-community.icon.png \ - -o public/favicon.png - - # Configure metadata - TAG=${{ matrix.tag }} - # Strip the leading ‘v’ or convert to a valid format - ${{ startsWith(matrix.tag, 'v') && 'VERSION=${TAG#v}' || 'VERSION="0.dev.${TAG}"' }} - cat << EOF > public/metadata.json - { - "\$schema": "../metadata.schema.json", - "language": "en-US", - "version": "$VERSION", - "typstOfficialUrl": "https://typst.app", - "typstOfficialDocsUrl": "https://typst.app/docs/", - "githubOrganizationUrl": "https://github.com/typst-community", - "socialLinks": [ - { "url": "https://github.com/typst-community/typst-docs-web" }, - { - "title": "Discord (Typst)", - "url": "https://discord.gg/2uDybryKPe" - } - ], - "originUrl": "https://example.com/", - "basePath": "${{ matrix.base }}", - "displayTranslationStatus": false - } - EOF + bash scripts/fetch-docs-assets.sh --tag "${{ matrix.tag }}" --base "${{ matrix.base }}" --dest public - name: Run Vite build run: bun run build diff --git a/mise.toml b/mise.toml index 13a2449..3076066 100644 --- a/mise.toml +++ b/mise.toml @@ -5,3 +5,5 @@ node = "22.11.0" bun = "1.2.21" pinact = "3.1.1" sd = "1.0.0" +shfmt = "3.12.0" +shellcheck = "0.11.0" diff --git a/scripts/fetch-docs-assets.sh b/scripts/fetch-docs-assets.sh new file mode 100644 index 0000000..d50ad72 --- /dev/null +++ b/scripts/fetch-docs-assets.sh @@ -0,0 +1,146 @@ +#!/usr/bin/env bash +# Usage: fetch-docs-assets.sh [--tag TAG] [--base BASE] [--dest DEST] +# This script downloads docs.json and assets from the typst-community/dev-builds GitHub release +# and writes `public/docs.json`, `public/assets`, `public/favicon.png`, and `public/metadata.json`. + +set -euo pipefail + +print_usage() { + cat <<'EOF' +Usage: fetch-docs-assets.sh [--tag TAG] [--base BASE] [--dest DEST] + +Environment/args: + --tag TAG (required) Release tag to download, e.g. v0.14.0 or latest + --base BASE (required) Base path used by docs, e.g. / or /docs/ + --dest DEST (optional) Destination directory to write files (default: public) + +This script performs the following: + - Downloads docs.json from the release tag + - Replaces '/DOCS-BASE/' placeholder in docs.json with the provided base + - Downloads docs-assets.zip and extracts it to destination/assets + - Downloads favicon and writes to destination/favicon.png + - Generates destination/metadata.json with basic deployment metadata +EOF +} + +# Defaults +ORG="typst-community" +DEST="public" +TAG="" +BASE="" + +# Parse args +while [[ $# -gt 0 ]]; do + case "$1" in + --tag) + TAG="$2" + shift 2 + ;; + --base) + BASE="$2" + shift 2 + ;; + --dest) + DEST="$2" + shift 2 + ;; + --help | -h) + print_usage + exit 0 + ;; + *) + echo "Unknown option: $1" >&2 + print_usage + exit 2 + ;; + esac +done + +if [[ -z "$TAG" || -z "$BASE" ]]; then + echo "--tag and --base are required" >&2 + print_usage + exit 2 +fi + +mkdir -p "$DEST" + +# Compute VERSION like the previous CI did +if [[ "$TAG" == v* ]]; then + VERSION="${TAG#v}" +else + VERSION="0.dev.${TAG}" +fi + +RELEASE_BASE_URL="https://github.com/${ORG}/dev-builds/releases/download/docs-${TAG}" + +# Download docs.json +DOCS_URL="${RELEASE_BASE_URL}/docs.json" +echo "Fetching docs from ${DOCS_URL}" +if ! curl -sSfL "$DOCS_URL" -o "${DEST}/docs.json"; then + echo "Failed to download docs.json from ${DOCS_URL}" >&2 + exit 3 +fi + +# Replace placeholder '/DOCS-BASE/' with provided base in docs.json +# Use `sd` if available, else fallback to sed +if command -v sd >/dev/null 2>&1; then + sd '/DOCS-BASE/' "$BASE" "${DEST}/docs.json" +else + # Use portable sed: escape slashes + ESCAPED_BASE=$(printf '%s' "$BASE" | sed 's|/|\\/|g') + sed -i "s/\/DOCS-BASE\//${ESCAPED_BASE}/g" "${DEST}/docs.json" +fi + +# Download assets and extract +ASSETS_URL="${RELEASE_BASE_URL}/docs-assets.zip" +ASSETS_ZIP="docs-assets.zip" +if curl -sSfL "$ASSETS_URL" -o "$ASSETS_ZIP"; then + echo "Extracting ${ASSETS_ZIP} to ${DEST}/assets" + # Clean up existing assets if present + rm -rf "${DEST}/assets" + unzip -q "$ASSETS_ZIP" + if [[ -d assets ]]; then + mv assets "${DEST}/assets" + else + echo "Downloaded zip did not contain assets/ folder" >&2 + # keep build going; not necessarily fatal + fi + rm -f "$ASSETS_ZIP" +else + echo "No assets ZIP was found at ${ASSETS_URL} (continuing without error)" >&2 +fi + +# Download favicon +FAVICON_URL="https://github.com/${ORG}/org/raw/main/design/typst-community.icon.png" +if curl -sSfL "$FAVICON_URL" -o "${DEST}/favicon.png"; then + echo "Wrote favicon to ${DEST}/favicon.png" +else + echo "Failed to download favicon from ${FAVICON_URL} (continuing without error)" >&2 +fi + +# Write metadata.json +cat >"${DEST}/metadata.json" < Date: Fri, 5 Dec 2025 19:20:35 +0900 Subject: [PATCH 2/4] ci: add job for shfmt and shellcheck linting --- .github/workflows/ci.yaml | 21 +++++++++++++++++++++ 1 file changed, 21 insertions(+) diff --git a/.github/workflows/ci.yaml b/.github/workflows/ci.yaml index 1a69279..1fb1149 100644 --- a/.github/workflows/ci.yaml +++ b/.github/workflows/ci.yaml @@ -36,6 +36,27 @@ jobs: - name: ${{ matrix.name }} run: ${{ matrix.command }} + ci-shell: + runs-on: ubuntu-24.04 + strategy: + fail-fast: false + matrix: + include: + - task: shfmt + name: "Run shfmt" + command: "shfmt -d ." + - task: shellcheck + name: "Run shellcheck" + command: "shellcheck **/*.sh" + name: Run ${{ matrix.task }} + steps: + - name: Checkout the repository + uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2 + - name: Setup tools + uses: jdx/mise-action@13abe502c30c1559a5c37dff303831bab82c9402 # v2.2.3 + - name: ${{ matrix.name }} + run: ${{ matrix.command }} + build: runs-on: ubuntu-24.04 strategy: From 7f7a866995c04d0546111c42b0c0738c4feecb13 Mon Sep 17 00:00:00 2001 From: 3w36zj6 <52315048+3w36zj6@users.noreply.github.com> Date: Fri, 5 Dec 2025 19:22:30 +0900 Subject: [PATCH 3/4] style: apply shfmt --- netlify-build.sh | 48 ++++++++++++++++++++++++------------------------ 1 file changed, 24 insertions(+), 24 deletions(-) diff --git a/netlify-build.sh b/netlify-build.sh index 3a94a43..d6c3f55 100644 --- a/netlify-build.sh +++ b/netlify-build.sh @@ -14,13 +14,13 @@ mkdir _site # Prepare favicon curl -L https://github.com/typst-community/org/raw/main/design/typst-community.icon.png \ - -o _site/favicon.png + -o _site/favicon.png cp _site/favicon.png public/favicon.png # Prepare the index page REF=$(git rev-parse --short HEAD) DATE=$(git log --max-count=1 --pretty='%cd' --date=iso) -cat << EOF > _site/index.html +cat <_site/index.html @@ -71,22 +71,22 @@ EOF # 3.1. Build en-US build_en_US() { - local VERSION="$1" + local VERSION="$1" - BASE="en-US-$VERSION" + BASE="en-US-$VERSION" - # Prepare docs.json - curl -L https://github.com/typst-community/dev-builds/releases/download/docs-"$VERSION"/docs.json \ - -o public/docs.json - sd '/DOCS-BASE/' "/$BASE/" public/docs.json + # Prepare docs.json + curl -L https://github.com/typst-community/dev-builds/releases/download/docs-"$VERSION"/docs.json \ + -o public/docs.json + sd '/DOCS-BASE/' "/$BASE/" public/docs.json - # Prepare docs assets - curl -LO https://github.com/typst-community/dev-builds/releases/download/docs-"$VERSION"/docs-assets.zip - unzip docs-assets.zip && rm docs-assets.zip - mv assets public/assets + # Prepare docs assets + curl -LO https://github.com/typst-community/dev-builds/releases/download/docs-"$VERSION"/docs-assets.zip + unzip docs-assets.zip && rm docs-assets.zip + mv assets public/assets - # Configure metadata - cat << EOF > public/metadata.json + # Configure metadata + cat <public/metadata.json { "\$schema": "../metadata.schema.json", "language": "en-US", @@ -101,15 +101,15 @@ build_en_US() { "displayTranslationStatus": false } EOF - # $DEPLOY_URL will be set by netlify. Fallback to example.com for local testing. - # https://docs.netlify.com/build/configure-builds/environment-variables/#deploy-urls-and-metadata + # $DEPLOY_URL will be set by netlify. Fallback to example.com for local testing. + # https://docs.netlify.com/build/configure-builds/environment-variables/#deploy-urls-and-metadata - # Build - mise exec -- bun run build - mv dist _site/"$BASE" + # Build + mise exec -- bun run build + mv dist _site/"$BASE" - # Clean - rm -r public/{docs.json,assets,metadata.json} + # Clean + rm -r public/{docs.json,assets,metadata.json} } build_en_US v0.14.0 @@ -121,9 +121,9 @@ build_en_US v0.13.1 mise exec -- bun run fetch-docs-ja-jp sd '"/docs/' '"/ja-JP/' public/docs.json sd --fixed-strings \ - '"basePath": "/docs/",' \ - '"basePath": "/ja-JP/",' \ - public/metadata.json + '"basePath": "/docs/",' \ + '"basePath": "/ja-JP/",' \ + public/metadata.json # Prepare docs assets # At present, typst-jp do not translate comments within example code. From f0d83cc5bba5461965831745ba6643f5b143a5ab Mon Sep 17 00:00:00 2001 From: "Y.D.X." <73375426+YDX-2147483647@users.noreply.github.com> Date: Fri, 5 Dec 2025 20:45:52 +0800 Subject: [PATCH 4/4] ci: unify netlify build script with docs asssets download script, and add en-US v0.14.1 --- netlify.toml | 2 +- scripts/fetch-docs-assets.sh | 16 ++++-- netlify-build.sh => scripts/netlify-build.sh | 55 ++++++-------------- 3 files changed, 29 insertions(+), 44 deletions(-) rename netlify-build.sh => scripts/netlify-build.sh (69%) diff --git a/netlify.toml b/netlify.toml index 5816a23..d74d894 100644 --- a/netlify.toml +++ b/netlify.toml @@ -1,3 +1,3 @@ [build] -command = "bash netlify-build.sh" +command = "bash scripts/netlify-build.sh" publish = "_site" diff --git a/scripts/fetch-docs-assets.sh b/scripts/fetch-docs-assets.sh index d50ad72..d466b63 100644 --- a/scripts/fetch-docs-assets.sh +++ b/scripts/fetch-docs-assets.sh @@ -7,12 +7,13 @@ set -euo pipefail print_usage() { cat <<'EOF' -Usage: fetch-docs-assets.sh [--tag TAG] [--base BASE] [--dest DEST] +Usage: fetch-docs-assets.sh [--tag TAG] [--base BASE] [--dest DEST] [--origin ORIGIN] Environment/args: - --tag TAG (required) Release tag to download, e.g. v0.14.0 or latest - --base BASE (required) Base path used by docs, e.g. / or /docs/ - --dest DEST (optional) Destination directory to write files (default: public) + --tag TAG (required) Release tag to download, e.g. v0.14.0 or latest + --base BASE (required) Base path used by docs, e.g. / or /docs/ + --dest DEST (optional) Destination directory to write files (default: public) + --origin ORIGIN (optional) Origin URL for the deployed site, without base path (default: https://example.com/) This script performs the following: - Downloads docs.json from the release tag @@ -26,6 +27,7 @@ EOF # Defaults ORG="typst-community" DEST="public" +ORIGIN="https://example.com/" TAG="" BASE="" @@ -44,6 +46,10 @@ while [[ $# -gt 0 ]]; do DEST="$2" shift 2 ;; + --origin) + ORIGIN="$2" + shift 2 + ;; --help | -h) print_usage exit 0 @@ -134,7 +140,7 @@ cat >"${DEST}/metadata.json" <_site/index.html

Build a website from the documentation JSON file generated by typst-docs.

This website is for developing typst-docs-web. Its contents might be changed at anytime.

    +
  • en-US, v0.14.1
  • en-US, v0.14.0
  • en-US, v0.13.1
  • ja-JP, v0.13.1
    • @@ -72,36 +73,14 @@ EOF build_en_US() { local VERSION="$1" - - BASE="en-US-$VERSION" - - # Prepare docs.json - curl -L https://github.com/typst-community/dev-builds/releases/download/docs-"$VERSION"/docs.json \ - -o public/docs.json - sd '/DOCS-BASE/' "/$BASE/" public/docs.json - - # Prepare docs assets - curl -LO https://github.com/typst-community/dev-builds/releases/download/docs-"$VERSION"/docs-assets.zip - unzip docs-assets.zip && rm docs-assets.zip - mv assets public/assets - - # Configure metadata - cat <public/metadata.json -{ - "\$schema": "../metadata.schema.json", - "language": "en-US", - "version": "${VERSION#v}", - "typstOfficialUrl": "https://typst.app", - "typstOfficialDocsUrl": "https://typst.app/docs/", - "githubOrganizationUrl": "https://github.com/typst-community", - "githubRepositoryUrl": "https://github.com/typst-community/typst-docs-web", - "discordServerUrl": "https://discord.gg/2uDybryKPe", - "originUrl": "${DEPLOY_URL:-https://example.com}/", - "basePath": "/$BASE/", - "displayTranslationStatus": false -} -EOF - # $DEPLOY_URL will be set by netlify. Fallback to example.com for local testing. + local BASE="en-US-${VERSION}" + + bash scripts/fetch-docs-assets.sh \ + --tag "${VERSION}" \ + --base "/${BASE}/" \ + --dest public \ + --origin "${DEPLOY_URL}" + # $DEPLOY_URL will be set by netlify. # https://docs.netlify.com/build/configure-builds/environment-variables/#deploy-urls-and-metadata # Build @@ -112,11 +91,19 @@ EOF rm -r public/{docs.json,assets,metadata.json} } +build_en_US v0.14.1 build_en_US v0.14.0 build_en_US v0.13.1 # 3.2. Build ja-JP +# Prepare docs assets +# At present, typst-jp do not translate comments within example code. +# And there is no simple way to download assets from GitHub Actions or the gh-pages branch. +# Therefore, we reuse the assets from the official version. +bash scripts/fetch-docs-assets.sh --tag "v0.13.1" --base "/irrelevant/" +rm public/{docs,metadata}.json + # Prepare JSON files mise exec -- bun run fetch-docs-ja-jp sd '"/docs/' '"/ja-JP/' public/docs.json @@ -125,14 +112,6 @@ sd --fixed-strings \ '"basePath": "/ja-JP/",' \ public/metadata.json -# Prepare docs assets -# At present, typst-jp do not translate comments within example code. -# And there is no simple way to download assets from GitHub Actions or the gh-pages branch. -# Therefore, we reuse the assets from the official version. -curl -LO https://github.com/typst-community/dev-builds/releases/download/docs-v0.13.1/docs-assets.zip -unzip docs-assets.zip && rm docs-assets.zip -mv assets public/assets - # Build mise exec -- bun run build mv dist _site/ja-JP