Why Jekyll

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

Getting Started with Jekyll SSG

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:

  1. Go to the RubyInstaller for Windows website - here
  2. Download the latest version of Ruby+Devkit.
  3. 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

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

Jekyll 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
    • ./_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

    I have used it to deploy with this workflow this very same theme here: https://jalcocert.github.io/RPi/

    name: "Build and Deploy"
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/Free 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, matumo or Plausible.

Where can I get favicons for Jekyll?