DEV Community

Sh Raj
Sh Raj

Posted on

🚀 How to Deploy a Docusaurus Website on GitHub Pages

#github #ghpages #docusaurus #story

📄 Introduction

Docusaurus is a modern static site generator that's perfect for creating documentation websites. Hosting your Docusaurus site on GitHub Pages is a popular choice because it’s free, easy to set up, and integrates directly with your GitHub repository.

This article will guide you through:

  • Creating a Docusaurus project
  • Building your documentation site
  • Deploying it seamlessly to GitHub Pages

✅ Prerequisites

Before we start, ensure you have:

  • Node.js (version 16.14+ recommended)
  • Git
  • A GitHub account
  • Basic terminal knowledge

🛠️ Step 1: Create a New Docusaurus Project

Run the following command to scaffold a new Docusaurus project:

npx create-docusaurus@latest my-website classic
Enter fullscreen mode Exit fullscreen mode
  • my-website is your project folder name.
  • classic is the template (the most commonly used one).

Move into your project directory:

cd my-website
Enter fullscreen mode Exit fullscreen mode

Test the site locally:

npm run start
Enter fullscreen mode Exit fullscreen mode

✍️ Step 2: Configure GitHub Pages Deployment

  1. Initialize a Git repository (if not already done): 
   git init
Enter fullscreen mode Exit fullscreen mode
  1. Push your project to GitHub: 
   git remote add origin https://github.com/yourusername/your-repo-name.git
   git branch -M main
   git add .
   git commit -m "Initial commit"
   git push -u origin main
Enter fullscreen mode Exit fullscreen mode
  1. Install GitHub Pages Package: 
   npm install --save gh-pages
Enter fullscreen mode Exit fullscreen mode
  1. Update docusaurus.config.js: 
   module.exports = {
     // Your existing config...
     url: 'https://yourusername.github.io', // Your GitHub Pages URL
     baseUrl: '/your-repo-name/', // The name of your GitHub repo
     // If deploying to https://<USERNAME>.github.io/, set baseUrl to '/'
     // If deploying to a custom domain, set baseUrl to '/' and set the 'cname' file in static folder
   };
Enter fullscreen mode Exit fullscreen mode

⚙️ Step 3: Add Deployment Scripts

In your package.json, add the following scripts:

"scripts": {
  "predeploy": "npm run build",
  "deploy": "gh-pages -d build"
}
Enter fullscreen mode Exit fullscreen mode

🏗️ Step 4: Build the Project

Run:

npm run build
Enter fullscreen mode Exit fullscreen mode

This will generate a build folder that contains your static site.

🚀 Step 5: Deploy to GitHub Pages

Run:

npm run deploy
Enter fullscreen mode Exit fullscreen mode

This will:

  • Build the project
  • Push the build folder to the gh-pages branch automatically

🔗 Step 6: Configure GitHub Pages

  1. Go to your GitHub repository.
  2. Click on Settings > Pages.
  3. Under Source, select the gh-pages branch and the / (root) directory.
  4. Click Save.

Your site will typically be live at:

https://yourusername.github.io/your-repo-name/
Enter fullscreen mode Exit fullscreen mode

🛠️ Optional: Custom Domain Setup

If you want to use a custom domain:

  1. Add your domain in docusaurus.config.js: 
   url: 'https://yourdomain.com',
   baseUrl: '/',
Enter fullscreen mode Exit fullscreen mode
  1. Create a file named CNAME in the static folder with the content: 
   yourdomain.com
Enter fullscreen mode Exit fullscreen mode
  1. Set up your DNS to point to GitHub Pages IPs.

🐛 Troubleshooting

  • 404 Errors?

    • Ensure your baseUrl in docusaurus.config.js is correctly set.

  • Build Errors?

    • Run npm install to make sure all dependencies are installed.

  • Deployment Not Updating?

    • Try deleting the local node_modules and reinstalling: 
    rm -rf node_modules
npm install

🎯 Summary Checklist

Task Status
Create Docusaurus project ✅
Push to GitHub ✅
Configure docusaurus.config.js ✅
Add deploy scripts ✅
Build the project ✅
Deploy to GitHub Pages ✅
Set GitHub Pages source ✅

📚 Additional Resources

Top comments (0)