Obsidian

Obsidian is personal knowledge management (PKM) software. This section is a quick reference for authors (i.e. me) on the features I use.

Content organization

Prefer associative ontologies to hierarchical taxonomies. Let structure emerge organically. When it's imposed from the start, you prematurely constrain what may emerge and artificially compress the nuanced relationships between ideas…. Tags are an easy way to relate heterogenous items, but they're quite a low-signal way of describing relationships. Prefer explicit associations to inferred associations.
— Andy Matuschak

Obsidian offers multiple ways to connect notes and ideas. Based on Andy Mauschak's advice, in order of preference:

• #Links are one-to-one — a specific file has a relationship with another specific file.
• Folders are one-to-many — one folder can hold many files that could be about anything. Folders are a filesystem feature.
• Tags are many-to-many — a file can have multiple tags, and a tag can be used on multiple files. Example: #obsidian → #obsidian.

Links

Links are the strongest way to relate two pieces of content. You can link to:

Hover to preview links. Press Command (⌘) while hovering to preview a link while in edit mode.

You can also embed content by prefixing a link with !, most commonly used with ![redacted].

Basic formatting

Obsidian makes heavy use of Markdown. It also uses CSS for styling, greatly aided by the Style Settings plugin. After trying a few themes, I landed on the Prism theme.

I also use some custom CSS, mostly for image sizing and placement, as shown with the logo above via ![obsidian-logo.png\|logo](/img/user/knowledge-weaving/obsidian/assets/obsidian-logo.png). It's common in Obsidian to use the Alt Text feature for image placement. These custom placement values see the most use:

• logo (right, 150px, equal to right|150)
• side (right, 250px)

However, you can also specify placement values manually using the format !<width>[x<height>].

More on custom CSS in Obsidian below.

Obsidian also makes use of "front matter", YAML configuration at the top of a file with metadata about the file.

Inline HTML

You can use inline HTML in Markdown, too, like this (<span style="color:red">this</span>). The downside with using HTML is that some basic Obsidian functionality like text selection stops working properly due to trouble parsing the tags.

Instead, I tend to lean on MathJax and its LaTeX-like syntax, which comes preloaded with most all the extra text formatting I need. For example, $\color{red}\text{this}$ renders as $\text{this}$.

If you add two or more spaces at the end of the first line before pressing Enter, the two lines remain part of the same paragraph, but are broken by a line break (HTML <br> element). I typically use quotes or code blocks for poetry, though.

This is an example quote, made by lines prefaced with >.

You can nest quotes and use Markdown like italics as well.

Code blocks and literal formatting

While you can write literal text inline by surrounding it with one backtick, for longer texts, you can delimit a code block by surrounding it with three backticks or tildes.

```js
function fancyAlert(arg) { ... }
```

becomes…

function fancyAlert(arg) {
  if(arg) {
    $.facebox({div:'#foo'})
  }
}

You can also create a code block by indenting the text using Tab or 4 blank spaces.

Syntax highlighting

Obsidian uses Prism for syntax highlighting in literal blocks; here's a page with a list of supported languages, around 300 at the time of this writing. Some common ones I use are markdown, csharp, css, html, json, ruby, python, xml, yaml, and zsh (an alias for bash).

This is an example code block, bounded by ```.

Callouts

Callouts are quote blocks that include a callout marker, such as >[!note] Optional title. If not provided, the default title is the callout type name. Callouts render like this summary:

Adding a dash after the callout specified hides the callout by default:

> [!example]- A collapsed tip
> This is hidden.

You can also use CSS to create your own [redacted] types. I have a couple defined.

Tables

Basic table, only basic formatting allowed (for example, not footnotes).

| | |
| --- | --- |
| | |

Left-aligned text | Center-aligned text | Right-aligned text
:-- | :--: | --:
Content | Content | Content

Escape vertical bars \| if need be.

Footnotes

Footnotes are accomplished by a kind of link, see footnote documentation. Here is text referring to a footnote. ^[1]

Plugins

Before Bases, I used [redacted].

Tasks

You create a task list with - [] and complete items with an X (- [X]), which renders like so:

• Milk
• Eggs

I enabled TickTick integration once, but found it wasn't so useful. Same with Obligator.

Diagrams and charts

I mostly use the [redacted] plugin, a vector illustration tool which allows you to create diagrams like this BCG matrix.

See also the [redacted] note.

Custom CSS

Custom [redacted] is added in Settings > Appearance.

The sidecar panel code I use came from Matthew Turk. It allows you to embed content other than images with height and width specified, optionally with a border.

Others snippets I wrote, shown below:

img[alt*="right"] {
    float:right;
    margin-left: 1rem;
    margin-bottom: 2px;
    margin-top: 2px;
}

img[alt*="side"] {
    float: right;
    margin-left: 1rem;
    margin-bottom: 2px;
    margin-top: 2px;
    width: 250px;
}

For a trove of example CSS snippets, look at this snippet repo by Rushikesh.

Custom colors

Here's a way to define custom colors for the Prism theme. Note the use of [redacted].

body.theme-light,
body.theme-dark {
  --color-maroon-base-rgb: #ffa5ab; /* cotton candy */
  --color-maroon-tint-rgb: #da627d; /* blush rose */
  --color-maroon-text-rgb: #a53860; /* cherry rose */

  /* Actual colors (Prism-style mapping from *-hsl) */
  --color-maroon-base: hsl(from var(--color-maroon-base-rgb) h s l);
  --color-maroon-tint: hsl(from var(--color-maroon-tint-rgb) h s l);
  --color-maroon-text: hsl(from var(--color-maroon-text-rgb) h s l);

  /* HSL triplets (for use with hsl()/hsla()) */
  --color-maroon-base-hsl: var(--color-maroon-base);
  --color-maroon-tint-hsl: var(--color-maroon-tint);
  --color-maroon-text-hsl: var(--color-maroon-text);

  /* Shorthand alias (like --color-red, --color-blue, etc.) */
  --color-maroon: var(--color-maroon-text);
}

I find sites like Coolors.co helpful for making pleasing color palettes.

In the end, for my "extra" callout coloring, I decided these colors were close enough to the Prism theme's pink palette that I just used it instead.

Virtual Content

With the Virtual Content plugin, you can add a "Related files" collection to the end of all MOCs, as I do with moc-insert.

Helpful links

• Obsidian help documentation
• Obsidian.rocks