First post!

Hello world, this is my first post!

Like many others, I start with some remarks on how this blog is set up. I'm using the static site generator hugo and the theme beautifulhugo. Since installation was straightforward, as described on the hugo website, I will only list a few remarks, as a memory aid, on how I tweaked details of the layout.

I removed the vertical bar underneath the title on the front page by deleting line 41 in \layouts\partials\header.html and modified the layout of meta information for posts in \layouts\partials\post_meta.html and \i18n\en.yaml. Then I applied the following changes in \static\main.css:

Played with the font size in line 5 but ultimately stayed with 18px. While a smaller font size looks nicer, speed of reading is negatively impacted by having too many words per line.
Played with paragraph spacings in lines 27, 30 and 39
Added new formating for horizontal rules in lines 65-73
Letterspacing in NavBar reduced to 0px in line 162
Multi-level navigation links changed from uppercase to capitalize in line 275
Text-align for multi-level navigation links changed from center to left in line 293
Post-preview border (bottom) increased to 8px in line 355
Changed spacing around tags in lines 448, 449, 454, and 460

Syntax highlighting relies on Chroma, not Pygments, using the following options in config.toml:

pygmentsUseClassic = false
pygmentsUseClasses = true
pygmentsCodeFences = true
pygmentsCodefencesGuessSyntax = true
pygmentOptions = "linenos=inline"

Currently I'm using the style igor generated by hugo gen chromastyles --style=igor > static\css\syntax.css. Based on various Internet finds I redesigned the codeboxes in \static\css\codeblock.css:

 1/* --- Code blocks --- */
 2
 3.chroma .ln {
 4  margin-right: 0.8em; /* space between ln and code */
 5  padding: 0.5em 0.5em 0.45em 0.5em; /* margin around ln */
 6  background-color: #f3f3f3;
 7  color: #b4b4b4;
 8  -webkit-user-select: none;
 9  -moz-user-select: none; 
10  -o-user-select: none;  
11}
12pre {
13  font-size: 14px;
14  line-height: 1.5em; /* should correspond to padding around ln */
15  margin: 1.5em 0em 1.5em 0em; /* margin around code box */
16}
17pre code {
18  white-space: pre;
19  overflow: auto;
20}
21pre.highlight, .highlight > pre, td.code pre {
22  background: #fdfdfd;  
23  border-left: 3px solid #d0d0d0;  
24  border-right: 1px solid #d0d0d0;
25  border-top: 1px solid #d0d0d0;
26  border-bottom: 1px solid #d0d0d0;
27  border-radius: 5px;
28  padding: 0.3em 0 0.3em 0;
29}

Inline math such as $\sum_{n=1}^{\infty} 2^{-n} = 1$ with $\KaTeX$ works if markup: mmark is added to the front matter of the post and the inline delimiters $$ ... $$ are used (as opposed to the standard $\LaTeX$ ones $ ... $ ).

I wanted to have an optional Table of Contents for longer posts and found several hacks here and here. The following changes/additions were needed:

Added a new partial toc.html
Added {{ partial "toc" . }} as line 4 of \layouts\_default\single.html
Added lines 819-866 to \static\main.css
Tweaked the formatting
Front matter of post must contain toc: true
Does unfortunately not work with mmark markdown

The website is under Git version control. A commonly used branching workflow in Git is to create a new code branch for each new feature, bug fix, or enhancement. These are called Feature Branches. Each branch compartmentalizes the commits related to a particular feature. Once the new feature is complete – i.e. a set of changes has been committed on the feature branch – it is ready to be merged back into the master branch (or other main code line branch depending on the workflow in use). Here are the commands to create a new branch, make some commits, and merge it back into master:

$ git checkout master
$ git branch <new-branch>
$ git checkout <new-branch>

# ...develop some code...

$ git add –A
$ git commit –m "Some commit message"
$ git checkout master
$ git merge <new-branch>
$ git push -u origin master

Hosting on GitHub works as follows. Two repos are created on GitHub:

website-github contains Hugo's content and other source files
joachimweise.github.io contains the fully rendered version of the Hugo website.

A git submodule is created through git submodule add -b master git@github.com:joachimweise/joachimweise.github.io.git public. Now when I run the hugo command to build the site to public, the created public directory will have a different remote origin (i.e. hosted GitHub repository). By running the following script through ./deploy.sh I can send changes to joachimweise.github.io:

#!/bin/sh

# If a command fails then the deploy stops
set -e

printf "\033[0;32mDeploying updates to GitHub...\033[0m\n"

# Build the project.
hugo # if using a theme, replace with `hugo -t <YOURTHEME>`

# Go To Public folder
cd public

# Add changes to git.
git add .

# Commit changes.
msg="rebuilding site $(date)"
if [ -n "$*" ]; then
	msg="$*"
fi
git commit -m "$msg"

# Push source and build repos.
git push origin master

I was facing issues with this setup when I accidentally deleted the content of the loca /public folder, which led to error messages like fatal: in unpopulated submodule 'public'. The following approach seems to help: delete references to the submodule in .gitmodules, .git\config and .git\modules. Then remove the public folder and execute git rm -r public, then add the submodule again as described above.

Hosting with Gitlab seems to me more straightforward. A .gitlab-ci.yml file in the root directory of the Hugo site configures the GitLab CI on how to build the site:

image: monachus/hugo

variables:
 GIT_SUBMODULE_STRATEGY: recursive

pages:
 script:
 - hugo
 artifacts:
   paths:
   - public
 only:
 - master

Next, a new repository is created on GitLab. It is not necessary to make the repository public. In addition, we may want to add public to our .gitignore file, as there is no need to push compiled assets to GitLab or keep your output website in version control.

# initialize new git repository
git init

# add /public directory to our .gitignore file
echo "/public" >> .gitignore

# commit and push code to master branch
git add .
git commit -m "Initial commit"
git remote add origin git@gitlab.com:joachimweise/my-hugo-site.git
git push -u origin master

That’s it! We can then follow the CI agent building our page.

code website

See also