Home Jekyll Install on Mac
Post
Cancel
Preview Image

Jekyll Install on Mac

Posted Jun 22, 2023 Updated Jun 2, 2025
By Bob Beveridge
10 min read

To edit the Archive

  • Run terminal; execute following to run Jekyll:
    • cd ~/Documents/jekyll_website_MASTER
    • bundle exec jekyll serve
  • Open folder ~/Documents/jekyll_website_MASTER in VSCode to edit Posts, etc
  • Open Finder window to /Media/Archive_Jekyll/files for organising static files/images/etc
  • SyncThing will copy Jekyll generated pages to TrueNAS /Media folder
  • Browse to Apache served website

Introduction

This Archive / website is written using markup from which Jekyll generates a static website of HTML files and CSS/JavaScript. Given the static nature of the Archive files, no database or PHP is required to serve the pages dynamically as was required with the original Wordpress version. More control can be exercised of the layout of the supporting files, and exactly what goes into them, although it is less intuitive if you’re not into using markdown. Jekyll uses various templates and Liquid code to build the static pages, allowing any sort of format required.

Having initially run Jekyll in Docker, I discovered that we can run Jekyll itself directly on a Mac, without SSH into the server, etc, so I decided to give it a go.

Start of Update

Having updated to macOS Sonoma, I had lost the previous Jekyll installation, but when I tried using the method I used previously I had errors all over the place. Settled on using the instructions on the Jekyll website, hence this update.

Install HomeBrew

A tool to make it easier to install tools on Mac:

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

Install Ruby

Ruby and RubyGems are already installed on the Mac, but are older versions and also in a folder where write permssions are limited. Instead of changing write permissions, it is okay to install a newer version of Ruby.

Install version manager chruby, ruby-install, and latest version of Ruby:

  • Run brew install chruby ruby-install
  • Run ruby-install ruby 3.4.1

Configure 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.4.1" >> ~/.zshrc # run 'chruby' to see actual version

Then quit and relaunch terminal. Check everything is working:

  • ruby -v

should show ruby 3.4.1 ...

Install Jekyll

  • Run gem install jekyll bundler

Start Jekyll Website

  • Go to the main Documents folder; run cd and drag folder from finder is easiest
  • Create new website jekyll new jekyll_website_MASTER
  • Change to new folder cd jekyll_website_MASTER
  • Build and serve the default website bundle exec jekyll serve

Failed to load with multiple errors. Googling got the suggestion bundle update, which then worked OK

  • Can use flags --livereload to automatically reload webpage after update, and --incremental to use incremental build of only pages that change (use with care)

  • Browse to the new website at http://localhost:4000

  • Once Apache and SyncThing are setup for use with Jekyll it is easier to just edit files locally on the Mac, upload static data files or images to the /files/ folder on Titan/Media, and then let Jekyll build the HTML files and for SyncThing to copy them to the Media folders. Can then browse fully at https://bbproj.org

End of Update

Install Chirpy Theme

  • Delete the newly created basic Jekyll install rm -R jekyll_website_MASTER and download the Chirpy theme from Github:

    • git clone https://github.com/cotes2020/jekyll-theme-chirpy.git jekyll_website_MASTER

  • Go into the folder cd jekyll_website_MASTER and run bundle to update all Gem dependencies

  • This does not give an “out-of-the-box” build and a few things needed adding:

    • A bunch of JavaScript libraries are missing from the \assets\lib folder. These were downloaded from the Chirpy GitHub site and unzipped into the folder

    • When run the terminal window showed a few JS files missing on build. I got these by running the Chirpy demo site, browsing to each page in turn, then looking at the page source and downloading the files in assets\js\dist. This resulted in six extra files

  • The minimal Chirpy website then seemed to work ok.

Modifying Chirpy Theme

