🚀 GitHub Pages is a powerful feature that lets you host static websites directly from a GitHub repository. But what if you have multiple README files—like User Guides, FAQs, and API Documentation—and want to display them as separate pages on GitHub Pages?

🎯 In this guide, you will learn:

✅ How to structure multiple README files for GitHub Pages✅ How to use GitHub Actions to automate deployment✅ How to add a Jekyll theme for a professional look✅ How to generate a Table of Contents for easy navigation

By the end of this tutorial, you will have a fully functional multi-page documentation site for your GitHub repository.

🛠 Step 1: Organize Your README Files

First, structure your repository properly. Inside your repository, create a docs/ folder and place multiple README files inside it.

📁 Your repository structure should look like this:

📁 my-repository
 ┣ 📁 docs
 ┃ ┣ 📄 README.md
 ┃ ┣ 📄 slidecraft-pro.md
 ┃ ┣ 📄 user-guide.md
 ┃ ┣ 📄 faq.md
 ┣ 📄 .github/workflows/deploy-docs.yml
 ┣ 📄 .gitignore
 ┣ 📄 LICENSE
 ┣ 📄 README.md

Each README file serves as a separate documentation page.

🔹 Step 2: Create a GitHub Actions Workflow

To automate the deployment of these files to GitHub Pages, create a GitHub Actions workflow.

📌 Create a new file at:.github/workflows/deploy-docs.yml

🔽 Copy and paste the following code:

name: Deploy Multiple README Files to GitHub Pages

on:
  push:
    branches:
      - main  # Run workflow on pushes to the main branch

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Repository
        uses: actions/checkout@v3

      - name: Setup Pages Directory
        run: |
          mkdir -p _site
          cp -r docs/* _site/

      - name: Create Table of Contents
        run: |
          echo "# Documentation Home" > _site/index.md
          echo "- [Home](README.md)" >> _site/index.md
          echo "- [SlideCraft Pro](slidecraft-pro.md)" >> _site/index.md
          echo "- [User Guide](user-guide.md)" >> _site/index.md
          echo "- [FAQ](faq.md)" >> _site/index.md

      - name: Deploy to GitHub Pages
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          branch: gh-pages  # Deploy to GitHub Pages branch
          folder: _site     # Directory to publish

🔹 What This Workflow Does:

✅ Copies all files from docs/ to _site/
✅ Generates a Table of Contents (index.md)
✅ Deploys _site/ to GitHub Pages automatically

🔹 Step 3: Enable GitHub Pages

Now, activate GitHub Pages in your repository settings:

1️⃣ Go to Settings → Pages2️⃣ Under Branch, select gh-pages3️⃣ Click Save4️⃣ Your site will be available at:

https://yourusername.github.io/your-repository/

Each README file will be accessible at:

https://yourusername.github.io/your-repository/user-guide.md
https://yourusername.github.io/your-repository/faq.md
https://yourusername.github.io/your-repository/slidecraft-pro.md

🔹 Step 4: Add a Jekyll Theme for a Professional Look

By default, GitHub Pages supports Jekyll themes, which help make your documentation look clean and professional.

📌 Create a _config.yml file in your docs/ folder:

title: "SlideCraft Pro Documentation"
theme: jekyll-theme-cayman

🚀 Now, your documentation will have a polished look!

📌 Final Result

Once GitHub Actions runs, your multi-page documentation will be live on GitHub Pages 🎉

✨ Example Structure on GitHub Pages:

📄 Home (index.md)
📄 SlideCraft Pro (slidecraft-pro.md)
📄 User Guide (user-guide.md)
📄 FAQ (faq.md)

⚡ Bonus: Automate Updates

If you want to update your GitHub Pages whenever new README files are added, simply commit and push changes to the main branch:

git add .
git commit -m "Updated documentation"
git push origin main

GitHub Actions will automatically redeploy your updated files! 🚀

🌟 Summary

✅ We created multiple README files inside docs/✅ We used GitHub Actions to deploy them automatically✅ We enabled GitHub Pages for public access✅ We added a Jekyll theme for a professional look

🎉 Now, your documentation is live and ready to be shared!

📚 How to Publish Multiple README Files on GitHub Pages Using GitHub Actions