Your Static Web Sites with Jekyll

The Jekyll Project

Thanks to Jekyll SSG, we can make websites without being a Web Dev:

The Jekyll Site
The Jekyll Source Code at Github
- License: MIT ❤️
- Jekyll Themes

So yes, Jekyll is Free and it can help you creating your Documentation, Blog etc.

I mean…we will use Jekyll together with Open Source community Themes to TWEAK and create our blog / documentation that we wanted to have for a long time.

Along the way, we will learn some interesting stuff:

How to customize jekyll
How to Deploy your Jekyll Website with a free Github Domain with CI/CD (GH Actions)
How to know what people liked the most at your Jekyll Site with Web Analytics

Why Jekyll

Ruby-based: Jekyll is written in Ruby, and it utilizes the Liquid template engine to process templates and content.
Markdown and HTML: Jekyll supports both Markdown and HTML for content creation. Markdown is often preferred for its simplicity and readability.
Templates and Layouts: Jekyll allows you to define templates and layouts to maintain consistency across your site. Templates can be customized using HTML and Liquid syntax.
Plugins: Jekyll supports plugins that extend its functionality. These plugins can be used for tasks such as generating sitemaps, optimizing images, or integrating with third-party services.
Free deployment: use Jekyll together with Github Pages / Firebase / Cloudflare Pages to get a Free Website with a domain!

Getting Started with Jekyll SSG

From the community, to the community:

Find a Jekyll Theme that you love!

https://github.com/wowthemesnet/jekyll-theme-memoirs?tab=License-1-ov-file#readme

git clone https://github.com/wowthemesnet/jekyll-theme-memoirs.git

#rm -rf .git

cd jekyll-theme-memoirs

gem install jekyll bundler

You might get this error: 'gem' is not recognized as an internal or external command, operable program or batch file.

To solve it:

Go to the RubyInstaller for Windows website - here
Download the latest version of Ruby+Devkit.
Run the installer. During the installation, ensure that you check the box that says “Add Ruby executables to your PATH” to ensure the gem command works from the command line.

Verify Jekyll’s installation with:

ruby -v
gem -v

How to Customize Jekyll

bundle install
bundle update --bundler
bundle exec jekyll serve

Self-Hosting Jekyll Static WebSites

Jekyll SSG + Docker

docker build -t my-jekyll-site .

# Use an official Ruby image as the base image
FROM ruby:3.0

# Install Jekyll and other dependencies
RUN gem install jekyll bundler

# Create a directory for your Jekyll site
WORKDIR /app

# Copy your Jekyll site files into the container
COPY . /app

# Install your Jekyll site's dependencies
RUN bundle install

# Build your Jekyll site
#RUN jekyll build

# Expose the port that your web server will run on (e.g., 80 for HTTP)
EXPOSE 80

# Command to start your web server (e.g., using Jekyll's built-in server)
#CMD ["jekyll", "serve", "--host", "0.0.0.0", "--port", "80"]

And the docker configuration file:

version: '3'
services:
  jekyll:
    build:
      context: .
      dockerfile: Dockerfile
    volumes:
      - .:/app  # Mount your Jekyll site files into the container
    command: ["jekyll", "serve", "--host", "0.0.0.0", "--port", "4000"]  # Customize Jekyll options as needed
    ports:
      - "4000:4000"  # Map the container's port to the host

  nginx:
    image: nginx:latest
    volumes:
      - ./nginx/nginx.conf:/etc/nginx/nginx.conf  # Mount your NGINX configuration
    ports:
      - "80:80"  # Map the container's port to the host

And with this docker compose you can deploy your jekyll image anywhere:

version: '3'
services:
  jekyll:
    image: your-jekyll-image-name:tag
    ports:
      - "4000:4000"  # Map the container's port to the host
    volumes:
      - jekyll-site:/app  # Mount the named volume into the container
      #- .:/app  # Mount your Jekyll site files into the container
    command: tail -f /dev/null #keep it running      

volumes:
  jekyll-site:  # Define the named volume here

How to use Jekyll with Github Pages

What you will get by using Github Pages:

A free github domain
Webpage Linked to your GH project

Here you have an GH Pages + Actions example with Chirpy

Jekyll Example - Chirpy Theme

The Chirpy Theme
The Chirpy Starter Theme - use this one!
- License: MIT ❤️
Clone it
Adapt base url
Adapt url to your github
To install dependencies —> bundle
To server locally to port 4000: http://127.0.0.1:4000/ or localhost:4000

