These are the steps we take to support the Echoes of Wasteland site building locally.
We use GitHub Actions to build and deploy a Jekyll site.
Start with the documentation site here;
then, move to the coding setup in the next section.
Setting up your local Mac box
Publishing this site does not require any additional local setup or configuration
as the associated GitHub Actions are automatically managing the build environment.
However, to run the site locally, one needs Ruby to install Bundler and Jekyll.
System Ruby exists as a part of Mac OS X at /usr/bin/ruby.
Using OS Ruby for user projects is a TERRIBLE idea, so we use asdf to manage our own SDKs.
Provisioning Project Ruby SDK on OS X (asdf)
brew install coreutils curl asdf
. $(brew --prefix)/opt/asdf/libexec/asdf.sh
asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git
See docs for asdf plugin add ruby https://github.com/asdf-vm/asdf-ruby.git for more details.
If the Ruby plugin is already installed, then:
asdf plugin-update ruby
OR:
asdf plugin update --all
Which ruby is present?
type -a ruby
NOTE: asdf manages its SDKs in the metafile ~/.tool-versions.
Install the Correct Ruby Version
At the time of this writing, the expected Ruby version is 3.3.4; See GitHub Pages Dependency Versions.
asdf install ruby 3.3.4
asdf global ruby 3.3.4
NOTE: You may ignore this pesky bug https://github.com/asdf-vm/asdf-ruby/issues/384
asdf list ruby
Should see 3.3.4, like so:
➜ ~
asdf list ruby
2.7.4
*3.3.4
Install Jekyll for a NEW site
Navigate to your project docs folder and run:
docs_folder=${PWD##*/}
docs_folder=${docs_folder:-/}
printf '\nWorking in:\n%s\n' "${PWD##*/}"
printf '\nDocs folder as:\n%s\n' "${PWD##*/}"
gem install jekyll
jekyll new --skip-bundle .
Or install Jekyll from anywhere with gem install jekyll.
And create the new site with jekyll new --skip-bundle .
jekyll new --force --skip-bundle .
Building EXISTING site locally
Make sure bundle is installed globally or in project for your docs folder to work as site root.
bundle install
IMPORTANT: GitHub Pages Documentation!
Theming Jekyll
- about Themes
- our current theme (Minimal Mistakes)
Where are my assets?
NEXT: please see the coding setup section!