Markdown on Nicole van der Hoeven

How to publish your notes for free with Quartz

Fri, 26 Jan 2024 14:00:47 +0100

Quartz just won Best Tool in the Obsidian Gems of the Year 2023 awards, and with good reason. It’s a free, open-source static site generator that works really well with Markdown-based note-taking apps– including Obsidian, which it was originally designed for.

Here’s what Quartz looks like when published.

Obsidian for Non-coders

Fri, 21 Oct 2022 18:17:53 +0200

In this video, I talk about how to get started with Obsidian for non-coders, specifically tackling topics like what Markdown is and how to use it to write notes in Obsidian. I also talk about some Obsidian-specific syntax that help you do things like embed Obsidian notes, create footnotes, and create queries to find the right note.

In the video, I mention Shortform– follow that link to get 20% off an annual subscription!

How I use Obsidian for D&D - Player's Edition

Mon, 09 Aug 2021 17:46:51 +0200

I’ve previously written about how I use Obsidian for work, and I’ve also talked about how I use Roam Research for D&D. Shortly after the latter post, however, I moved to Obsidian. That was six months ago, so I thought it was time for an update.

Before the game

World

My World page is the main jumping-off point for all my notes for a specific campaign, and each campaign gets one. It contains:

The main locations in the world
The player characters, and links to their individual pages with information about what my character knows or thinks of them
A link to Open Loops (Quests and Questions and Agenda, as discussed below)
The list of all the sessions I’ve played for the campaign
Campaign-specific house rules that the DM has introduced

Quests and Questions

I like to play high-intelligence characters, so I like to keep track of unanswered questions and other adventure hooks my DM has dropped that the party hasn’t quite gotten around to resolving yet. Some of them are critical quest or story arcs, and others are random tidbits of information that NPCs have mentioned. I organize them by location, and then by quest, so that it’s easy to follow a thread depending on where the party is or how much downtime we have. Here’s an example of that page:

Agenda

While the Quests and Questions page records unfinished business that my character is actively thinking about but may not quite know how to explore yet, my Agenda page is where I write down specific tasks. I loosely follow the Getting Things Done methodology and divide this page into Next Actions and Waiting For. I group tasks by person and/or by location.

I use the Obsidian Completed Area plugin so that hitting a CTRL + ENTER on a task automatically checks it and then moves that task to a separate Completed section at the bottom of the note. This helps me keep the agenda clean and relevant.

During a game

Workspace

One of the best parts about Obsidian is that it allows me to save and load custom workspaces. This is useful because I use Obsidian for work as well as play, so I can set up the two workspaces differently. I also DM one campaign and play in another, and I have a workspace for each of them because I need different information available to me. The workspace features lets me customize my dashboard. Here’s what my workspace looks like for the 4e game that I play in:

At the beginning of a game, I’ll create a new session page in the last pane, enter into it, and then stay in the workspace for the rest of the game. I have my character’s stats sheet handy (which I need to do manually since I haven’t found a D&D Beyond-like service for 4e) and all the powers and abilities I need to refer to.

Session template

I love Obsidian templates! I use templates for things like inserting an HP tracker with all my party’s names, their max HP, healing surges (4e); a defense table to keep track of a creature’s defenses (again, 4e); and campaign-specific session log formats.

At the beginning of the game, I’ll create a new page in the Session List, click into it, and insert a session log template (I have this hotkeyed to CMD+;). Here’s what a fresh one looks like, in Edit mode:

I add metadata to every session so that I can query it later using the excellent Obsidian Dataview plugin, though I do this more often for the campaign I DM rather than the one I play in.

