tangshengming/personal_website

Deploy Website

Overview

Use this skill to guide deployment of an already generated website to GitHub Pages. The expected project is an Astro static site stored in a GitHub repository, with source files committed and deployment handled by GitHub Actions.

This skill assumes the website itself already exists. Do not redesign the website unless the user asks.

Deployment Model

Use this setup for the current personal website workflow:

• Track source code in Git.
• Ignore generated or dependency folders such as node_modules/, dist/, .astro/, and tmp/.
• Build the site with npm.cmd run build.
• Deploy from GitHub Actions to GitHub Pages.
• Keep local development at http://localhost:4321/.
• Use an Astro base path only during GitHub Actions builds for project Pages URLs such as https://USERNAME.github.io/REPOSITORY/.

Before Deploying

Check readiness with lightweight commands:

git status
npm.cmd run build

Confirm these files or settings exist:

• package.json
• astro.config.mjs
• .gitignore
• .github/workflows/deploy.yml
• src/
• public/

For this project, astro.config.mjs should support local and GitHub Pages builds, for example:

import { defineConfig } from "astro/config";

const isGithubPagesBuild = process.env.GITHUB_ACTIONS === "true";

export default defineConfig({
  site: "https://USERNAME.github.io",
  base: isGithubPagesBuild ? "/REPOSITORY" : "/",
});

Use URL helpers in Astro pages/layouts when linking to local public assets or internal pages:

const base = import.meta.env.BASE_URL;
const url = (path: string) => {
  const normalizedBase = base.endsWith("/") ? base : `${base}/`;
  const normalizedPath = path.replace(/^\/+/, "");

  return `${normalizedBase}${normalizedPath}`;
};

GitHub Actions Workflow

Use a Pages workflow like this:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: pages
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v7
      - name: Build with Astro
        uses: withastro/action@v6

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

Explain the actions simply when needed:

• actions/checkout@v7: downloads the repository into the GitHub Actions runner.
• withastro/action@v6: installs dependencies, builds the Astro site, and prepares the Pages artifact.
• actions/deploy-pages@v5: publishes the built artifact to GitHub Pages.

The @vN suffix pins a major version of the action.

Repository And Commit Steps

Guide the user to commit and push deployment-ready source changes:

git status
git add .
git commit -m "Prepare website deployment"
git push origin main

If Git reports line-ending warnings such as LF will be replaced by CRLF, explain that this is a Windows line-ending normalization warning and usually not a deployment blocker.

If Git reports no configured user identity, configure the repository or global identity before committing. If privacy matters, use the user's GitHub noreply email.

GitHub Pages Settings

Guide the user in GitHub:

1. Open the repository on GitHub.
2. Go to Settings.
3. Go to Pages.
4. Under Build and deployment, set Source to GitHub Actions.
5. Save if GitHub shows a save button.
6. Go to the Actions tab and open the latest deployment run.
7. Wait until the workflow succeeds.
8. Open the Pages URL shown by GitHub.

For a project site, the expected URL is usually:

https://USERNAME.github.io/REPOSITORY/

Verification

After deployment, verify:

• Homepage loads.
• Navigation links work.
• Images load.
• Downloadable files, such as the CV PDF, open correctly.
• Browser URL includes the repository path for project Pages.
• No broken paths like /REPOSITORYprojects, /REPOSITORYprofile.jpg, or /REPOSITORYfile.pdf appear in generated HTML.

If the deployed site is broken but local preview works, inspect base-path handling first.

If GitHub Actions fails, inspect the failing step:

• Checkout failure: repository or permission problem.
• Install/build failure: dependency, Astro, or source-code problem.
• Deploy failure: GitHub Pages source/permission/settings problem.

Completion Criteria

Consider the deployment task complete when:

• Local build passes.
• Source changes are committed and pushed.
• GitHub Pages source is set to GitHub Actions.
• The Actions deployment run succeeds.
• The public Pages URL loads the website correctly.