Skip to Content

Themes

Built-in themes

mddog has four built-in themes:

ThemeDescription
github-light, github-darkHow GitHub renders Markdown
obsidian-light, obsidian-darkHow Obsidian renders Markdown

By default, mddog uses the GitHub pair and follows the macOS appearance.

To pick a theme, set theme in your config:

theme = "light:obsidian-light,dark:obsidian-dark"

Custom themes

A theme is a CSS file of tokens that sets the page's colors and type, and mddog's terminal parts (file list, status bar, table of contents, help, loading skeleton) to match. Example:

:root {
  color-scheme: dark;
  --mddog-base: github-dark;
  --mddog-bg: #101418;
  --mddog-link: #6cb6ff;
  --mddog-font-body: "Avenir Next", system-ui;
}

While a theme file has the .css extension and uses CSS's :root { ... } syntax, it is not a stylesheet. It only accepts the specific tokens as described in the Tokens section.

Save the file next to your config, for example as ~/.config/mddog/my-theme.css, and point the config at it:

theme = "my-theme.css"

Rules

  • color-scheme is light or dark. It is required unless the theme has a base
  • Colors are literal #rgb or #rrggbb. var(), rgb(), names, and alpha are not accepted
  • A token you leave out comes from the base, else from the GitHub theme of the same mode
  • mddog reads the theme at startup. Restart it to see a change

Build on another theme

Name a base with --mddog-base, and your theme starts from all of the base's tokens, so you only set the ones you want to change. The base is a built-in name or a .css path. A relative path starts from the theme file's folder.

For example, this gives obsidian-dark a navy background and keeps the rest of it:

:root { --mddog-base: obsidian-dark; --mddog-bg: #202a44; }

Your theme takes its base's color-scheme. A different color-scheme, or a chain of bases that loops, stops mddog with an error.

The built-in themes in assets/themes/ set every token, so they work as full examples.

Tokens

Terminal parts

TokenColors
--mddog-bgthe page and file list background
--mddog-fgnormal text
--mddog-fg-muteddim text: ages, titles, hint labels
--mddog-fg-brightnames, keys, headings
--mddog-selection-bgthe selected row in the list and the table of contents
--mddog-bar-bgthe bottom status bar
--mddog-borderseparators and the table of contents divider
--mddog-skeletonthe loading skeleton bars

Page

TokenColors
--mddog-textbody text
--mddog-text-mutedlevel 6 headings and other quiet text
--mddog-headingheadings 1 to 5
--mddog-linklinks
--mddog-accentthe quote bar and done checkboxes in the obsidian layout
--mddog-code-bginline code
--mddog-pre-bgcode blocks, diagram nodes, the diagram zoom bar, and keys
--mddog-alt-bgevery other table row
--mddog-rulerules, heading lines, quote bars, and table borders (the obsidian layout draws quote bars in --mddog-accent)
--mddog-mark-bg<mark> text
--mddog-match-bgsearch matches
--mddog-match-current-bgthe current search match
--mddog-match-fgtext inside a search match
--mddog-match-current-fgtext inside the current search match
--mddog-text-selectionselected text
--mddog-alert-note, -tip, -important, -warning, -cautioneach alert's bar, icon, and title
--mddog-diff-add-bg, --mddog-diff-del-bgadded and removed lines in a diff block
--mddog-button-bga diagram's copy and expand buttons. Their border and the zoom bar's take --mddog-border

Code

TokenColors
--mddog-pl-commentcomments
--mddog-pl-keywordkeywords and operators
--mddog-pl-stringstrings
--mddog-pl-constantnumbers, constants, and types
--mddog-pl-entityfunction names
--mddog-pl-inserted, --mddog-pl-deletedthe text of added and removed diff lines
--mddog-pl-variable, --mddog-pl-tagvariables, and tags and JSON keys, in the obsidian layout. The github layout draws them as constants and keywords

Type

TokenValueGitHub's
--mddog-font-bodyfont names, first choice firstsystem-ui
--mddog-font-codefont names, first choice firstui-monospace, SFMono-Regular, Menlo
--mddog-heading-scalesix sizes in em, for h1 to h62 1.5 1.25 1 0.875 0.85
--mddog-heading-weightsix font weights from 100 to 900, for h1 to h6600 600 600 600 600 600
--mddog-line-heightbody line height, in em1.5
--mddog-code-sizecode size, in em of the text around it0.85
--mddog-code-line-heightline height in code blocks1.45

A font list works like CSS's font-family: mddog takes the first installed font. system-ui is the macOS system font, and ui-monospace is SF Mono. Quote a name with spaces. When no name matches, body text uses the system font and code uses Menlo.

A heading weight works like CSS's font-weight. The system font draws every weight, so Obsidian's 700 680 660 640 620 600 steps down smoothly. A font with fixed cuts takes its nearest one: Menlo has only regular and bold, so its 600 is bold. Bold text and table headers stay at 600 whatever the headings use.

Layout

--mddog-layout picks the rules that place blocks on the page. Its value can be github (the default) or obsidian:

  • github lays out a page as GitHub renders Markdown
  • obsidian lays out a page like Obsidian's reading view

Compared with github, obsidian's headings have no line under them, lists and tables are tighter, tables have no stripes, and quote bars and done checkboxes use --mddog-accent. It takes its grays from --mddog-text over --mddog-bg, so the look holds with any colors. To use it with your own colors, set --mddog-layout: obsidian or build on an Obsidian theme.

Other

TokenSets
--mddog-basethe theme this one builds on. See Build on another theme

On this page