braindump4000: heavily modified jethrokuan braindump

Convert your nested org mode database with broken links into a Hugo website.

In addition to nesting and broken links, braindump4000 also deals with it if you are already using Hugo to publish parts of your org mode database.

Find the original braindump at https://github.com/jethrokuan/braindump

You could also use org-publish, but on my 1000+ file database, that takes forever, even when most of the files don't have to be republished.

P.S. This tool is now also able to munge that Hugo-destined output for Obsidian, so that you are able to access your org-mode database using the Obsidian mobile app.

Quickstart

Let's say the root directory containing your nested org-mode database is ~/notes/pkb4000 and you want a Hugo version in ~/notes/web-pkb4000 then you could do the following:

Create the hugo website

cd ~/notes
hugo new site web-pkb4000

Install jethrokuan's cortex theme:

cd ~/notes/web-pkb4000/themes
git clone https://github.com/jethrokuan/cortex.git

Install his config.toml at the top-level.

Add the root level of the config, add:

refLinksErrorLevel = "WARNING"

Add two important pages

Create web-pkb4000/content/_index.md for the front page:

Well hello!

See the [index](posts).

Very importantly, create an empty web-pkb4000/search/_index.md just so that your search works.

Build your site with braindump4000

# I usually clone braindump4000 inside my notes database pkb4000
cd notes/pkb4000
git clone https://github.com/cpbotha/braindump4000.git
cd notes/pkb4000/braindump4000
# note that the destination directory is the desired Hugo section within "content"
# for the cortex theme, this must be "posts"
python3 build.py ~/notes/pkb4000 ~/notes/web-pkb4000/content/posts

The instructions above are just following my example.

However, as long as you specify your input and output directories correctly, everything should work for different setups.

Obsidian support

braindump4000 is also able to transform your org-mode database into an Obsidian vault.

This is a bit of a hack, but it does yield an Obsidian vault which is quite usable, including image attachments, backlinks and so on.

This howto is simpler, because we don't need the whole Hugo site, only something that looks like an Obsidian vault:

# I usually clone braindump4000 inside my notes database pkb4000
cd notes/pkb4000
git clone https://github.com/cpbotha/braindump4000.git
cd notes/pkb4000/braindump4000
python3 build.py --obsidian ~/notes/pkb4000 ~/notes/obs-pkb4000/content/posts

After this, you can open ~/notes/obs-pkb4000/ as an Obsidian vault.

The markdown in content/posts/ has been massaged (see obs_postproc.py for details) to support Obsidian's particular expectations, and images generally end up in static/ox-hugo.

Personally, I use syncthing and Möbius Sync to push the converted vault into Obsidian's sandbox on my iPhone in order to get mobile access to my Org mode database.

Obsidian app configuration

Activate Settings - Editor - Display - Srict line breaks as the ox-hugo / markdown generally does add single line breaks inside paragraphs.

These scripts add the org-mode note title as the first h1 / # heading to the file, whilst the Obsidian app wants to display the filename as the title.

In order to hide the built-in Obsidian filename-title display, create the file vault/.obsidian/snippets/hide-title.css with the following contents:

div.inline-title {
  display: none;
}

Then, in settings - appearance - css snippets, refresh and activate hide-title.

Obligatory screenshot(s)

In the screenshot below, I started with the Apple WatchOS 9 sleep tracking video note, from there the Sleep backlinks page, then the Seven and a Half Lessons about the Brain book notes and finally my Books backlinks.

My braindump site is being served using goStatic, tightly bound to a private tailnet IP.

Obsidian mobile app

FAQ

Why is this README markdown and not org?

It started as an org-file, but then I ran into github's org mode support not including a way to specify image display size. See e.g. https://stackoverflow.com/questions/54926052/github-org-mode-html-export-image-resizing