Set Up Hugo with Errorist Theme

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install wdiff tree -y

wget https://github.com/gohugoio/hugo/releases/download/v0.74.3/hugo_extended_0.74.3_Linux-64bit.tar.gz

tar -zxf hugo_0.74.3_Linux-64bit.tar.gz 
sudo cp hugo /usr/local/bin/

hugo version

cd /mnt/c/Users/<YOUR WINDOWS USER NAME>

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install wdiff tree -y

wget https://github.com/gohugoio/hugo/releases/download/v0.74.3/hugo_extended_0.74.3_Linux-64bit.tar.gz

tar -zxf hugo_0.74.3_Linux-64bit.tar.gz 
sudo cp hugo /usr/local/bin/

hugo version

cd /mnt/c/Users/<YOUR WINDOWS USER NAME>

sudo cp ~/Downloads/hugo_extended_0.74.3_macOS-64bit/hugo /usr/local/bin/
hugo version

git --version

sudo port install wdiff tree

sudo cp ~/Downloads/hugo_extended_0.74.3_macOS-64bit/hugo /usr/local/bin/
hugo version

git --version

sudo port install wdiff tree

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install git wdiff tree -y

wget https://github.com/gohugoio/hugo/releases/download/v0.74.3/hugo_extended_0.74.3_Linux-64bit.tar.gz
tar -zxf hugo_0.74.3_Linux-64bit.tar.gz 
sudo cp hugo /usr/local/bin/

hugo version

sudo apt-get update
sudo apt-get upgrade -y
sudo apt-get install git wdiff tree -y

wget https://github.com/gohugoio/hugo/releases/download/v0.74.3/hugo_extended_0.74.3_Linux-64bit.tar.gz
tar -zxf hugo_0.74.3_Linux-64bit.tar.gz 
sudo cp hugo /usr/local/bin/

hugo version

Setup Errorist

Clone the bootstrapping project from GitHub, change into the project directory, and start Hugo server:

git clone --recurse-submodules git@github.com:tvendelin/errorist-bootstrap.git
cd errorist-bootstrap
hugo server -D

In your browser, open http://localhost:1313. Welcome to your new website! It contains the manual (and the instructions to remove it). The Errorist Manual is also available on this site. But for now, let’s briefly discuss language learning combined with blogging.

Leave the Hugo server running and open another terminal window or tab. Go to your project directory. Create a new section at your website and your first blog post in one command:

hugo new -k page blog/test-post

The new section blog and the new page bundle are located under kontent directory. It is called page bundle rather than just page, because it is a directory that includes a few files. The main file in a bundle is kontent/blog/test-post/index.md, so let’s add some content there:

---
title: "Getting my Feet Wet with Errorist"
date: 2020-08-05T11:28:38+02:00
description: My test post description
draft: true
---

The articles, blog posts, etc. are written using a plain text editor. The
special parts of you texts – headings, lists, links, images, blockquotes – are
marked up with a simple notation called Markdown. For example, once I put an
empty line after this text, it will be interpreted as a new paragraph.

Notice you can read everything almost as easily as on a webpage that is created
based on your Markdown writings. Marking a text as a header or a subheader is
quite easy:

# One Pound Sign Makes the Biggest Header (H1 in HTML)

To create up to five levels of subheaders you just need to add more pound signs.
This is the next level of a subheader:

## Two Pound Signs Make a Second-Level Subheader

To add _emphasis_ to some part of a text, put it between underscores, and to
make it **bold**, put it between two asterisks on each side.

To block-quote some text, like your grammar exercise, prepend each paragraph
with `>` sign:

>When illustrating some grammar concepts, you might want to highlight some
>~~common misspellings~~,
and the **correct spelling** as well. You can put the misspelled text between
two tilde characters on both sides, and it will appear red and crossed out.
Marking text as **bold** within a blockquote will make it green, bold and
italic. The latter is just styling specific to Errorist.
>
>To continue a blockquote over a paragraph boundary, use the `>` sign on the
>blank line and the beginning of the next paragraph.

