Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/chrisgrieser/shimmering-focus/llms.txt

Use this file to discover all available pages before exploring further.

Shimmering Focus is written in vanilla CSS and welcomes contributions from the community. Whether you want to patch a bug, add styling for a new plugin, or improve the mobile experience, the source is well-organized and the build process is fully automated via GitHub Actions — so getting started requires nothing more than a text editor and a GitHub account.

​
Contribution Scope

Welcome Contributions

  • Bug fixes for existing styling
  • Support for additional community plugins
  • Mobile display improvements
  • Color scheme additions (submitted via GitHub Discussions)

Discuss First

Entirely new features should be proposed before implementation. Open a Draft PR or a GitHub Issue to align on scope before writing code.
To suggest a new color scheme for inclusion in Shimmering Focus, use the dedicated GitHub Discussions category. Classic, well-known color schemes are especially welcome.

​
Source Structure

All CSS source files live in the source/ directory of the repository. Do not edit theme.css at the repo root directly — it is compiled output and will be overwritten by the GitHub Action on every push. 
source/
├── 0-fonts/                   # Embedded font files (iA Writer Quattro, Recursive, Material Icons)
├── 1-colorschemes/            # Color scheme CSS files
│   ├── 00_Default.css
│   ├── Coffee.css
│   ├── Everforest.css
│   ├── Gruvbox.css
│   └── macOS-native.css
├── 2-variables/               # CSS custom property definitions
│   ├── shapes.css
│   └── variables.css
├── 3-markup/                  # Callouts, headings, images/tables, markdown elements
│   ├── callouts.css
│   ├── headings_inline-title.css
│   ├── images_tables_embeds.css
│   └── markdown.css
├── 4-user-interface/          # Header bar, tab bar, sidebars, status bar, and more
│   ├── header-bar.css
│   ├── notice_dropdown_input_sliders_context-menu.css
│   ├── quick-switcher_command-palette.css
│   ├── search-container.css
│   ├── settings_plugin-theme-browser.css
│   ├── sidebars.css
│   ├── statusbar.css
│   └── tab-bar.css
├── 5-editor/                  # Editor, frontmatter, gutter, search matches, vim mode
│   ├── active_note_or_block.css
│   ├── editor.css
│   ├── frontmatter_metadata.css
│   ├── gutter_folds.css
│   ├── search-matches.css
│   └── vim-mode.css
├── 6-plugins/                 # Core and community plugin styling
│   ├── community_plugins.css
│   ├── core_plugins.css
│   ├── longform-plugin.css
│   └── style_settings_plugin.css
├── header.txt                 # Header text prepended to the compiled theme.css
└── style-settings.yaml        # Style Settings plugin configuration
Do not save .css files directly at the source/ level — place them inside the numbered subdirectories. The build concatenates files using ./source/**/*.css globbing, which only matches exactly two levels deep (for cross-shell compatibility between zsh locally and bash in GitHub Actions).

​
Style Settings YAML

When adding new user-facing customization options, edit source/style-settings.yaml. This file is appended to the compiled theme.css inside a /* @settings … */ block so that the Style Settings plugin can parse it.

​
Build Process

The theme uses lightning-css for syntax lowering, which means you can write modern CSS in the source files and the compiled output remains compatible with older Obsidian installer versions. Modern CSS features you can use freely in source files: Browser target for compilation: chrome 108 (corresponding to Obsidian installer 1.1.9). The GitHub Actions workflow (build-and-bump.yml) runs on every push to main that touches the source/ directory and performs the following steps automatically:
  1. Concatenates all source/**/*.css files in alphabetical (numbered) order
  2. Runs lightning-css --minify --browserslist for syntax lowering and minification
  3. Writes a /* header */ comment block from source/header.txt, then appends the minified CSS
  4. Appends the Style Settings YAML block from source/style-settings.yaml inside a /* @settings … */ block
  5. Runs doiuse to check for unsupported CSS features against the browser target
  6. Bumps the patch version in manifest.json
  7. Updates the download count badge in README.md
  8. Regenerates Changelog.md from the git log
  9. Commits the updated theme.css, manifest.json, README.md, and Changelog.md back to main

​
Development Workflow

1

Fork and clone the repository

Fork chrisgrieser/shimmering-focus on GitHub and clone your fork locally.
git clone https://github.com/<your-username>/shimmering-focus.git
cd shimmering-focus
2

Install dependencies (optional, for local checks)

The two dev dependencies are lightningcss-cli (the compiler) and doiuse (CSS compatibility checker). They are only needed if you want to run a local build or lint check.
npm install
3

Edit CSS source files

Make your changes inside the appropriate subdirectory of source/. For example, to fix a plugin styling issue, edit source/6-plugins/community_plugins.css. To add a Style Settings option, also update source/style-settings.yaml.
4

Local build and hot-reload (optional)

If you have a local Obsidian vault configured, you can use the just task runner to build and hot-reload without pushing to GitHub. The personal-build-and-reload task concatenates all source CSS and copies the result into every vault listed in ~/.config/perma-repos.csv.
just personal-build-and-reload
There is also a formatter task for non-CSS files (uses biome):
just biome-check-and-format
The local build task uses zsh-style globbing and is intended for macOS development. The canonical build runs on GitHub Actions (which uses bash). Both produce identical output because CSS files are stored exactly two levels deep inside source/.
5

Commit with a semantic commit message

Commit messages must follow the Conventional Commits format. PR titles are validated automatically by the semantic-pr-title workflow. Allowed types are:
TypeUse for
fixBug fixes
featNew styling features
improvImprovements to existing styling
refactorCode reorganization without behavioral change
choreMaintenance tasks
docsDocumentation updates
breakBreaking changes (removed settings, etc.)
revertReverting a previous commit
git commit -m "fix: sidebar tab buttons not showing on hover (#123)"
6

Push and open a Pull Request

Push your branch to your fork and open a Pull Request against main. If you are proposing a new feature rather than a bug fix, open it as a Draft PR first so the scope can be discussed before review.Once the PR is merged, the GitHub Action compiles the source automatically and commits the updated theme.css — no manual build step is required.

​
Tooling Reference

lightning-css

CSS compiler and minifier. Handles syntax lowering of modern CSS (nesting, :has()) to the chrome 108 browser target. Configured via BROWSERSLIST environment variable in the workflow.

doiuse

CSS compatibility checker. Validates theme.css against the browser target after compilation. Ignored rules are listed in .doiuse-ignore.json (css-text-indent, text-decoration).

biome

Code formatter for non-CSS files (YAML, JSON, Markdown). Configured in biome.jsonc. Excludes theme.css from formatting. Run locally with just biome-check-and-format.

GitHub Actions

Four workflows: build-and-bump (main build), rumdl-lint (Markdown linting), semantic-pr-title (PR title validation), and stale-bot (auto-closes issues inactive for ~6 months).

​
Filing Issues and Feature Requests

For questions, bug reports, or feature requests, please open an issue on GitHub using one of the provided issue templates. Issue templates are located in .github/ISSUE_TEMPLATE/.
Due to the volume of messages received, inquiries made outside of GitHub (e.g. via email or social media) cannot be responded to. GitHub Issues is the only supported channel.

Build docs developers (and LLMs) love

Get started for freeTalk to us