User Guide Setup

Table of contents

1. Overview
2. Install Ruby and Jekyll
3. Docs Directory
4. Create or Update the Gemfile
5. Install Dependencies
6. Configure _config.yml
7. Serve Jekyll Locally
8. Commit and Push to GitHub
9. Enable GitHub Pages
10. Verify Deployment
11. (Optional) Custom Domain
12. Troubleshooting
    
    

1. Overview Table of Contents

This guide explains how to set up Jekyll to serve the PHP MVC framework’s user guide both locally and on GitHub Pages, ensuring compatibility with GitHub’s environment.

2. Install Ruby and Jekyll Table of Contents

Jekyll requires Ruby. Follow the steps based on your operating system:

Linux

gem install bundler jekyll

MacOS

• A. Install rbnev using Homebrew

  brew install rbenv ruby-build
  

  
  

• B. Shell Configuration

  Zsh (MacOS default) - run:

  echo 'eval "$(rbenv init - zsh)"' >> ~/.zshrc
  source ~/.zshrc
  

  Bash users:

  echo 'eval "$(rbenv init - bash)"' >> ~/.bash_profile
  source ~/.bash_profile
  

  
  

• C. Install Ruby (Latest Stable Version)

  rbenv install 3.2.2
  rbenv global 3.2.2
  
  

  
  

• D. Install Bundler and Jekyll

  gem install bundler
  gem install jekyll
  

  
  

Windows

• A. Install Ruby from RubyInstaller.
• B. Open a terminal (Git Bash or Command Prompt with Ruby) and run:

   gem install bundler jekyll
  

  
  

3. Docs Directory Table of Contents

Navigate to the docs/ Directory

Since the user guide is stored in docs/ at the project root, navigate to that directory:

cd path/to/your/project/docs

4. Create or Update the Gemfile Table of Contents

The Gemfile manages Jekyll dependencies. Ensure it contains:

source "https://rubygems.org"

Use the GitHub Pages gem, which includes Jekyll

gem "github-pages", group: :jekyll_plugins

Minima is included with GitHub Pages, so you don’t need to specify a version.

gem "minima"

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
end

Windows and JRuby fixes

platforms :mingw, :x64_mingw, :mswin, :jruby do
  gem "tzinfo", ">= 1", "< 3"
  gem "tzinfo-data"
end

gem "wdm", "~> 0.1", platforms: [:mingw, :x64_mingw, :mswin]
gem "http_parser.rb", "~> 0.6.0", platforms: [:jruby]

5. Install Dependencies Table of Contents

Before installing, remove any old dependencies:

rm -rf Gemfile.lock

Now install the correct versions:

bundle install

6. Configure _config.yml Table of Contents

Modify docs/_config.yml to ensure the correct setup:

title: "My PHP MVC Framework Guide"
description: "User guide for my custom PHP MVC framework."
theme: minima
baseurl: "/your-repo-name" # Set to "" if this is a user/org site
url: "https://yourusername.github.io"

# Ensure Jekyll serves Markdown files
include:
  - "*.md"

# Set up assets folder
sass:
  sass_dir: "assets/css"

# Exclude unnecessary files
exclude:
  - "Gemfile"
  - "Gemfile.lock"
  - "README.md"
  - "vendor"
  - "node_modules"

Base URL Considerations:

• For user/org sites (yourusername.github.io), set:

  baseurl: ""
  

• For project sites (yourusername.github.io/your-repo-name), set:

  baseurl: "/your-repo-name"
  

  
  

7. Serve Jekyll Locally Table of Contents

To preview the guide locally from within the docs directory:

bundle exec jekyll serve --livereload

or under project root:

php console serve:docs

Then open:

• For project sites: http://localhost:4000/your-repo-name/
• For user/org sites: http://localhost:4000/
  

8. Commit and Push to GitHub Table of Contents

Once everything looks good, commit and push the changes:

git add .
git commit -m "Set up Jekyll for framework guide"
git push origin main

9. Enable GitHub Pages Table of Contents

1. Go to your repository on GitHub.
2. Navigate to Settings > Pages.
3. Under Source, select:

   • GitHub Actions (recommended)

     OR

   • GitHub Pages with the main branch and /docs folder.

4. Click Save.

Your site will be available at:

• https://yourusername.github.io/your-repo-name/

  OR

• https://yourusername.github.io/ (for user/org sites).
  
  

10. Verify Deployment Table of Contents

After a few minutes, visit:

• For project pages: https://yourusername.github.io/your-repo-name/
• For user/org pages: https://yourusername.github.io/

To check for issues:

bundle exec github-pages health-check

11. (Optional) Custom Domain Table of Contents

If using a custom domain:

1. Add a CNAME file inside docs/ containing your domain.
2. Update DNS settings to point to GitHub’s IPs.
3. Enable HTTPS in GitHub Pages settings.
   
   

12. Troubleshooting Table of Contents

In my particular case I had to export gems using the following commands:

echo 'export GEM_HOME=$HOME/gems' >> ~/.bashrc
echo 'export PATH="$HOME/gems/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc