Jekyll

Jekyll is a static site generator. GitHub Pages is a free hosting that supports Jekyll. The size limit is 1 GB.

To create a site, you need to register on GitHub

https://github.com/

and install

Git - https://git-scm.com/download/win

Jekyll - https://jekyllrb.com/docs/installation/windows/

Creating a site

Note: use your GitHub username

Go to the command line:

Win+R cmd

git init username.github.io
cd username.github.io
git checkout --orphan main
jekyll new --skip-bundle .
bundle install
git add .
git commit -m "first commit"
git remote add origin https://github.com/username/username.github.io.git
git push -u origin main

Your site will be located at https://username.github.io/

Source: https://docs.github.com/en/pages/setting-up-a-github-pages-site-with-jekyll/creating-a-github-pages-site-with-jekyll

Information on the site

In _config.yml fill the title, author, email, url, description (you can delete it). In about.markdown write a description of the site.

Creating a page

Create .md file in the site folder. For example, page.md
Then the page will appear on your site at https://username.github.io/page
You can put the file in the folder named folder. Then a page will appear on your site at https://username.github.io/folder/page

Creating a post

https://jekyllrb.com/docs/posts/

Formatting

01. Bold text: **bold text**
02. Italics: *italics*
03. Title (in the beginning):
---
comments: true
title: Title
---
04. Heading: # heading text
05. Subheading: #### subheading text
06. New paragraph: empty line
07. Highlight a link: <link>
08. Link: [text](link)
09. Link to site page: [text](/folder/page)
10. Link back and forth:
text<a href="#note" id="note-back">†</a>

<a href="#note-back" id="note">†</a> text of the note
11. Link to place in text:
[Place](#place)

<a id="place"></a>
12. Table of Contents:
#### Table of Contents
[Introduction](#introduction)

<a id="introduction"></a>
#### Introduction
13. Line break: <br>
14. Blank line (double line break): <br><br>
15. Note:
text[^1] text[^2]

[^1]: note text

	note text

[^2]: note text
16. Quote:
> quote
>
> the rest of the quote
17. Small text: <sub>text</sub>

Code block - https://docs.github.com/ru/get-started/writing-on-github/working-with-advanced-formatting/creating-and-highlighting-code-blocks

https://www.markdownguide.org/basic-syntax/

Adding picture

Let’s say you put image.png into the folder named images.

To place this image on the page:

![Picture description](/images/image.png)

In the center:

{:refdef: style="text-align: center;"}
![Picture description](/images/image.png)
{: refdef}

With a link:

{:refdef: style="text-align: center;"}
[![Picture description](/images/image.png)](link)
{: refdef}

HTML:

{:refdef: style="text-align: center;"}
<img src="/images/image.png" width="500">
{: refdef}

<div style="display: flex; justify-content: space-between; flex-wrap: wrap;">

<div style="text-align: center;">
  <img src="/images/look-see-2.jpg" style="max-height: 250px; max-width: 100%; height: auto;">
  <br>
  (a)
</div>

<div style="text-align: center;">
  <img src="/images/look-see-3.jpg" style="max-height: 250px; max-width: 100%; height: auto;">
  <br>
  (b)
</div>

</div>

Updating the site

Win+R cmd

cd username.github.io
git add .
git commit -m "new commit"
git push

You can create .bat file and put these commands inside. Then the commit can be done with two clicks. To stop the command line from closing immediately after executing commands, add pause at the end.

Starting the site locally

To avoid errors, you need to add webrick to Gemfile:

cd username.github.io
bundle add webrick csv logger base64

Starting the site:

cd username.github.io
bundle exec jekyll serve

Open given address.

Paste in _config.yml:

header_pages:
  -about.markdown

Changing title size

Go to minima folder. On Windows it is located in user folder:

.local/share/gem/ruby/3.4.0

Go to _layouts folder. Copy (Ctrl+C) page.html.

Create _layouts folder in username.github.io. Paste (Ctrl+V). Edit page.html with Notepad++. Remove

 class="post-title"

Referencing the source

Sometimes I post some texts. In academia, it is enough to write a citation. But if there is an ebook online, that’s what you really should reference.

I like to put the link at the top. Default post layout always puts the title in the top, so I copied post.html into _layout folder and removed the piece of code that creates the title.

Markdown file of my posts looks like this:

---
layout: post
tag: Readings
comments: true
title: Title of the text
---

Source: [Source title](link to the source)
<br><br>

# Title of the text

Comments

https://help.disqus.com/en/articles/1935528-jekyll-installation-instructions

Underlinings and marginalia

There are people who leave pesky underlinings and margin notes in their books. There’s a way to reproduce them in posts, and do them less intrusive for other readers.

<span class="underlining">text</span><span class="marginalia">comment</span>

Add this script to post.html:

Expand


  <style>
    .post-content {
      position: relative;
    }

    .marginalia {
      position: absolute;
      right: -250px;
      width: 200px;
      padding: 10px;
      background-color: rgb(30,30,30);
      border-left: 3px solid rgb(80,80,80);
      border-radius: 4px;
      font-size: 0.9em;
      color: rgb(210,210,210);
      opacity: 0;
      transform: translateX(20px);
      transition: all 0.3s ease;
      margin-top: -10px;
    }

    .marginalia.visible {
      opacity: 1;
      transform: translateX(0);
    }

    .toggle-annotations {
      position: absolute;
      top: 20px;
      right: 20px;
      padding: 8px 16px;
      background-color: #007bff;
      color: white;
      border: none;
      border-radius: 4px;
      cursor: pointer;
      transition: background-color 0.2s;
      z-index: 1000;
    }

    .toggle-annotations:hover {
      background-color: #0056b3;
    }

    .underlining {
      text-decoration: none;
      transition: text-decoration 0.3s ease;
    }

    .underlining.visible {
      text-decoration: underline;
      text-decoration-color: crimson;
      text-decoration-thickness: 3px;
	  text-underline-offset: 6px;
    }

    @media (max-width: 1200px) {
      .toggle-annotations {
        display: none;
      }
    }
  </style>

  <script>
    window.addEventListener('DOMContentLoaded', function() {
      const marginalia = document.querySelectorAll('.marginalia');
      const button = document.getElementById('annotationsButton');
      
      if (marginalia.length > 0) {
        button.style.display = 'block';
      }
    });

    let annotationsVisible = false;

    function toggleAnnotations() {
      const marginalia = document.querySelectorAll('.marginalia');
      const underlinedText = document.querySelectorAll('.underlining');
      const button = document.querySelector('.toggle-annotations');
      
      annotationsVisible = !annotationsVisible;
      
      marginalia.forEach(note => {
        note.classList.toggle('visible', annotationsVisible);
      });

      underlinedText.forEach(text => {
        text.classList.toggle('visible', annotationsVisible);
      });

      button.textContent = annotationsVisible ? 'Hide Annotations' : 'Show Annotations';
    }
  </script>

MathJax

1) Download zip file.

https://github.com/mathjax/MathJax/releases

2) Put MathJax files into assets/js/mathjax/

