Deploying to GitHub Pages

GitHub Pages is a free static website hosting service provided by GitHub that allows users to convert their code repositories directly into accessible public web pages. For developers, it serves not only as an ideal choice for building personal blogs, project documentation, or demonstration pages but also as a powerful tool for implementing a "write-and-deploy" workflow. Its core advantage lies in the lack of need to configure complex server environments (such as Nginx or Apache); instead, users simply use a static site generator locally to convert code into HTML/CSS/JS and push it to a GitHub repository to automatically complete deployment and publishing.
Before using GitHub Pages, you need to ensure you have the following basic conditions:

  • GitHub Account: Used to store source code and trigger the build process.
  • Static Site Generator Toolchain: Current mainstream choices include VuePress, Hugo, Hexo, or Next.js. This article uses VuePress as an example for explanation, as it has the most integrated relationship with GitHub Pages and the most complete documentation.
  • Node.js Environment: Used to run build scripts and install dependency packages.

First, you need to initialize an empty Git repository as your project root directory. Open the terminal, enter this directory, and execute the following commands to create a new VuePress project structure:

npm init vuepress@latest my-website
cd my-website
# Assuming you choose the default template, it will generate .vuepress/dist/ and docs/ folders at this point
git add .
git commit -m "Initial setup"

Configuring Build and Deployment Rules

The deployment logic for GitHub Pages relies on GitHub Actions. You need to create a file named .github/workflows in the root directory of your project (if it does not exist) and define a workflow file within it, such as deploy.yml. This configuration file tells GitHub to automatically execute specific script commands to build the website and upload it to the server whenever code is pushed to the repository.

Below is a standard deployment configuration example; this process will automatically run VuePress build commands and publish the artifacts to the default branch (usually master or main):

name: Deploy to GitHub Pages

on:
  push:
    branches: [main] # Please modify this name according to your actual main branch

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

concurrency:
  group: "pages-build-deploy"
  cancel-in-progress: true

jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v3
        
      # Install Node.js (Optional, can be skipped if configured locally)
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with: { node-version: '18' }

      - name: Install dependencies and build
        run: |
          npm install
          npm run docs:build
        
      # Deploy to GitHub Pages (Requires installing pages-action)
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/.vuepress/dist/

Note: In publish_dir, you need to specify the directory containing the built static files. For VuePress, the default output path is typically .vuepress/dist. If your project uses a different generator (such as Hugo), please adjust this path parameter accordingly. Additionally, ensure that your GitHub Actions has the permission to write to Pages, which is usually achieved through the automatic injection of GITHUB_TOKEN.

Local Verification and Final Deployment

It is strongly recommended to perform a full build test locally before committing code to the remote repository. Running the following command will simulate the production environment packaging process:

npm run docs:build

Upon successful execution, you will obtain a docs/.vuepress/dist folder containing complete static files. You can manually drag this folder into your browser to preview it, or deploy it to other platforms such as Netlify or Vercel for secondary testing. If the local build is error-free and there are no errors (such as missing dependencies or path errors), then the GitHub Actions automated process will also execute smoothly.

Once code is pushed to the configured branch, the GitHub CI/CD pipeline will be automatically triggered. The entire process takes approximately a few minutes; during this time, you can visit https://<your-username>.github.io/<repository-name> to check the build progress and final results. Once deployment is successful, this link becomes your project's permanent online address, allowing you to enjoy globally accelerated static resource services without any additional server fees.