We usually do a recap at the beginning of the game, so I jump into the Recap of the last session section and embed the summary from the previous session using ![](/assets/86_20210717 Day 16 Hunting the Ice Phase Spider#^summary), which pulls in the section marked with ^summary from the last session. That embeds just that portion of the last session in the current session, like this:

This helps me get back up to speed quickly instead of doing the usual “Where were we again?” that takes up time.

HP table

My character is a multiclassed healer, so it’s important for me to know who needs heals or other buffs. I keep track of this separately, and it helps out my DM as well because it’s easy to miss something in the excitement of a battle. I do include the HP table in my workspace, in Preview mode, but here’s what it looks like in Edit mode:

Tables in Markdown can be a pain, but the Advanced Tables plugin goes a long way towards making this easier by adding some nice features like tabbing to the next cell, adding commands for inserting and deleting a column or row, and just automatically formatting a table so that it’s not a jumble of lines. I also heavily use this plugin for my characters stats and skills, both of which I keep in tables.

Keeping track of fights

When a fight breaks out, I insert an intiative template, which is just a list of all the characters in the party:

Initiative!
- Ka'ira
- Maestro
- Xio
- Eraithe
- Keren

This makes it easier to add the initiative value rolled, as well as that of any other baddies we’re fighting. I use the Outliner plugin to be able to easily move people on the list up or down as needed without having to copy or paste. I have the shortcuts set to CMD+SHIFT+UP and CMD+SHIFT+DOWN so I don’t even need to use my mouse.

I also have a template for Defenses. D&D 4th Edition has four different kinds of defenses, and since my character’s powers target a few of them, I keep track of the defenses of each monster. Here’s what that template looks like, in Edit mode:

| Defense | Value |
| --------------------- | ----- |
| [[Reflex Defense]] | |
| [[Fortitude Defense]] | |
| [[Will Defense]] | |
| [[Armor Class]] | |

You’ll notice that I also link to the pages I have for each defense type, in case I need to remind myself which stat a defense is comprised of.

Character powers

Like many, I have migrated from playing games on a literal tabletop to doing it virtually. These days, I play 100% online, using a bunch of different tools. For the most part, though, I still prefer to roll actual dice. There’s just something satisfying about the feel of a die in my hand. Since I switched to Obsidian, though, I have looked into virtual dice. On the off chance I don’t have any dice (ha) or all my dice have betrayed me (much more likely), I use the Dice Roller plugin. It turns

`dice: 1d20+7`

into a random die roll. Here it is when incorporated into my character’s list of powers:

Sometimes, when I’m feeling superstitious about my dice, I’ll switch to using this dice roller “just to be safe”. It has other cool features too, which I’ll cover more in detail in the Dungeon Master’s edition of this article.

Search, linked, unlinked mentions

Frequently, something comes up in a game that I’m sure we’ve heard of before, but I can’t quite remember where or when. Actually, sometimes something comes up that I’m quite sure we’ve never heard of before, but it turns out we have. Luckily, Obsidian is quick to tell me that using the linked/unlinked mentions and the search features.

Here are the mentions in my note for the word “Netheril”:

Unlinked mentions show up too, in case the word came up somewhere and I didn’t think to specifically create a page on it.

On monster pages, mentions remind me when we fought them last, and any tips for fighting them. It can be handy when one of the other players has forgotten something that happened to them, too. If I want to remember how Ka’ira got her festering wound, I can type it into the Obsidian search bar:

and be able to confidently say that Ka’ira got her last festering wound on session 68, in the Blue Crystal Fortress that we now know to be the Twisted Fane, while fighting aberrations.

After a game

I think I might use Obsidian even more between games than during the game, because after the game is when I process everything my character learned.

Session summary

Immediately after the game is when I create a short session summary. I like to do this when the session is still fresh in my mind. Then, I add ^summary at the end of the paragraph to identify it and to be able to pull it into the next session’s recap. Block references and block embeds are some of my most frequently used Obsidian features.

Creating new pages

I then create new pages for any people, places, magical items, or events that we encountered. I like to use a standard frontmatter:

---
type:
location: [Neverwinter]
world: "Forgotten Realms"
campaign: "Order of the Wandering Mind"
date: 2021-06-23
---

Here’s an example of the page for an NPC:

If my DM has given us character art, I include it in the page.

And here’s an example of a page for a location:

For this page, I used a plugin called Obsidian Leaflet, which lets me add maps to my notes! In this case, my DM gave us this map of the structure as a guide, but during combats we didn’t use a map. To keep myself oriented between games, I added red pawprint pins where we had spotted or fought monsters, green thumbtacks to mark where we’d ended sessions, and green markers where we had spotted allies. I also like to add links to monsters or sessions on the pins/markers so that I can jump to those pages quickly if I need to.

History

To keep historical events straight in my head, especially since we tend to discover them out of sequence, I use the Obsidian Timelines plugin, which lets me create pages like this:

by using this code in the timeline page:

```timeline
fr
\```

(without the backtick) and this for every event that I want to include:

---
date: [2021-06-23]
tags: [timeline, fr]
---
<span
 class='ob-timelines'
 data-date='1443-00'
 data-title='Xionerys is born'
 data-class='orange'
 data-img = 'assets/xionerys.jpg'
 data-type='range'
 data-end='1443-00'>
 Xionerys is born in Calimshan.
</span>

Using this method, I’ve been able to call out discrepancies in what two different NPCs told us and figure out that one was lying– or at least misinformed.

Replace all

When I inevitably get a fantasy name wrong, having pages as flat .md files is great because I can do a find and replace on ALL mentions of a certain NPC name/place I’ve misspelled (those fantasy names!). I do this with my usual code/text editor, VSCode, just because I usually already have it up, but you can do it using terminal commands. If it’s just the name of a page, updating the spelling in Obsidian changes it everywhere else it’s linked to as well, which is useful.

Updating open loops

To finish processing the last session, I update Open Loops: I add new points or update existing points in Quests and Questions, and then add tasks to Agenda that I want to do in the next session. I find that it’s best to do it after a game because it’s a week, sometimes more, between games and there’s a high likelihood I’ll have forgotten what I want to do by then!

Publish

I also publish my D&D notes, just for transparency. My DM has joked that he looks in there sometimes when he’s forgotten something. Even if he doesn’t, I enjoy having my notes so easily accessible. I often navigate there myself when I have a spare moment, remembering old sessions and thinking about some loose threads. If you’re interested, here they are! Just be warned that the plugins won’t work in the web version, so sometimes you’ll come across bits of code that didn’t render. I also migrated these notes from Roam Research, and haven’t gone back and updated all the older notes.

Conclusion

Since I’ve switched to Obsidian, it’s been an indispensable part of my workflow for D&D. Without it, I’d be just another murder hobo with no notes. And no DM wants that!

Presentation Slides as Code

Tue, 02 Mar 2021 19:07:31 +0100

I was working on a presentation for later this month when Marie Drake told me about slides.com. It’s basically a Powerpoint replacement (which, let’s be honest, needs replacing) in that it lets you create slides and it lets you present from it. It even goes beyond Powerpoint in that it also saves your slides publicly for people to view later.

Before she’d mentioned slides.com, I had been planning on creating a presentation on Obsidian, my note-taking tool of choice. The advantage of this approach is that presentations in Obsidian are just Markdown files with --- between lines of text to delineate slides.

The problem with using Obsidian on its own is that it’s severely lacking in features, and it’s also not shareable. You can, of course, publish the Markdown file, but people won’t be able to view them in slide format. After playing with slides.com, however, I also discovered it had its own weaknesses. It is completely UI-driven, so there’s no way to create slides just from a Markdown file. It’s also hosted by them, so there are limitations imposed, depending on which pricing tier you pay for.

So I got to Googling. And I think I found a pretty good setup for my needs.

The end result

I write the presentation in Obsidian, in Markdown. Here’s what that looks like in a sample presentation where I’m trying out a bunch of features.
I use Hugo to generate a static website and convert the Markdown files into javascript and html, using reveal.js and the reveal-hugo theme.
I push the static website to a remote repository on GitHub. GitHub Pages serves that site (for free!) on my custom subdomain.

Check out the final product here: https://slides.nicolevanderhoeven.com/sample

The setup

Prerequisites

An Obsidian vault (or you can actually just use any text editor)
Git installed and set up with credentials
A GitHub account
Hugo installation (brew install hugo)

Create a new Hugo site

Open up a terminal window and cd to a folder in your Obsidian vault. Then, create a new Hugo-generated site:

hugo new site slides

Replace slides with the name of your new site.

You should have a new directory, slides, in your Obsidian vault.

Add the reveal-hugo theme

cd into slides and clone the reveal-hugo repo. The documentation suggests using a submodule:

git submodule add git@github.com:dzello/reveal-hugo.git themes/reveal-hugo

Personally, I just cloned it because I know I’m probably going to be messing around with it substantially:

git clone git@github.com:dzello/reveal-hugo.git themes/reveal-hugo

You should have a /themes/reveal-hugo folder that contains the theme.

Configure reveal-hugo theme

Set up your new Hugo site to use the reveal-hugo theme by adding the following to /config.toml:

theme = "reveal-hugo"

[markup.goldmark.renderer]
unsafe = true

[outputFormats.Reveal]
baseName = "index"
mediaType = "text/html"
isHTML = true

The Reveal part is what lets you output text in slide format.

Create your slides

Go to /content and create a file there, called _index.md. The filename is important, as is its location (I learned that the hard way). This file is going to be the first page people see, so it should probably be a list of your presentation slides. For now, put in something like this:

+++
title = "My presentations"
outputs = ["Reveal"]
+++

Here are my presentation slides!

[sample presentation](/sample)

Then, create a new folder for your presentation, such as sample. In /content/sample, create a file called _index.md. Again , the filename is also important here (guess how I learned that).

This index file is going to be where you actually create your slides. Here’s the context of my /content/sample/_index.md:

Each slide is separated by ---, just like in Obsidian, which apparently uses the same converter that reveal-hugo does, reveal.js. Note that if you want to try out having an image as a background to one of the slides, you’ll need to add that to your /sample folder and change the filename in the slide in this part:

slide background-image="lucrezia-carnelos-AsM4T46tqcU-unsplash.jpg"

Generate your site

Now it’s time to generate your site! Wait - didn’t we already do that? Sort of that. That was creating the framework for the site, but now you need to get Hugo to convert those Markdown files you’ve just created into something publishable. So cd to the root directory slides and run this:

hugo

That command should generate a slides/public folder, where all the publishable code will go.

At this point, you can also check your work by starting a local server with hugo server and navigating to http://localhost:1313.

Push your site to a remote GitHub repo

cd into your public folder. This is important, as I initially started the repo in slides and it took me ages to realize that GitHub Pages requires an index.html in the root directory to function.

Initialize a Git repo:

git init

Stage and commit your changes:

git add .

git commit -m 'Initial commit'

Create a repository on your GitHub account called username.github.io where username is your GitHub username. (If you already have a repo called that, you can alternatively push the contents of public to a branch called gh-pages). The repo name matters.

Push your changes to your repo.

git push -u origin master

You should now have a repository on GitHub called username.github.io, containing everything in public.

Set up GitHub Pages

On GitHub, go to the repository settings and scroll down to the GitHub Pages section. Select the right branch (master in most cases) and click Save.

(Optional) Using a custom domain

If you want to use a custom domain, enter it in the repository settings from the previous step.

Then, go to your domain registrar and add a CNAME record pointing www to username.github.io. Here’s more information on that from GitHub.

It can take a few hours for DNS records to propagate, so after you set this up, take a break before you convince yourself you’ve set something up wrong. ;)

Check out your new site!

When you navigate to your new site, you should first see the contents of slides/content/_index.md, which has a link to your sample presentation. Clicking on that should reveal (ha) the slides one by one. You can navigate through them with the arrow keys, and you can also see speaker notes (if you put any in, which I did on the third slide if you copied my sample slides).

Other issues I faced

I ran into a few issues during this setup because:

I was already tracking changes in my Obsidian vault with Git
I already had a repo called nicolevanderhoeven.github.io, and I needed to create a branch called gh-pages to still use GitHub Pages.
My Obsidian repo on GitHub is a private one, but I wanted the slides to be public.

If you have a similar setup, maybe the following instructions will help.

Use worktrees, not subtrees or submodules

After attempts to make this setup work with submodules and subtrees, both of which were way too complicated for what I needed, I settled on using worktrees.

Add public to .gitignore. From slides:

echo "public/" >> .gitignore

Create a worktree for public, to be tracked on the branch gh-pages:

git worktree add public gh-pages

After you generate the static code via hugo:

cd public
git add .
git commit -m 'Commit message'
git push origin gh-pages

Your gh-pages branch should contain only the files in public.

GitHub Pages with a private repo

GitHub Pages is free, but if you want to be able to use it with a private repo, you can’t. Sorry!

You can look into using GitHub Actions to copy public from your private repo to a public one, or you could just spend the $4/month to remove the restriction. I opted to pay, because I love GitHub anyway.

Presentation as code

That’s it! I ran into a few snags while I was attempting to implement this, so I thought I’d document it here in case it helps anyone else. Despite the setbacks, I think it’s worth it– I can now whip up presentations in Markdown within Obsidian and have that published to a site I control for people to look through at their own leisure. This should speed up my presentation creation process considerably.

Theoretically.

If only I could stop procrastinating on creating this presentation by setting up a framework for creating presentations…