Skip to content

Setup GitHub Pages

Resources:

MkDocs

Resources:

Install MkDocs Material with Docker

Here are the steps from the installing with Docker guide:

# pull the image
docker pull squidfunk/mkdocs-material

# navigate to the root directory of the repo
cd /path/to/root/of/repo

# run the container and attach the current directory to /docs
docker run --rm -it -p 8000:8000 -v ${PWD}:/docs squidfunk/mkdocs-material

Adding plugins to the Docker image

From https://squidfunk.github.io/mkdocs-material/getting-started/#with-docker

Material for MkDocs only bundles selected plugins in order to keep the size of the official image small. If the plugin you want to use is not included, create a new Dockerfile and extend the official Docker image: 

FROM squidfunk/mkdocs-material
RUN pip install ...
Next, you can build the image with the following command: 
docker build -t squidfunk/mkdocs-material .
The new image can be used exactly like the official image.

Creating a new site with Docker

After issuing the docker run command above, issue the following: 

docker run --rm -it -v ${PWD}:/docs squidfunk/mkdocs-material new .

Publish the site with GitHub Actions

From From https://squidfunk.github.io/mkdocs-material/getting-started/#with-docker

Using GitHub Actions you can automate the deployment of your project documentation. At the root of your repository, create a new GitHub Actions workflow, e.g. .github/workflows/ci.yml, and copy and paste the following contents: 

name: ci 
on:
  push:
    branches:
      - master 
      - main
permissions:
  contents: write
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Configure Git Credentials
        run: |
          git config user.name github-actions[bot]
          git config user.email 41898282+github-actions[bot]@users.noreply.github.com
      - uses: actions/setup-python@v5
        with:
          python-version: 3.x
      - run: echo "cache_id=$(date --utc '+%V')" >> $GITHUB_ENV 
      - uses: actions/cache@v4
        with:
          key: mkdocs-material-${{ env.cache_id }}
          path: .cache
          restore-keys: |
            mkdocs-material-
      - run: pip install mkdocs-material 
      - run: mkdocs gh-deploy --force
Now, when a new commit is pushed to either the master or main branches, the static site is automatically built and deployed. Push your changes to see the workflow in action.

Jekyll

Resources: * Creating a GitHub Pages site * Creating a GitHub Pages site with Jekyll * Adding a theme to your GitHub Pages site using Jekyll

Install Jekyll on macOS

Follow the Jekyll on macOS guide:

  1. Install Ruby using Homebrew
    1. Install Homebrew
    2. Install chruby and the latest Ruby with ruby-install
  2. Install Jekyll

Supported macOS versions

Permalink: Jekyll supported macOS versions

  • Ventura (macOS 13)
  • Monterey (macOS 12)
  • Big Sur (macOS 11)

Older macOS versions might work, but we don’t officially support them.

1. Install Ruby using Homebrew

Permalink: Install Ruby

To install Jekyll on macOS, you need a proper Ruby development environment. While macOS comes preinstalled with Ruby, we don’t recommend using that version to install Jekyll. This external article goes over the various reasons why you shouldn’t use the system Ruby.

Instead, you’ll need to install a separate and newer version of Ruby using a version manager such as asdf, chruby, rbenv, or rvm. Version managers allow you to easily install multiple versions of Ruby, and switch between them.

We recommend chruby because it’s the simplest and least likely to cause issues.

The instructions below are an excerpt from this detailed external guide to install Ruby on Mac. They work best if you’re setting up development tools for the first time on your Mac. If you’ve already tried to install Ruby or Jekyll on your Mac, or if you run into any issues, read that guide.

1.1: Install Homebrew

Permalink: Step 1: Install Homebrew

Homebrew makes it easy to install development tools on a Mac. 

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

1.2: Install chruby and the latest Ruby with ruby-install

Permalink: Step 2: Install chruby and the latest Ruby with ruby-install

Install chruby and ruby-install with Homebrew: 

brew install chruby ruby-install xz

Install the latest stable version of Ruby (supported by Jekyll): 

ruby-install ruby 3.1.3

This will take a few minutes, and once it’s done, configure your shell to automatically use chruby: 

echo "source $(brew --prefix)/opt/chruby/share/chruby/chruby.sh" >> ~/.zshrc
echo "source $(brew --prefix)/opt/chruby/share/chruby/auto.sh" >> ~/.zshrc
echo "chruby ruby-3.1.3" >> ~/.zshrc # run 'chruby' to see actual version

If you’re using Bash, replace .zshrc with .bash_profile. If you’re not sure, read this external guide to find out which shell you’re using.

Quit and relaunch Terminal, then check that everything is working: 

ruby -v

It should show ruby 3.1.3p185 (2022-11-24 revision 1a6b16756e) or a newer version.

Next, read that same external guide for important notes about setting and switching between Ruby versions with chruby.

2. Install Jekyll

Permalink: Install Jekyll

After installing Ruby with chruby, install the latest Jekyll gem: 

gem install jekyll

Troubleshooting

Permalink: Jekyll on macOS Troubleshooting

See Troubleshooting or ask for help on our forum.