Deploy to GitHub Pages

Deploy Kecare Blog to GitHub Pages

Prerequisites

Before starting the deployment, please ensure you have the following ready:

• Github Account
• Git and Node.js

Create a GitHub Repository

1. Create a public repository on GitHub
2. Record the repository address: https://github.com/<username>/<repo>.git

Configuring SSH Connection

For the specific process, please visit Connecting to GitHub with SSH - GitHub Docs

Verify SSH Connection

ssh -T git@github.com

Push Code to GitHub

cd <你的主题目录>

git init

git add -A

git commit -m "init: 初始化项目"

git branch -M main

git remote add origin git@github.com:<username>/<repo>.git

git push -u origin main

After a successful push, your code will appear in the main branch of the GitHub repository.

Configuring Nuxt

⚠️ Note: This section is for the example theme using Nuxt. If you are using other frameworks, please refer to the deployment documentation for the corresponding framework.

GitHub Pages only supports static sites. Nuxt requires pre-rendering the application into static HTML files.

Configuring Base URL

If you are not using a custom domain, you need to set the correct Base URL.

Method 1: Configure in nuxt.config.ts

export default defineNuxtConfig({
  app: {
    baseURL: '/<repository>/',  // 替换为你的仓库名
  },
});

Method 2: Configure via Environment Variables

NUXT_APP_BASE_URL=/<repository>/

📖 Reference: Nuxt Official Documentation - GitHub Pages Deployment

---

Build and Publish

Make sure to execute in the theme directory:

npm install

npx nuxt build --preset github_pages

npx gh-pages -d .output/public

This command will automatically create the gh-pages branch and push the static files.

Enable GitHub Pages

Configuring Pages Settings

1. Go to the repository Settings → Pages

2. Source select Deploy from a branch

3. Branch select gh-pages, Folder select (root)

4. After saving, visit https://<username>.github.io/<repo>/

Frequently Asked Questions

Q: How to achieve automatic deployment?

A: You can use GitHub Actions to achieve automatic build and deployment. Nuxt officially provides example workflows. For details, refer to the Nuxt GitHub Pages Deployment Documentation.

Q: How to use a custom domain?

A: Add a custom domain in GitHub Pages settings and configure DNS resolution at your domain service provider to point to GitHub Pages.

Q: What to do if the build fails?

A: I don't know