Contents - Introduction - Create a New repository - Select a theme - Read the theme blog - Edit the contents of your repository - Create a new post - Publish post - Resources
Introduction
Looking for a Jekyll template theme to use for writing my blogs, I started by looking at the Jekyll officially supported themes, but as I wanted a theme that could handle Tex/LaTex/MathML codes for math, I ended up searching here and here. In the end I decided to use the So Simple theme by Michael Rose. When writing this in December 2019 the So Simple theme was at version 2. When attempting to update Jekyll and So Simple, I discovered that version 3 of the So Simple theme was differently constructed. The installation and customisation of the So Simple theme as described in this blog is thus outdated.
In this blog I describe how I set up Jekyll with the So Simple theme. If you need to set up Jekyll and a text editor for working with your blogs, check this blog. If you want to understand a bit more about the code structure of Jekyll and markdown files, and publish a blog on GitHub, you could read this blog.
Create a New repository
As I will use a new theme (So Simple) for this blog, I chose to create a new repository. As described in an earlier blog, I do it using GitHub desktop.app. In the main menu of GitHub desktop.app, select
In the dialog window that opens, enter a Name and a Description, check the box for ‘Initialize this repository with a README’, and leave the alternative for ‘GitIgnore’ and ‘License’ with None. Write the local path manually to create a (non-existing) repository. Click the button, and then click Publish repository in top menu/tab. In the window that opens, un-check ‘Keep this code private’, and click .
Select a theme
Select a Jekyll theme you like, either from the list of officially supported themes, or from other web pages offering Jekyll themes, like jekyllthemes.io or jekyllthemes.org. You can also search directly in GitHub.com. If you are looking for an easy solution, you could use the default Jekyll theme [minima], that I used for creating my first blog.
When downloading your chosen theme, you will be directed to the GitHub repository for that theme. Click the button, and select either alternative. If you have a local clone of your GitHub.com account it is probably simpler to clone, GitHub.com will ask if you allow opening GitHub desktop and clone the theme. If you select ‘Download ZIP’, wait for the download to finish, unzip, and then copy the complete content of the theme folder into the repository folder you just created with GitHub desktop.app. The _config.yml file should be directly under your repository folder. You are copying/moving to the correct folder if your system asks if the README.md should be overwritten (whether or not to overwrite is your choice, you can anyway edit README.md later).
Now you should have a repository set up with a Jekyll theme of your choice. Open the Terminal.app (see this blog post if you are not familiar with the Terminal). To change directory (cd) to your newly created repository, write $ cd at the prompt, followed by the local path to your repository. Instead of writing the path, you can just drag the path from a Finder window to the Terminal prompt, and it will be pasted automatically:
$ cd /local/path/to/repository
List (ls) the content of your repository using the Terminal:
$ ls
The Terminal window will show the files and folders in your repository. They should include _config.yml, README.md and Gemfile, and more. To install all the dependencies (gems) defined in the Gemfile start by executing the command:
$ bundle install
You should now be able to use Jekyll to create a local server and view the theme content in your web browser. Write the following command at the Terminal prompt:
$ bundle exec jekyll serve
Read the theme blog
Your theme default (instruction) pages should now be up and running as a local server. To read them copy and paste the url returned in the Terminal window (default is ‘http://127.0.0.1:4000’). All themes (that I have tested at least) contain information related both to how to execute Jekyll to serve up the theme, as well as instructions and hints for how to customize the theme.
Dependent on your theme, you might get warnings, or even errors preventing the theme to be served up. Themes created for Jekyll 3.5.0 or earlier, will use ‘gems’ instead of ‘plugins’ in _config.yml, and dependent on your version of Jekyll and the theme, you might need to edit _config.yml. Other syntax changes between different versions of Jekyll and your theme might cause other problems. To solve these problems, you need to use a text editor. In another blog, I introduced Atom.
Edit the contents of your repository
Start Atom (or another text editor if you prefer), and go via the menu:
The New Window will open with some default tabs, including the Welcome Guide. Click it and select ‘Open a Project’, and then click the button that also says Open a project. Navigate to the folder containing the repository you created above, and select the repository folder to be your Project.
In the Atom Project pane that opens you should see all the files that you put in the repository when you copied the Jekyll theme that you downloaded. If you got a warning saying ‘gems’ configuration option has been renamed to ‘plugins’, click on _config.yml to open it, and replace ‘gems’ with ‘plugins’.
Create a new post
Atom is advertised as ‘A hackable text editor’, and there are several packages available for Atom that support writing blogs. In another blog I describe how to install packages. The key package for writing posts using markdown is .
By default, Jekyll expects posts to be located in the repository sub-folder _posts, with each post in a separate markdown file. The name of the file must start with the date in the form YYYY-MM-DD-. followed by any identification. The full file name of a post thus becomes YYYY-MM-DD-‘your-identifier’.markdown
When working on a new post, you do not want it to appear in the online blog, and you should thus not put it in _posts folder until it is ready. By default Jekyll ignores any files in the sub-folder _drafts. When writing a new post you should hence have your manuscript in the _drafts folder.
To start a new post using Atom, go via the main menu:
In the Add New Draft window that opens, the folder _drafts is already set, and you only need to give a Title. The title should only be the content identifier, do not write the YYYY-MM-DD-, that will be automatically added when using for publishing your blog.
Atom will generate a markdown file with some basic YAML front matter, but it will probably not be adjusted to your Theme. You need to check in the theme documentation and edit the YAML.
When your are finished with the blog, use for publishing your post:
Publish post
This will transfer your file to the _posts folder, and at the same time add the required prefix YYYY-MM-DD-.
If your server is up and running in “–watch” mode, you should be able to see your new post in your web browser. If not, you need to stop ctrl-x and restart the Jekyll server:
$ jekyll serve –watch
Note that your theme might need another Jekyll command for serving up, if jekyll serve –watch does not work, look at the theme’s documentation.
When your are ready with the new post, you need to upload it. To use GitHub.com for publishing online is described in an earlier blog
Resources
Set up blog tools: Jekyll and Atom another blog by me
Setup GitHub pages another blog by me