Themes
Built-in themes
mddog has four built-in themes:
| Theme | Description |
|---|---|
github-light, github-dark | How GitHub renders Markdown |
obsidian-light, obsidian-dark | How 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-schemeislightordark. It is required unless the theme has a base- Colors are literal
#rgbor#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
| Token | Colors |
|---|---|
--mddog-bg | the page and file list background |
--mddog-fg | normal text |
--mddog-fg-muted | dim text: ages, titles, hint labels |
--mddog-fg-bright | names, keys, headings |
--mddog-selection-bg | the selected row in the list and the table of contents |
--mddog-bar-bg | the bottom status bar |
--mddog-border | separators and the table of contents divider |
--mddog-skeleton | the loading skeleton bars |
Page
| Token | Colors |
|---|---|
--mddog-text | body text |
--mddog-text-muted | level 6 headings and other quiet text |
--mddog-heading | headings 1 to 5 |
--mddog-link | links |
--mddog-accent | the quote bar and done checkboxes in the obsidian layout |
--mddog-code-bg | inline code |
--mddog-pre-bg | code blocks, diagram nodes, the diagram zoom bar, and keys |
--mddog-alt-bg | every other table row |
--mddog-rule | rules, heading lines, quote bars, and table borders (the obsidian layout draws quote bars in --mddog-accent) |
--mddog-mark-bg | <mark> text |
--mddog-match-bg | search matches |
--mddog-match-current-bg | the current search match |
--mddog-match-fg | text inside a search match |
--mddog-match-current-fg | text inside the current search match |
--mddog-text-selection | selected text |
--mddog-alert-note, -tip, -important, -warning, -caution | each alert's bar, icon, and title |
--mddog-diff-add-bg, --mddog-diff-del-bg | added and removed lines in a diff block |
--mddog-button-bg | a diagram's copy and expand buttons. Their border and the zoom bar's take --mddog-border |
Code
| Token | Colors |
|---|---|
--mddog-pl-comment | comments |
--mddog-pl-keyword | keywords and operators |
--mddog-pl-string | strings |
--mddog-pl-constant | numbers, constants, and types |
--mddog-pl-entity | function names |
--mddog-pl-inserted, --mddog-pl-deleted | the text of added and removed diff lines |
--mddog-pl-variable, --mddog-pl-tag | variables, and tags and JSON keys, in the obsidian layout. The github layout draws them as constants and keywords |
Type
| Token | Value | GitHub's |
|---|---|---|
--mddog-font-body | font names, first choice first | system-ui |
--mddog-font-code | font names, first choice first | ui-monospace, SFMono-Regular, Menlo |
--mddog-heading-scale | six sizes in em, for h1 to h6 | 2 1.5 1.25 1 0.875 0.85 |
--mddog-heading-weight | six font weights from 100 to 900, for h1 to h6 | 600 600 600 600 600 600 |
--mddog-line-height | body line height, in em | 1.5 |
--mddog-code-size | code size, in em of the text around it | 0.85 |
--mddog-code-line-height | line height in code blocks | 1.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:
githublays out a page as GitHub renders Markdownobsidianlays 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
| Token | Sets |
|---|---|
--mddog-base | the theme this one builds on. See Build on another theme |