Wikipaulia

Setting up Emanote

5 min read

This is how to set up Emanote on a Linux computer (I am using Pop!_OS, but this should work on Ubuntu and derivatives too) to create a blog to host on GitHub Pages, i.e. this one.

This is a very big installation (gigabytes)!

Installing Nix (Linux)

Follow the official instructions at Installing – Emanote

It is apparently feasible on Windows (via WSL) but I haven’t tried it.

I haven’t used Nix before, and needed to do the following to install it:

curl --proto '=https' --tlsv1.2 -sSf -L https://artifacts.nixos.org/experimental-installer | sh -s -- install --no-confirm --extra-conf "trusted-users = $(whoami)"
echo "experimental-features = nix-command flakes" >> ~/.config/nix/nix.conf  # restart your terminal after this line
nix run nixpkgs#omnix -- health  # got a couple of warnings but OK to ignore them

Install Emanote

nix profile install github:srid/emanote  # answer "y" to questions

Check installation:

emanote --version

Create Blog Structure

cd
mkdir emanote              # Folder for project
cd emanote
mkdir content docs         # content = Markdown, docs = compiled site (GitHub Pages expects this)
cd content
emanote run

You can also create folders for templates and other assets (but you can do this later):

  • templates/ – custom layouts
  • static/ – static assets (images, CSS, etc.)

Emanote runs a local server and prints a URL such as:

http://127.0.0.1:34043

Open this in your browser. It live-reloads as you edit files.

Create the home page

Create the following file with the text editor of your choice:

~/emanote/content/index.md

Add Markdown for your welcome page. Mine currently looks like this:

---
title: Wikipaulia
---
 
Welcome! I'm **Paul Cleary**, a UK epidemiologist working in public health and global health. My technical interests include statistics, coding, open source software, self-hosting, global health informatics and AI.
 
## What you'll find here
 
- My[[Blog|blog]]
- Occasional[[Writing|writing]]
- Interesting[[Bookmarks|bookmarks]]
- Notes (e.g. on[[Books|reading]]) which I am starting to organise in Obsidian
 
[Email](mailto:blog@paulcleary.net) [GitHub](https://github.com/prcleary) [Letterboxd](https://letterboxd.com/rusticana/) [ORCID](https://orcid.org/0000-0001-9335-5422) [Strava](https://www.strava.com/athletes/9125693) [Zotero](https://www.zotero.org/drprcleary)
 
[Old blog](static/oldblog.html)
 
<p style="white-space:nowrap;" xmlns:cc="http://creativecommons.org/ns#" xmlns:dct="http://purl.org/dc/terms/"><a property="dct:title" rel="cc:attributionURL" href="https://prcleary.github.io">Wikipaulia</a> by <a rel="cc:attributionURL dct:creator" property="cc:attributionName" href="https://prcleary.github.io">Paul Cleary</a> is marked with <a href="https://creativecommons.org/publicdomain/zero/1.0/?ref=chooser-v1" target="_blank" rel="license noopener noreferrer" style="display:inline;">CC0 1.0<img style="display:inline!important;height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg?ref=chooser-v1" alt=""><img style="display:inline!important;height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/zero.svg?ref=chooser-v1" alt=""></a></p>

There’s YAML metadata at the start (other possible fields include date in YYYY-MM-DD format), then it’s mostly standard Markdown, with some HTML at the end.

You can link to another page by using the filename of the source Markdown file, without the “.md” file ending. You don’t need to specify a path as Emanote will find the file that is nearest in the hierarchy with that name. So to link to my blog page (Blog.md), I can use [[Blog]], or [[Blog|blog]] if I want the link to show “blog”. Note that there is a bit of extra space around links, so you may not need to add a space, e.g. My[[Blog|blog]].

Configure index.yaml

I copied the default config from: https://raw.githubusercontent.com/srid/emanote/refs/heads/master/emanote/default/index.yaml

Put it in:

~/emanote/content/index.yaml

Useful changes:

  • Change theme (see Tailwind color palette: https://tailwindcss.com/docs/colors#default-color-palette)
    Example: neutral, blue, slate, stone, etc.

  • Set:

    siteTitle: Wikipaulia
siteUrl: https://yourusername.github.io/repository-name/

  • Enable Mermaid and MathJax by adding the following under bodyHTtml.

    bodyHtml: |
  <snippet var="js.mermaid" />
  <snippet var="js.mathjax" />

Do not put #-prefixed comments in config values — they can be interpreted as tags.

Folder Structure and “Folder Notes”

Add subfolders as needed, for example:

content/
  Blog/
    2023-03-08.md

Outside each subfolder create a folder note to replace default folder content:

Blog.md

This file sits alongside the Blog/ directory.

Alternatively use:

Blog/index.md

Folder notes are useful for:

  • Section introductions
  • Custom ordering
  • Tag summaries

Look at the source of this blog for some possibilities.

Front Matter for blog pages

Structure pages using YAML front matter:

---
title: My nerdy blog page
date: 2023-03-08
order: -5
slug: my-nerdy-blog-page
tags:
  - blog
---

Notes:

  • Use ISO date format: YYYY-MM-DD
  • Naming files e.g. 2023-03-08.md works well for chronological sorting
  • order controls sidebar positioning (lower = higher up)
  • slug controls URL
  • tags allow you to group the content and have separate RSS feeds

Dates are not shown unless you use a trick - see the source for this blog.

Build the Site

From the project root:

emanote -L content/ gen docs/

Or:

cd emanote/content
emanote gen ../docs/

As mentioned the docs/ folder is required for GitHub Pages.

Export Everything to a Single Markdown File

emanote export content

You can also export config with emanote export.

Publish to GitHub Pages

Typical workflow:

cd emanote
git pull
vim content/path/filename.md
emanote -L content/ gen docs/
git add .
git commit -m "Add content"
git push

Configure GitHub Pages to serve from:

  • Branch: main
  • Folder: /docs

RSS Feeds

Emanote supports RSS generation (see official documentation).
Ensure:

  • siteUrl is set correctly.
  • Pages include date: in front matter.

RSS is typically generated automatically during gen.

Search (Ctrl-K)

Emanote includes built-in search powered by Stork.
Press:

Ctrl-K

to open the search dialog.

Search behavior can be adjusted in index.yaml under the stork: section.

There are tips in the Emanote documentation or among the GitHub Issues to:

  • change the default fonts
  • show dates in pages

Have a look at the source of my blog to see how that is done.

I didn’t end up using Emanote for long, as I found something better.

Graph View