The Jekyll Project

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

Why Jekyll

  1. Ruby-based: Jekyll is written in Ruby, and it utilizes the Liquid template engine to process templates and content.
  2. Markdown and HTML: Jekyll supports both Markdown and HTML for content creation. Markdown is often preferred for its simplicity and readability.
  3. 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.
  4. 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.
  5. Free deployment: use Jekyll together with Github Pages / Firebase / Cloudflare Pages to get a Free Website with a domain!

Getting Started with Jekyll SSG

Find a Jekyll Theme that you love!
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, matomo or Plausible.

Where can I get favicons for Jekyll?