color-tomato-theme/README.en.md

# [Color tomato](README.md)

Two Jekyll themes to decorate static websites. The color variant was written earlier
using AngularJS and Material, this was the design of the previous version of my blog.
Then a lightweight single-color variant was written using only HTML and CSS, the
appearance resembles the default design theme on GitHub Pages. Both themes supplement
each other and are similar to each other, commonalities and differences between them
are marked in the list of features.

- Color tomato — color selection during the build.
- [Older tomato](https://git.org.ru/golovin/older-tomato-theme/src/branch/master/README.en.md) — lightweight decoration theme.

### Features

- [x] Responsive layout.
- [x] User JS and CSS files in the head block of HTML pages.
- [x] SEO-markup using JSON-LD and Open Graph.
- [x] Switch between two languages and two tomato themes.
- [x] Map of site pages with their translations in XML format.
- [x] Simple 404 page for non-existing URLs.
- [x] Redirection to site root from folders, without `index.html`.
- [x] Fonts: Roboto for text and JBMono for code blocks.
- [x] Tomatoes: PNG, JPG 120x120, SVG 64x64, ICO 32x32.
- [ ] Color selection during the build, green is the default color.
- [ ] Scroll-to-top button in Material style.

### Colors

The theme color can be selected from the list of colors of the Material library. Each
color goes with a palette of its shades, that are used to design the entire site, green
is the default color. Only syntax highlighting in code blocks and custom JS and CSS
files are independent of color. In the old version of the blog, the palette could be
selected from a drop-down menu by a button on the client. Now the palette is selected
once at the build time — this noticeably simplifies the DOM tree and eases the client.

<details>
<summary>List of colors</summary>

- [ ] red
- [ ] pink
- [ ] purple
- [ ] deep-purple
- [ ] indigo
- [ ] blue
- [ ] light-blue
- [ ] cyan
- [ ] teal
- [x] <b>green</b>
- [ ] light-green
- [ ] lime
- [ ] yellow
- [ ] amber
- [ ] orange
- [ ] deep-orange
- [ ] brown
- [ ] grey
- [ ] blue-grey
</details>

### Installation

Run the script from the theme folder, build the *gem* package and install it.

```shell
rm color-tomato-theme-1.0.1.gem
gem build color-tomato-theme.gemspec
sudo gem install --local color-tomato-theme-1.0.1.gem
```

### After build

The site can be built using the `jekyll build` command. After that, we get the `_site` folder with the
generated pages and the `assets` subfolder from the theme. We move the contents of this subfolder back
to the `_site` folder — we get shorter links, that are used in the theme. After that we bypass HTML pages
and optimize a set of tags also for shortness and for correctness. Additionally, we copy from theme the
redirection file to the root of the site for all subdirectories, if they don't contain the `index.html`
file. The script is intended for this purpose.

```shell
# optimizing gathered content
cd _site || exit
cp -r assets/* .
rm -r assets
# patterns for optimizing a set of tags
expr+=('s|layout-padding=""|layout-padding|g')
expr+=('s| class="language-plaintext highlighter-rouge"||g')
expr+=('s| class="language-java highlighter-rouge"||g')
expr+=('s| class="language-html highlighter-rouge"||g')
expr+=('s| class="language-js highlighter-rouge"||g')
expr+=('s| class="language-bash highlighter-rouge"||g')
expr+=('s|<div><div class="highlight">|<div class="highlight">|g')
expr+=('s|</pre></div></div>|</pre></div>|g')
expr+=('s|<input(.+) />|<input\1>|g')
expr+=('s|<img(.+) />|<img\1>|g')
# launching parallel processing of gathered pages and optimizing a set of tags
find . -type f -name "*.html" -printf '%p\0' | xargs -I{} -n1 -0 -P0 bash -c \
  "echo 'Optimize: {}' && sed -i -E $(printf " -e '%s'" "${expr[@]}") '{}'"
# transition to the site root for directories without a main page
find . -type d -exec cp -n return.html {}/index.html \;
rm -r return.html
```

### Directory structure

Folder with the Jekyll site should contain two mandatory files: with dependencies `Gemfile`
and with parameters `_config.yml` — all other files are the site content itself. This theme
is written with the expectation, that the site contents is separated into two subdirectories
by language and consist of publications and main pages, where the main pages are lists of
publications with short descriptions.

```
jekyll_site
├─ ru
│  ├─ . . .    — publications
│  └─ index.md — main page
├─ en
│  ├─ . . .    — publications
│  └─ index.md — main page
├─ . . .
├─ Gemfile     — dependencies
└─ _config.yml — parameters
```

### Dependencies

`Gemfile` — a list of packages *ruby gems* to use, including locally installed ones.

```ruby
source "https://rubygems.org"
gem "jekyll"
gem "color-tomato-theme"
```

### Site parameters

`_config.yml` — a list of common parameters for the site, including parameters for the build.

```yaml
# site name for caption in footer
name: "Код с комментариями"
# footer caption for translated pages
name_translated: "Code with comments"
# URL of the site including protocol
url: "https://pomodoro.example.ru"
# subfolder of this build for relative URLs
baseurl: "/color"
# weblink in the top-left of the main pages
homepage_url: "https://git.org.ru/tolstoy.ln"
# representation of the weblink
homepage_name: "GIT.ORG.RU"
# subfolder of the alternative build,
# can be omitted, if not used
older_tomato_baseurl: ""
# time zone for ISO-8601 date format
timezone: "Europe/Moscow"
# language parameters should be specified either
# everywhere, or only on pages with translations
lang: "ru" # default, can be omitted
# author's name for SEO-markup and footer caption
author: "Толстой Л.Н."
# transliteration of the name for translated pages
author_translated: "Tolstoy L.N."
# addition to footer caption for translated pages
translation_caption: "translation from Russian"
# counter numbers for pages,
# can be omitted, if not used
live_internet: "abcdefghij"
yandex_metrika: "1234567890"
# design theme and color for the build
theme: color-tomato-theme
# default, can be omitted
color: green
# layout for the build
defaults:
  - scope:
      path: ""
    values:
      layout: default
```

### Page parameters

List of individual parameters of site pages to specify in the Front matter of the page.

```yaml
---
# page title in the page language
title: Вращаем пространственный крест
# preferably 150-160 characters in the page language
description: ниасилил, многабукаф
# comma-separated list of sections of a page in its language
sections: [Объёмные фигуры,Матрица поворота,Экспериментальная модель]
# comma-separated list of tags of a page in its language
tags: [javascript,canvas,геометрия,матрица,графика,изображение,куб]
# comma-separated list of scripts for
# this page, can be omitted, if not used
scripts: [/js/classes.js,/js/script1.js,/js/script2.js]
# comma-separated list of styles for
# this page, can be omitted, if not used
styles: [/css/pomodoro1.css,/css/pomodoro2.css]
# canonical URL of this page
canonical_url: /ru/2023/01/15/spinning-spatial-cross.html
# URL of translated page for original pages,
# or the original page for translated pages
url_translated: /en/2023/01/16/spinning-spatial-cross.html
# title of translated page for original pages,
# or the original page for translated pages
title_translated: Spinning spatial cross
# date parameters should be specified only on publication
# pages and should not be specified on main pages,
# main pages display the date the site was last built
date: 2023.01.15
# language parameters should be specified either
# everywhere, or only on pages with translations
lang: "ru" # default, can be omitted
# author's name in the page language
author: "Толстой Л.Н."
# transliteration of the author's name for original
# pages, or original author name for translated pages
author_translated: "Tolstoy L.N."
# addition to footer caption for translated pages
translation_caption: "translation from Russian"
---
```

---

© Golovin G.G., Code with comments, translation from Russian, 2021-2024