bundle exec jekyll s

Important files for Jekyll:
- ./_config.yml
- _data/contact.yml
- ./posts/

FAQ

Help with get started - Jekyll 101

Find a Jekyll theme you like.
Install Ruby (as Jekyll uses it)
Try it locally and build when ready

#clone a Jekyll theme
snap install ruby --classic
bundle

bundle exec jekyll s
#http://127.0.0.1:4000/chirpy-starter/ #example

#bundle exec jekyll build

How to use Jekyll with Github Pages & GH Actions Workflow

You need a workflow like this one below so that Github Actions generates your Jekyll website and make it visible from Github Pages.

👉 Github Action Workflow - Jekyll to GH Pages

Thanks to Cotes2020 - You can Apply this config to deploy other Jekyll themes to GH Pages

name: "Build and Deploy jekyll to GH Pages"
on:
  push:
    branches:
      - main
      - master
    paths-ignore:
      - .gitignore
      - README.md
      - LICENSE

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

# Allow one concurrent deployment
concurrency:
  group: "pages"
  cancel-in-progress: true

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          # submodules: true
          # If using the 'assets' git submodule from Chirpy Starter, uncomment above
          # (See: https://github.com/cotes2020/chirpy-starter/tree/main/assets)

      - name: Setup Pages
        id: pages
        uses: actions/configure-pages@v3

      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: 3.2
          bundler-cache: true

      - name: Build site
        run: bundle exec jekyll b -d "_site${{ steps.pages.outputs.base_path }}"
        env:
          JEKYLL_ENV: "production"

      - name: Test site
        run: |
          bundle exec htmlproofer _site \
            \-\-disable-external=true \
            \-\-ignore-urls "/^http:\/\/127.0.0.1/,/^http:\/\/0.0.0.0/,/^http:\/\/localhost/"          

      - name: Upload site artifact
        uses: actions/upload-pages-artifact@v1
        with:
          path: "_site${{ steps.pages.outputs.base_path }}"

  deploy:
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v2

How to Add GA/F/OSS Web Analytics to Jekyll Chirpy Theme?

Thanks to Aouledissa for inspiration

Create _include folder in the root of your Chirpy repo
Create inside that folder the following files:

👉 google_analytics.html

<!-- With Umami Web Analytics -->
<script async src="https://umami.yourdomain.com/script.js" data-website-id="some-random-code-umami-provides"></script>

<!-- Google tag (gtag.js) -->
<!-- 
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
 <script>
 window.dataLayer = window.dataLayer || [];
 function gtag(){dataLayer.push(arguments);}
 gtag('js', new Date());

 gtag('config', 'G-XXXXXXXXXX');
 </script> -->

You can also use these procedure for other Web Analytics tools.

Copy the head.html file.

👉 and adapt head.html

Comment the GA Part (might be somehow different when you see it), but this is the idea. Dont forget to include inside the part, our script google_analytics with the liquid syntax.


{% include google_analytics.html %}


    <!-- GA -->
    <!-- {% if jekyll.environment == 'production' and site.google_analytics.id != empty and site.google_analytics.id %}
      <link rel="preconnect" href="https://www.google-analytics.com" crossorigin="use-credentials">
      <link rel="dns-prefetch" href="https://www.google-analytics.com">
  
      <link rel="preconnect" href="https://www.googletagmanager.com" crossorigin="anonymous">
      <link rel="dns-prefetch" href="https://www.googletagmanager.com">
    {% endif %} -->

This will work not only with Google Analytics, but with other F/OSS Web Analytics and Privacy respectful like: Umami, matomo or Plausible.

Where can I get favicons for Jekyll?

favicons

Interesting Webs Built with Jekyll

https://github.com/muan/site
- It can show how to use Jekyll + OpenStories! - https://github.com/dddddddddzzzz/OpenStories

Open Stories is a syndication format for distributing stories to friends and families.

The Jekyll Project#

Why Jekyll#

Getting Started with Jekyll SSG#

How to Customize Jekyll#

Self-Hosting Jekyll Static WebSites#

How to use Jekyll with Github Pages#

Jekyll Example - Chirpy Theme#

FAQ#

Help with get started - Jekyll 101#

How to use Jekyll with Github Pages & GH Actions Workflow#

How to Add GA/F/OSS Web Analytics to Jekyll Chirpy Theme?#

Where can I get favicons for Jekyll?#

Interesting Webs Built with Jekyll#