Creating Structured Multi-Page Documentation with GitHub Pages

GitHub repositories often include README documentation, but for larger projects, it’s beneficial to have structured documentation with multiple pages and search functionality. In this blog post, we will explore how to achieve this using Jekyll themes, specifically the “just-the-docs” theme. By following the steps outlined below, you can create a comprehensive documentation page with navigation, search capabilities, and repository links

once we finish the same, we will have documentation page looks like below which will contains

Lets do the same

Step 1: Organize Your Documentation

To maintain organization, start by creating a “docs” folder in the root section of your repository. This will serve as the home for your documentation files.

Step 2: Enable GitHub Pages

Go to your repository’s settings and navigate to the “Pages” section. Enable GitHub Pages and select “GitHub Actions” as the source. This will allow automatic generation of your documentation.

Step 3: Create a Gemfile

Inside the “docs” folder, create a new file called “Gemfile” with the following content:

source ‘https://rubygems.org'

gem “jekyll”, “~> 4.3” # installed by `gem jekyll`

gem “just-the-docs”, “0.5.0” # pinned to the current release

This file specifies the required dependencies for Jekyll and the “just-the-docs” theme.

Step 4: Create Your Pages

Begin by creating your initial page named “index.md” and add additional pages as needed. Each page should have its own markdown file with content specific to that topic. To establish connections between pages, include YAML front matter at the beginning of each file. For example:

---
title: Overview
layout: default
nav_order: 1
---

You can customize the title, layout, and navigation order according to your needs. For sub-pages, you can use the “parent” field to define the parent page like below

---
title: SubPage
layout: default
nav_order: 2
parent: Overview
---

Here the sub page will comes under the Overview page.

you can find the full documentation on the customization and configuration this link

Step 5: Configure the Documentation

Create a basic configuration file named “_config.yml” in the “docs” folder. This file should contain information about your documentation, such as the title, description, theme, logo, and favicon. Additionally, include any auxiliary links, such as a link to your repository.

title: your document title
description: your document description
theme: just-the-docs
logo: "your_logo_path"
favicon_ico: "your_icon_path"

url: your_repo_url

aux_links:
  Repository: your_repo_url

Step 6: Set Up the GitHub Action Workflow

To automate the documentation generation process, create a GitHub Action workflow file. This file specifies the steps required to build and deploy the documentation. It also sets permissions and concurrency settings. The workflow will trigger whenever there are changes in the “docs” folder.

# Workflow for building and deploying a Jekyll site to GitHub Pages
name: Deploy Github Pages

on:
  push:
   branches: 
     - "main"
   paths:
     - "docs/**"

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  # Build job
  build:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: docs
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.1' # Not needed with a .ruby-version file
          bundler-cache: true # runs 'bundle install' and caches installed gems automatically
          cache-version: 0 # Increment this number if you need to re-download cached gems
          working-directory: '${{ github.workspace }}/docs'
      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v2
      - name: Build with Jekyll
        # Outputs to the './_site' directory by default
        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
        env:
          JEKYLL_ENV: production
      - name: Upload artifact
        # Automatically uploads an artifact from the './_site' directory by default
        uses: actions/upload-pages-artifact@v1
        with:
          path: "docs/_site/"

  # Deployment job
  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v1

By following these steps, you can create structured multi-page documentation with GitHub Pages using the “just-the-docs” theme. This approach allows you to organize your documentation effectively, provide navigation and search functionality, and integrate it seamlessly with your repository. Empower your users with comprehensive documentation and enhance the overall experience of your project.

Keep coding.. :)