Obsidian

Obsidian is the tool I use to maintain this knowledge base. I also use it extensively for my notes at work since joining Microsoft since:

1. It does not try to upload all my notes (and the secrets therein) to some third-party cloud service. I keep my Obsidian vaults in my corporate OneDrive or Sharepoints, allowing me to comply with corporate data management policy.
2. It supports linking between documents and finding information that I’ve forgotten very easy. This seems to work best for the way I take and re-read notes.

I’ve left Obsidian a few times, but I keep coming back. I now pay for a commercial license since I use it primarily for work. Obsidian keeps getting better too, and its direction of development lines up with what I need out of it.

I use Obsidian in combination with a lightly modified version of Quartz 4 to publish this digital garden online.

Organization

I periodically try new ways of organizing, but I’ve found that just throwing everything into one unorganized pile (as is on display with this site) seems to work best. It lets me focus on just capturing details without the cognitive burden of fitting those details into some rigid folder structure at the same time.

Reference

I never remember how some of the markdown extensions in Obsidian work.

Callouts

See Callouts - Obsidian Help for the full assortment of callouts supported. Quartz supports these too.

Note

This is a note.

Abstract

This is an abstract. Aliases are summary and tldr.

Info

This is an infobox.

Warning

Stuff for which the reader should be mindful, like gotchas.

Danger

Worse than a warning I guess.

Question

Maybe for internal monologue?

Tip

This is a tip. Possibly a protip.

Example

Good for tutorials?

Success

Not sure how this is meant to be used.

Failure

Also not sure how this is meant to be used.

Todo

This is a todo.

Bug

Lorem ipsum dolor sit amet

Quote

This is neat. Better than the standard markdown >?

Mermaid graphs

See Examples | Mermaid.

Mermaid seems to be OK at making basic network diagrams, but they get messy fast. I don’t know if it is as expressive as graphviz.

---
title: Network topology
---
graph TD
	subgraph spines
		t00
	    t01
	end
	subgraph leaves
		t10
		t11
		t12
		t13
	end
	t00 --- t10
	t00 --- t11
	t00 --- t12
	t00 --- t13
	t01 --- t10
	t01 --- t11
	t01 --- t12
	t01 --- t13

---
title: Left-to-right
---
graph LR
    A[Square label] -- Edge label --> B((Circle label))
    A --> C(Rounded label)
    B --> D{Diamond}
    C --> D

Exporting

Pandoc

Sometimes I have to convert from Obsidian Markdown to docx before disseminating (since I work at Microsoft). The following flow seems to do a good job:

# strip out wikilinks and preserve link descriptions
perl -pe 's/\[\[[^|\]]+\|?(.*?)\]\]/\1/g' text.md > finalfile.md
 
# convert to docx using permissive interpretation of markdown
pandoc finalfile.md -f gfm -t docx -o output.docx

Readwise Reader

After Omnivore was shut down, I tried using a few read it later apps including Readwise Reader. Here is the export template I used:

---
title: {{ title }}
author: {{ author }}
category: {{ category }}
{% if document_note -%}
description: {{document_note}}
{% endif -%}
{% if tags -%}
tags: {% for tag in tags %}{{tag}} {% endfor %}
{% endif -%}
{% if url -%}
source: {{url}}
{% endif -%}
---

From [{{ title }}]({{url}}):

{% for highlight in highlights -%}
> [!quote]
> 
> {{ highlight.content | replace('\n', '\n> ') }}

{% if highlight.note -%}
{{ highlight.note }}
{% endif %}
{% endfor %}

Omnivore

Danger

As of October 29, 2024, the Omnivore app has been acquired, and everyone’s data on the public service instance will be deleted. So I guess this was a short-lived experiment, and I’m back to struggling with other read-it-later apps.

I tried using Omnivore (a read it later app) to save and annotate interesting articles, then import them into Obsidian so I could easily copy+paste them into pages here. I used the following note template based on Sync all your reading to Obsidian

From [{{{title}}}]({{{originalUrl}}}):

{{#highlights.length}}{{#highlights}}> [!quote]
> {{{text}}}[^{{{id}}}]

{{#note}}{{{note}}}

{{/note}}{{/highlights}}{{/highlights.length}}
[^{{{id}}}]: [{{{title}}}]({{{originalUrl}}})

And my front matter template (under Advanced Options) is:

id: {{{id}}}
title: >
  {{{title}}}
{{#author}}
author: >
  {{{author}}}
{{/author}}
source: {{{originalUrl}}}
date_saved: {{{dateSaved}}}
{{#datePublished}}
date_published: {{{datePublished}}}
{{/datePublished}}