Skip to main content

🚀 Deploy Your Docusaurus Portfolio to GitHub Pages

This tutorial walks you through deploying your personal portfolio built with Docusaurus to GitHub Pages using GitHub Actions.

If you like this portfolio design, feel free to use or fork it from my GitHub repository.

🛠️ Prerequisites​

  • A GitHub account
  • A Docusaurus portfolio project (e.g., my-portfolio)
  • Basic terminal/git knowledge

📁 Step 1: Push Your Code to GitHub​

Create a new public or private GitHub repo and push your local portfolio:

git init
git remote add origin https://github.com/USERNAME/REPO_NAME.git
git add .
git commit -m "Initial commit"
git push -u origin main

⚙️ Step 2: Update docusaurus.config.js​

url: 'https://USERNAME.github.io',
baseUrl: '/REPO_NAME/', // '/' if it's a personal site
projectName: 'REPO_NAME',
organizationName: 'USERNAME',

For a personal site, use:

baseUrl: '/',
projectName: 'USERNAME.github.io',

🔄 Step 3: Add GitHub Action for Deployment​

Install the deploy script:

npm install --save docusaurus

Then add the following to .github/workflows/deploy.yml:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node
        uses: actions/setup-node@v3
        with:
          node-version: 18
      - run: npm install
      - run: npm run build
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

🌍 Step 4: Enable GitHub Pages​

  1. Go to Repo > Settings > Pages
  2. Build and deployment
    • Source → Deploy from a branch
    • Branch → gh-pages / (root)
  3. Save ✅

✅ Done!​

Your site should be available at:

https://USERNAME.github.io

💡 Troubleshooting Tips

  • Use the GitHub Actions tab to debug failed deployments
  • For private repos, Pages is supported if you’re on GitHub Pro or Team plans

Now your portfolio is live! 🧑‍💻