3) Create _includes/mathjax.html

<script>
  MathJax = {
    tex: {
      inlineMath: [['$', '$'], ['\\(', '\\)']],
      displayMath: [['$$', '$$'], ['\\[', '\\]']]
    },
    svg: {
      fontCache: 'global'
    }
  };
</script>
<script type="text/javascript" id="MathJax-script" async
  src="/assets/js/mathjax/tex-mml-chtml.js">
</script>

4) Add to post and page layouts in the very end:

{% if page.use_math or page.math %}
  {% include mathjax.html %}
{% endif %}

5) Enable when needed:

---
layout: page
comments: true
math: true
title: Jekyll
---

6) Now this

$ E_0 = mc^2 $

should render like this

$ E_0 = mc^2 $

My theme

theme.zip

Also add:

1) assets/main.scss

---
# Only the main Sass file needs front matter (the dashes are enough)
---

@use "minima-dark";

2) assets/fonts/Skolar Sans

Skolar Sans.zip

3) Dart Sass

Gemfile

gem "jekyll-sass-converter", "~> 3.0"
gem "sass-embedded", "~> 1.60"

bundle install

4) GitHub Actions

Navigate to your repository on GitHub.

Go to

Settings -> Pages

Build and deployment -> Source -> GitHub Actions

.github/workflows/jekyll.yml

name: Jekyll

on:
  push:
    branches: ["main"]
  workflow_dispatch:

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

concurrency:
  group: "pages"
  cancel-in-progress: false

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4

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

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

      - name: Build with Jekyll
        run: bundle exec jekyll build --baseurl "$"
        env:
          JEKYLL_ENV: production

      - name: Upload artifact
        uses: actions/upload-pages-artifact@v3

  deploy:
    environment:
      name: github-pages
      url: $
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v4