Whenever edit _config.yml need to restart Jekyll.

  • Amend _config.yml with own details

    • timezone = Europe/London
    • title = BB Archive
    • tagline / description = Somewhere to keep a record of stuff I’ve done over the years
    • url = “https://bbproj.org”
    • github/username = bbprojects-org
    • twitter & username = commented out
    • social/name = Bob Beveridge
    • social/email = commented out
    • social/links/twitter = commented out
    • social/links/github = https://github.com/bbprojects-org
    • google_site_verification = commented out
    • img_cdn = empty
    • avatar = /files/img/avatar.png
    • assets/self_host/enabled = true [use local files, not CDN]
    • defaults/scope/comments = false [for posts]

  • Amend _data/authors.yml with personal data

  • Amend _data/contact.yml; GitHub only, rest commented out

  • In _data/locales delete all but en.yml

  • Move image code from _layouts/post.html to _layouts/page.html so now get image at top whether post or page
    • Amend image size to 960 x 250

  • Change aspect ratio for image in _sass/layout/post.scss to 96/25

  • Add _tabs/subject.md for each main subject area Computer, Electronics, Photography, etc, amending the Front matter order as required

  • Delete _tabs/archives.md, add _tabs/archive-posts.md, _tabs/archive-pages.md, _tabs/archive-diary.md and add associated layout files in _layouts

  • Having amended the size of the preview images in posts, the home page shows posts with images wrong size. Resolved by commenting out height:100% in .preview-img.img section of _sass/layout/home.scss. Also commented out height: 11.55rem further down

  • Add ‘new window fix’ to make all external links or PDF files open in a new browser tab
    • Download new-window-fix.html from Jekyll Codex
    • Save file to _includes folder
    • Add {% include new-window-fix.html %} at end of default.html layout file
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29

    <script>
//open external links in a new window
function external_new_window() {
  for(var c = document.getElementsByTagName("a"), a = 0;a < c.length;a++) {
    var b = c[a];
    if(b.getAttribute("href") && b.hostname !== location.hostname) {
      b.target = "_blank";
      b.rel = "noopener";
    }
  }
}
//open PDF / Sketchup (skp) / Word (docx) links in a new window
function pdf_new_window ()
{
  if (!document.getElementsByTagName) return false;
  var links = document.getElementsByTagName("a");
  for (var eleLink=0; eleLink < links.length; eleLink ++) {
  if ((links[eleLink].href.indexOf('.pdf') !== -1)||(links[eleLink].href.indexOf('.skp') !== -1)||(links[eleLink].href.indexOf('.docx') !== -1)) {
    links[eleLink].onclick =
    function() {
      window.open(this.href);
      return false;
      }
    }
  }
} 
pdf_new_window();
external_new_window();
</script>

  • To add related posts at end of main category pages, add code to page.html after post-content div section:

    1
2
3

    {% if page.related != nil %}
  {% include related-categories.html %}
{% endif %}
    • and the file itself:
    1
2
3
4
5
6
7
8
9
10
11

    {% assign filtered-posts = site.posts | where_exp:'p', 'p.categories contains page.related' %}
{% if filtered-posts.size > 0 %}
  <div>
  <h2>Related Pages</h2>
  <ul>
  {% for post in filtered-posts %}
    <li><a href="{{ post.url | relative_url }}">{{ post.title }}</a></li>
  {% endfor %}
  </ul>
  </div>
{% endif %}

  • To add related posts Navigator on series posts, add code to post.html after post-content div section:

    1
2
3

    {% if page.related != nil %}
  {% include related-series.html %}
{% endif %}
    • and the file itself:
    1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

    {% assign related_pages = "" | split: " " %}

{% for post in site.posts reversed %}
  {% if post.related == page.related %}
    {% assign related_pages = related_pages | push: post %}
  {% endif %}
{% endfor %}