To add an external link, write [Link to Google](http://google.com).

To add a link to a page in your website (`/manual/short` in our example), write
[Link text]({{< ref "/manual/short" >}})

When using this form, the link will be checked for existence by `hugo`, so your
site is guaranteed to have no dead internal links.

This is how you will be writing your blog posts. The top part (between triple dashes) holds some parameters of your page and is called front matter. The text of the page itself is the rest of it.

Save the file, and look at http://localhost:1313 page again. You will notice the ‘Blogs’ section link on the left, and in a few clicks you will reach the page you’ve just created. Now compare the web page to the text that you have copied and pasted from this one, and you will easily see how one maps to another. Simple, right?

Exercise as a Block of Clickable Tabs

Clickable tabs allow you to include your grammar exercises, showing either the original task or your solution, or the correct solution, or the solution with corrections, but one at a time. This is useful should you wish to revisit a particular topic in the future.

So let’s create one. In a page bundle, create a directory myhomework (the name is arbitrary):

mkdir kontent/blog/test-page/homework

In this directory create four files as shown in the following code snippets. Here, the names are important. If you are experiencing the ‘writer’s block’, here’s example contents for the said files:

kontent/blog/test-page/homework/10_task.txt:

Señor Rodriguez ... católico, pero ... muerto. 
Señor Díaz ... vivo, pero hoy no ... católico.

kontent/blog/test-page/homework/20_mysolution.txt:

Señor Rodriguez es católico, pero es muerto. 
Señor Díaz está vivo, pero hoy no es católico.

kontent/blog/test-page/homework/30_solution.txt:

Señor Rodriguez era católico, pero está muerto. 
Señor Díaz está vivo, pero hoy no está católico.

kontent/blog/test-page/homework/40_corrections.txt:

Señor Rodriguez ~~es~~ **era** católico, pero ~~es~~ **está** muerto. 
Señor Díaz está vivo, pero hoy no ~~es~~ **está** católico.

The ~~ is markdown that will be converted into <del> HTML tag, and ** will become the <strong> tag.

Back to our tabs. Your page bundle structure will now look like this:

kontent/blog/test-page
├── homework
│   ├── 10_task.txt
│   ├── 20_mysolution.txt
│   ├── 30_solution.txt
│   └── 40_corrections.txt
├── index.md
├── index.ru.md
└── main-img

Add the following at the bottom of kontent/blog/test-page/index.md and kontent/blog/test-page/index.ru.md files:

{{< tabs_bq "homework" >}}

If you look at your test page now, you will see the clickable tabs at the bottom, showing our fictional homework exercise.

Here’s a brief explanation how it works.

The *.txt files in the homework directory are read in alphabetical order, and each becomes a tab. The number at the beginning of a tab file name is for sorting, so that 10_task.txt appears before 40_corrections.txt. To change the order, change the numbers.

The name of a tab is the file name stripped of its number_ prefix and .txt suffix, so 10_task.txt becomes task. The names of the tabs will be translated into languages your site supports, if there are respective entries in localization file (see the documentation for details), or will be displayed ‘as is’, should that not be the case. The entries for ’task’, ‘mysolution’, ‘solution’ and ‘diff’ are already included.

Finally, you are not required to provide all of the aforementioned files, if you don’t want to.

Using an Archetype

A skeleton for a blog article with a grammar exercise can be created using what’s called an archetype, a kind of blueprint for a new page:

hugo new -k langblog blog/señores-vivos-y-muertos

The archetype name in the example above is langblog. The command creates a page stub for each supported language, a homework directory, and four empty files in it. This is handy, since now you just need to used tab-completion instead of remembering the names of the files. If you wish to include more than one tab block with exercises, just change into page bundle directory and copy the homework directory recursively:

cp -R homework another_homework_task

Explore the archetypes directory in your project and read the documentation for details.

wdiff

The exercise in our example is very short for the sake of explanation, so adding some Markdown symbols to highlight the corrections didn’t seem to be a particularly gruelling task. In reality, however, the texts of the exercises will be much longer, of course. Notice that the corrections can be determined based on the other two files: the one with your solution (potentially containing errors), and the solution. There must be a way to calculate the difference, right?

This can be done with a program called wdiff. Not as famous as its cousin, diff, it does exactly what we want - calculating word-by-word difference between two text files:

wdiff -w '~~' -x '~~' -y '**' -z '**' 20_mysolution.txt 30_solution.txt

renders

Señor Rodriguez ~~es~~ **era** católico, pero ~~es~~ **está** muerto.
Señor Díaz está vivo, pero hoy no ~~es~~ **está** católico.

which is identical to the contents of 40_diff.txt. The options -w, -x, -y, -z denote the start of the deletion, the end of the deletion, the start of the insertion and the end of the insertion, respectively. Since the command is quite a mouthful, and is likely to be used very repetitively, it makes sense to create an alias in .bashrc (Linux) or .bash_profile (Mac OS X) by adding the following at the bottom:

alias mddiff="wdiff -w '~~' -x '~~' -y '**' -z '**'"

Close and re-open the terminal program for changes to take effect. From now on, to produce the file with corrections, use the alias and redirect the output:

mddiff 20_mysolution.txt 30_solution.txt > 40_diff.txt

Cooperating with Your Teacher

So far we have been considering your (the student’s) benefits, but there are some for your teacher as well.

What happens when you send your homework to your teacher? She goes through your texts, manually highlighting your errors, corrects them, and probably highlights the corrections. But wait, we’ve just discussed a better way to do it! So, all your teacher needs to do now, is to send you just the solution and, perhaps, some comments on your errors (but in a separate file or the e-mail body). You can then calculate the difference, and redirect it into your blog - that’s it!

And how do you think that exercise has been created in the first place? It would be a safe bet to assume, that your teacher wrote a normal text first (essentially, the solution to the exercise), and only then punched the holes in it, making it a grammar exercise. So, no extra effort is required for creating ’the solution’ – just ask your teacher to create the exercises as plain text files, separating paragraphs with empty lines, and to keep the text without the gaps in a separate file.

If your teacher has got other blogging students, the time savings on checking the students’ homework might become quite considerable. This can be further optimized, though, by

Using Git and GitHub for Homework Management

I’ve wrote a series of articles on that, so this is just to give you a taste of it.

I’ve created a demo repository with just a single exercise. Clone it and change into the directory created:

git clone https://github.com/tvendelin/language-exercise-example
cd language-exercise-example

The directory contains a single exercise file, indonesian_pronouns.md (the README.md just describes the repository itself). However, there is another dimension to that. Running

git log --pretty=reference -- indonesian_pronouns.md

will reveal the following:

2198844 (Corrected exercise indonesian_pronouns.md, 2020-05-16)
3f43247 (Completed exercise indonesian_pronouns.md, 2020-05-16)
802e45b (Created an exercise on personal pronouns., 2020-05-16)

Git (if you’ve never met before) is a version control system. That is, it is used to create and keep the snapshots of text files at certain points in time. These are called commits, and the command we’ve just run displays the commit history for a particular file, indonesian_pronouns.md. Each commit is identified by a checksum (left) and is supposed to have a meaningful commit message (on the right, in brackets). At any time git can display the contents of a file at the time of a particular commit. This, for example

git show 802e45b:./indonesian_pronouns.md

will output the oldest commit with the task. Notice that you need to provide the path, so it’s ./indonesian_pronouns.md rather than just indonesian_pronouns.md. To populate the tab files now, you will need to run git show on each commit in turn, and redirect the output to the respective files.

This may seem to be a tad more complicated than our previous scenario with wdiff, but it will help you and your teacher to keep things organized much better. This is where GitHub – a free online service hosting git repositories – comes in. The details are covered here , so I won’t be repeating myself.

The Next Steps and Further Reading

The next step would be scratching your head a bit in order do decide how do you prefer to organize the content at your website, as it likely won’t be limited to blogging about learning a particular language. This article covers only language-learning aspects of it, but there are a few more things to do. For that, refer to the Errorist documentation.

Once you are done, create an account at GitHub , create a repository <YOUR USERNAME>.github.io, enable GitHub pages in settings, build your site, commit and push it to GitHub.

To learn more about Git, read Pro Git online book.

Also read the Hugo documentation though it might be a tough read for a beginner.

At this point I wish you best of luck. Report success in the comments below.