Obsidian Minimal: a CSS theme whose real controls live in two other plugins
A distraction-free and highly customizable theme for Obsidian.
At a glance
- What is it?
- kepano/obsidian-minimal is an MIT-licensed CSS theme for Obsidian on desktop, mobile and tablet. The theme file is only half of the product, because colors, fonts, toggles and UI hiding sit in companion plugins you install separately.
- Who is it for?
- Use Minimal if you want a quiet Obsidian interface and are willing to install Minimal Theme Settings, and probably Hider, alongside it. Skip it if you want a single self-contained theme file, if you write in a language other than English and will not add a translation snippet, or if your daily plugins are not on the short list the author tested by hand.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 3 days ago.
- What is it written in?
- Mainly CSS, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.
Star history
- kepano/obsidian-minimal5,677 ★ · +288
| Repository | 2026-09-23 | 2026-11-15 |
|---|---|---|
| kepano/obsidian-minimal | 5.4k | 5.7k |
288 Stars in the last 53 days, measured from the daily GitHub snapshot. Compare with other projects
Editorial analysis
The theme installs in three clicks but exposes almost nothing by itself
Installation goes through Obsidian itself. Open Settings, go to Appearance and click Manage, then search community themes for Minimal and click Use. That gives you the stylesheet and nothing more. The background contrast options, the color scheme picker, line width, focus mode, colorful headings and the rest of the toggles are reached through the Minimal Theme Settings plugin, which is a separate install from Community plugins. For that you turn off Restricted mode, search for Minimal Theme Settings, click Install and then Enable.
The practical consequence is that a user who installs only the theme gets the default look and no visible way to change it. The README calls the settings plugin highly recommended for all users of Minimal, and in practice the recommendation is a requirement if you want any of the documented options.
Custom color schemes depend on Style Settings, a third plugin from a different author
Minimal ships preset color schemes that you pick separately for light and dark mode: Dracula, Everforest, Gruvbox, macOS, Nord, Notion, Solarized and Things. The Style Settings plugin is listed as optional and is the route to a scheme of your own. The README says that with it you can change Minimal's colors, font sizes, font styles and many more details, and suggests opening Style Settings in a new pane through the command palette, with CMD + P by default, so you can watch changes land.
Style Settings comes from a different author (mgmeyers) than the theme and the other two companion plugins (kepano). So if you want a palette outside the presets, you rely on a plugin the theme author does not control. There is no documented way in the README to define a custom scheme from the theme file alone.
Hider removes interface elements, and removing the ribbon changes how you reach it
The Hider plugin is recommended for hiding Obsidian UI elements such as the window frame, scrollbars and tooltips. It is a separate repository, kepano/obsidian-hider, so the "minimal" look of a fully stripped window costs you a second plugin on top of the settings one.
There is a side effect worth knowing before you switch the toolbar off. When you use Hider to turn off the main toolbar, also called the app ribbon, you reach it by hovering over the bottom left edge of the window. Anyone using a touch device or a window that is not flush with the screen edge should test that gesture before relying on it, because the ribbon holds the buttons you may still want daily.
Text labels for navigation are English only until you add a translation snippet
One of the listed features adds text labels to the top left primary navigation. The README attaches a condition to it: a translation snippet is necessary for languages other than English, and it points to a localization section of the documentation for the details.
If you write notes in another language and turn the labels on without the snippet, you should expect English labels in an otherwise localized vault. The work of translating the labels falls on you.
The other feature toggles are simpler. Focus mode hides the title bar and status bar. Colorful frame uses the accent color for the top area of the app window. Colorful headings gives each heading level its own color. Hide workspace borders removes dividing lines, and Trim filenames cuts file names to a single line.
Image filters are written into each link, so they cannot be applied to a whole vault
Layout behavior is controlled at two levels. The settings plugin sets image grids and block widths for the whole vault: image grids turn consecutive images into columns, and a new row starts when you add an extra line break between images. The same options can be turned on per file with helper classes.
Image filters work per image. You append the filter name to the end of the image link:
![[image.jpeg#invert]]Four filters are listed. #invert inverts images in dark mode and suits charts and handwriting on light backgrounds. #invertW inverts in light mode for charts and handwriting on dark backgrounds. #circle crops the image to a circle, and #outline adds an outline.
Because the filter lives in the link text, every image that needs it must carry it. If you later move to a different theme, those suffixes stay in your notes and no longer do anything, which makes the syntax a small piece of lock-in inside your content.
Plugin support is a named shortlist, not a compatibility guarantee
The README says most plugins work well with Minimal, but eleven have received special attention: Calendar, Charts, Checklist, Dataview, Dictionary, Excalidraw, Git, Hider, Kanban, Outliner and QuickAdd. The wording "most plugins work well" is a claim without a list of exceptions, so a plugin outside the eleven has no stated status either way.
If your workflow leans on an unlisted plugin with its own interface, such as a heavy dashboard or a custom view, the cost of finding visual glitches is yours. The sensible check is to switch to Minimal on a copy of your vault, open the views you use every day, and compare them against the default theme before switching permanently. Whether Minimal beats the default theme for you depends on those plugins, and the README offers no comparison table to settle it.
Two presets matter for people comparing Minimal with Things: Things is not a rival theme here but one of the color schemes Minimal itself offers.
Building from source needs Node, sass and a path in a local env file
The repository root holds Minimal.css, theme.css, obsidian.css, manifest.json, versions.json, build.js and a src directory. The package.json declares two scripts, build running node build.js and dev running node build.js --watch, with chokidar ^3.6.0 and sass ^1.83.0 as dependencies. The package version is 9.1.4.
The watch mode copies output into your vault when you tell it where the vault is. The repository includes a .env.example with one line:
OBSIDIAN_PATH='/Documents/Obsidian/.obsidian/themes/'That value is an example path, and you must replace it with your own vault's themes folder. The README does not describe what build.js does when the variable is missing, so do not assume a default. Only contributors who edit the Sass sources need any of this. A normal user installs from the community themes list and never touches Node.
The project is MIT licensed, its default branch is master, and the documentation lives at minimal.guide rather than in the README.
Three tags landed within two days, and the last push was 6 October 2026
Recent releases are 9.1.2 on 5 October 2026, 9.1.3 on 6 October 2026 at 18:39 UTC and 9.1.4 on 6 October 2026 at 22:07 UTC. The latest push to the repository was 6 October 2026, and the repository is not archived.
Three releases in about a day and a half show quick iteration, and the release list gives no reason for it. The practical advice is to update through Obsidian's theme manager and look at your daily notes afterward. The README does not document a way to pin an older version or roll back, so if 9.1.4 breaks a view you rely on, your options are to wait for the next tag or to keep a copy of the earlier theme.css yourself.
Editorial conclusion
Use Minimal if you want a quiet Obsidian interface and are willing to install Minimal Theme Settings, and probably Hider, alongside it. Skip it if you want a single self-contained theme file, if you write in a language other than English and will not add a translation snippet, or if your daily plugins are not on the short list the author tested by hand. Before committing, check that your own plugins render properly under the theme.
Frequently asked questions
What is Minimal documentation and where does it live?
The detailed documentation for the Minimal theme is at minimal.guide, and the README links to it from the first line. Feature pages such as background contrast, color schemes and line width are hosted there.
How do you make Obsidian look pretty with Minimal?
Install Minimal from Appearance, Manage, community themes, then add the Minimal Theme Settings plugin to pick a color scheme, fonts and feature toggles. Hider can hide interface elements such as the window frame and scrollbars.
Is Obsidian Minimal better than the Things theme?
They are not separate choices in the README: Things is one of the preset color schemes that Minimal offers, alongside Dracula, Everforest, Gruvbox, macOS, Nord, Notion and Solarized.
What is the best Obsidian theme according to Minimal's README?
The README says Minimal won Obsidian's official Best Theme award, linking to the Best of 2020 awards results. It makes no ranking claim beyond that.
Official sources
Add this badge to your README
If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.
[](https://hysenlabs.com/projects/kepano-obsidian-minimal)Star history chart for your README
[](https://hysenlabs.com/projects/kepano-obsidian-minimal)Was this useful?