Basic Jekyll site

Create a Jekyll site template:

gem install jekyll bundler
jekyll new my-new-site
cd my-new-site
bundle exec jekyll serve

Asciidoc

Default config supports only the Markdown; Asciidoc requires a plugin.

Add jekyll-asciidoc and asciidoctor-diagram on Gemfile and _config.yml:

Gemfile.

group :jekyll_plugins do
  gem 'jekyll-asciidoc'
  gem 'asciidoctor-diagram'
  gem "jekyll-feed", "~> 0.12"
end

_config.yml.

plugins:
- jekyll-asciidoc

Minima theme from github

Adding custom scripts to _includes/custom-head.html allows adding them globally to all the site pages without editing the theme. The current version of the "minima" theme (2.5) does not support including custom-head.html (https://github.com/jekyll/minima/issues/472), and the GitHub master branch is required.

In Gemfile replace the 2.5 version

gem "minima", "~> 2.5"

with githuib master branch:

gem "minima", github: "jekyll/minima"

Latex math equations

  1. Add MathJax scripts to _includes/custom-head.html to include them in all the pages of the site

  2. Add :eqnums: and :stem: latexmath to the header of asciidoc files.

_includes/custom-head.html.

<script type="text/x-mathjax-config">
MathJax.Hub.Config({
    TeX: {
    equationNumbers: { autoNumber: "AMS" },
    tagSide: "right"
    },
    tex2jax: {
    inlineMath: [ ['$','$'], ["\\(","\\)"] ],
    displayMath: [ ['$$','$$'], ["\\[","\\]"] ],
    processEscapes: true
    }
});
MathJax.Hub.Register.StartupHook("TeX AMSmath Ready", function () {
    MathJax.InputJax.TeX.Stack.Item.AMSarray.Augment({
    clearTag() {
        if (!this.global.notags) {
        this.super(arguments).clearTag.call(this);
        }
    }
    });
});
</script>
<script type="text/javascript" charset="utf-8"
src="https://cdn.jsdelivr.net/npm/mathjax@2/MathJax.js?config=TeX-AMS_CHTML">
</script>

_posts/2020-01-01-my-example-post-with-equations.adoc.

= My asciidoc post title
:eqnums:
:stem: latexmath

stem:[\sqrt 4 = 2]

\(\sqrt 4 = 2\)

latexmath:[$$C = \alpha + \beta Y^{\gamma} + \epsilon$$]

\(C = \alpha + \beta Y^{\gamma} + \epsilon\)

This is a numbered equation \eqref{myequation}
[stem]
++++
\begin{equation}\label{myequation}
c^2 = a^2 + b^2 + 5
\end{equation}
++++

This is a numbered equation 1 \[ c^2 = a^2 + b^2 + 5~(1) \]

PlantUML diagrams

Set default output directory for diagram images, generated from asciidoc:

_config.yml.

asciidoctor:
  attributes:
    - imagesdir=/assets/images/
    - imagesoutdir=assets/images

[plantuml, diagram-classes, png]
....
A --|> B : ablink
B --|> C : bclink
A --|> C : aclink
....

diagram