{% if related_pages.size > 0 %}
  <div class="table-wrapper">
    <table>

      <thead>
        <tr>
          <td>
            <h2 id="navigatorXX"><span class="mr-2">{{ page.related }} Navigator</span><a href="#navigatorXX" class="anchor text-muted"><i class="fas fa-hashtag"></i></a></h2>
          </td>
        </tr>
      </thead>

      <tbody>
      {% for post in related_pages %}
        <tr>
        {% if post.url == page.url %}
          <td>>> <b><a href="{{ post.url | relative_url }}">{{ post.title }}</a></b></td>
        {% else %}
          <td><a href="{{ post.url | relative_url }}">{{ post.title }}</a></td>
        {% endif %}
        </tr>
      {% endfor %}
      </tbody>

    </table>
  </div>
{% endif %}
  • Based on this guide
    • html-proofer is already installed
  • Amend Jekyll site to allow sensible review by html-proofer
    • Have Jekyll running in Terminal window as above
    • In VSCode replace /files/ with http://192.168.0.22:8080/files/ to allow full search to Apache URL
    • In second Terminal window
      • cd ~/Documents/jekyll_website_MASTER
      • bundle exec htmlproofer ./_site
    • Result will be a number of errors. For some reason several external sites gave errors even though the links work fine, so just ignored them. Various others needed fixing
    • When happy with the results, put things back to normal:
      • In VSCode replace http://192.168.0.22:8080/files/ with /files/

SiteInspector is a free, open-source tool that helps find spelling-errors, grammatical errors, and broken links on websites.

Create folder for siteinspector data:

1
2

cd ~/docker
mkdir siteinspector

Add the following service definition to dc-siteinspector.yml in docker root folder:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

version: '3'

services:
  app:
    depends_on:
      - 'postgres'
      - 'redis'
    image: 'siteinspector/siteinspector:latest'
    ports:
      - '808:808'
    volumes:
      - '$DOCKERDIR/siteinspector/:/app'
    command:  bash -c "rake db:migrate && foreman start"
    environment:
      SECRET_KEY_BASE: FITSy9dGK9BlOOrOqOi3xRaWjMPgR9KQtT0GaPiBaKQ7LcYniHsdsSA78iEy8BmOGAXpkVi7Imp9dZeHfJPptA
      RAILS_LOG_TO_STDOUT: 'true'
      DATABASE_URL: postgresql://postgres:postgres@postgres:5432/siteinspector
      REDIS_URL: redis://redis:6379/0
      PORT: 808
      SIDEKIQ_CONCURRENCY: 10

  postgres:
    image: 'postgres:12.2'
    volumes:
      - 'postgres:/var/lib/postgresql/data'
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: postgres
      POSTGRES_DB: siteinspector

  redis:
    image: 'redis:5.0'
    command: redis-server
    volumes:
      - 'redis:/data'

volumes:
  redis:
  postgres:

From the Docker root folder, run this command to build the container:

1

sudo docker compose -f dc-siteinspector.yml up -d

Open the app locally on port 808 (http://localhost:808/) or using the remote Docker IP.

Layouts info

Files are hierarchical: post.html -> page.html -> default.html -> compress.html

They call additional content from _includes folder as necessary.

LIQUID NOTE: assign = any type variable, capture = captures any output as a string variable

POST.HTML

1
2
3
4
5
6
7
8
9
10
11

  Front Matter : refactor=true, panel_includes = toc, tail_includes = related-posts / post-nav / comments
  published date
  modified date
  author
  include read-time.html
  // content //
  related_pages (rcb: added)
  categories
  tags
  ?? change copyright
  include post-sharing.html

PAGE.HTML

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

  if layout.refactor or page.layout == 'page'
    _content = refactor-content.html
  else
    _content = content
  page.image (rcb: moved from post.html)
  if page.layout == 'page' or page.collection == 'tabs'
    title
    // _content //
    ?? rcb: related_pages
  else
    // _content //
  related_pages (rcb: added)
  panel (RHS):
    include update-list.html
    include trending-tags.html
    ?? layout.panel_includes
  ?? layout.tail_includes

DEFAULT.HTML

1
2
3
4
5
6
7
8
9
10
11

  include origin-type.html
  include head.html
  include sidebar.html
  include topbar.html
  // content //
  include search-results.html
  include footer.html
  include js-selector.html
  ?? include mermaid.html
  include search-loader.html
  include new-window-fix.html (rcb: added)

COMPRESS.HTML

1

  Compress HTML

Misc Notes (Todo)

Computer
This post is licensed under CC BY 4.0 by the author.
Recently Updated
Contents