Using Jekyll


Various commands:

To start a jekyll server, clean up, update, install the bundles, run:

bundle exec jekyll serve
bundle exec jekyll clean 
bundle update jekyll
bundle install


Caution

Sometimes Gemfile.lock pins a different bundler. Verify:

gem list bundler
tail -n +1 Gemfile.lock | sed -n '/BUNDLED WITH/,$p'

Removing the file solves the problem.

Important

never ever run bundle as sudo


To update Bundler to a version compatible with your Ruby version and check / uninstall old versions:

sudo gem update --system
sudo gem update bundler
sudo gem install bundler 
gem list bundler    
sudo gem uninstall bundler -v 2.6.5

Sometimes nuke bundler and re-install it:

sudo rm -f /opt/homebrew/bin/bundle /opt/homebrew/bin/bundler
sudo gem uninstall bundler -aIx


Styling


Admonitions:

Adding the following to the jekyll_plugins group in the gemfile allows to use admonitions in markdown files:

  gem "jekyll-gfm-admonitions"

Admonitions can be achieved like this:

> [!NOTE] 
> Note text line1
> Note text line2

The available admonitions are:

[!NOTE], [!TIP], [!WARNING], [!CAUTION], [!IMPORTANT]


Adding Content

The files in directories starting with an underscore are not processed by jekyll if specified in the _config.yml file like this:

# this add content to the website from the local dirs starting with _
collections:
  pi0:
    output: true


Optionally permalinks can be added for navigation.


Additional markdown features