Deploy to GitHub Pages (From 0 to Live Meow~)

0. What You Need to Prepare (Checklist)

• A GitHub account (register it yourself meow)
• Git installed locally
• Node.js installed locally (for installing dependencies and building Nuxt)

1. Create a New Repository on GitHub

1. Log in to GitHub

2. New repository in the upper right corner

3. Fill in the repository information:

Repository name: Any name is fine, meow, anything goes (maybe

Choose Public, make it public meow

After creation, you will receive a repository address (which will be used for Git binding later).

2. Bind Local Git to GitHub (SSH Method Recommended Meow~)

2.1 Generating SSH Key (Local)

Open the terminal and execute:

ssh-keygen -t ed25519 -C "your_email@example.com"

Just press Enter all the way. If you encounter any issues, take a look at the official GitHub documentation—it follows the same process and provides more details 👉Click me meow

2.2 Adding the Public Key to GitHub

1. Open your local public key file (usually ~/.ssh/id_ed25519.pub)
2. Copy the content (it's a long string starting with ssh-ed25519)
3. In your GitHub account settings, add an SSH key (paste the public key)

This is the official GitHub "Add SSH key" process. GitHub's documentation is definitely better than what I could write, so 👉just click me meow

2.3 Testing SSH Connection

ssh -T git@github.com

First, you will be prompted to confirm the fingerprint; enter yes. Seeing the welcome message means success~

3. Push the theme code to your repository

Now, assuming you already have a theme directory (e.g., Kecare-theme/), we want to push it to the newly created repository.

3.1 Initialize Git in the Theme Directory (If It's Not Already a Repository)

cd <你的主题目录>
git init
git add -A
git commit -m "init: theme"

3.2 Adding a Remote Repository and Pushing

Replace the following <user> and <repo> with your GitHub username and repository name:

git branch -M main
git remote add origin git@github.com:<user>/<repo>.git
git push -u origin main

At this point, your theme code should already be in the main branch of the GitHub repository, meow~

4. Nuxt (Example Theme)

[!WARNING] Please note: The scaffolding and tech stack (language/framework/build method) may vary significantly between different themes, so the deployment methods may also be completely different. This document only uses the Example Theme for demonstration—because the Example Theme is built with Nuxt, the Nuxt build and deployment steps described here are "customized for this theme". Before actual deployment, please prioritize reading the deployment instructions and requirements provided by the theme author.

GitHub Pages only supports static sites, and Nuxt will pre-render your application into static HTML files.

4.1 Base URL

If you are not using a custom domain, you need to set NUXT_APP_BASE_URL to your repository name during the build step. For example: https://<user>.github.io/<repository>/

NUXT_APP_BASE_URL=/<repository>/

Nuxt officially explicitly requires this meow, for details please see👉Click me meow

However, I think it's fine to configure the baseUrl in Nuxt.config.ts.

export default defineNuxtConfig({
  compatibilityDate: '2025-07-15',
  devtools: { enabled: true },
  app: {
    baseURL: 'https://<user>.github.io/<repository>/',
    head: {
    },
  },
});

5. Building Static Assets in the Theme Directory

Make sure you are executing in the theme directory

npm install

Then build:

npx nuxt build --preset github_pages

After the build is complete, the Nuxt GitHub Pages preset will generate static files to:

.output/public

This is the output path provided by Nuxt (we will publish this directory later).

6. Publish Build Artifacts to the gh-pages Branch

Execute in the theme directory:

npx gh-pages -d .output/public

It will push .output/public to the gh-pages branch (which will be automatically created if it doesn't exist), perfect for beginners~

7. Enable Pages in the GitHub Repository

1. Go to your repository → Settings

2. Find Pages

3. In the Source / Build and deployment section, select:

• Branch: gh-pages
• Folder: / (root)

4. Save

There is also the official GitHub process👉Still click me meow

After saving, wait a moment, and GitHub will provide your Pages address, for example:

https://<user>.github.io/<repo>/

Then access it meow.

FAQ

Q: Can I make it automatically deploy (without manually building + publishing each time)?

A: Yes. Nuxt officially provides example workflows for GitHub Actions that can automatically upload and deploy .output/public to Pages. 👉Click here meow