Creating and Publishing Your Own Obsidian Theme

Introduction

Obsidian's great appeal lies in the ability to freely customize its appearance by editing CSS.

In this article, I have summarized the process from not just using existing themes, but creating your own and publishing it as an official Community Theme.

TL;DR (3-Line Summary)

• Conclusion 1: Organized the flow for creating and publishing an Obsidian theme.

• Conclusion 2: Creation itself is not difficult if you use the official template.

• Conclusion 3: Care is needed regarding "image size" and "JSON descriptions" during the PR.

Target Audience (Who is this for?)

• People interested in customizing Obsidian.

• People who want to create and distribute their own themes.

• People who want to know the key points for passing the theme review.

Background / Challenges

As I used Obsidian more deeply, specific needs emerged, such as "I want to tighten this margin" or "I want a more eye-friendly color scheme." While it's possible to fix these with snippets (CSS fragments), I thought, "I might as well build it as a complete theme and try publishing it."

However, throughout the process from theme creation to registration in the official list (Pull Request), I encountered several minor regulations and pitfalls. I am recording them here as a reference.

Main Topic / Solution

Here, I will explain the steps from creating a theme according to the official recommended procedure to applying for registration.

Specific Procedures

1. Creating the Base for Your Theme

The fastest way to start is by using the official template provided by Obsidian.

1. Access obsidian-sample-theme on GitHub.

2. Click the "Use this template" button in the top right of the screen and fork it (create a repository) to your own account.

3. clone the created repository to your local machine.

2. Editing Design and Metadata

Edit the files locally to create your original theme.

• theme.css: This is the body of your design. Override CSS variables to adjust colors and layouts.

• manifest.json: Describes the theme's information (name, version, author name, etc.).

  manifest.json

  {
    "name": "My Custom Theme",
    "version": "1.0.0",
    "minAppVersion": "0.15.0",
    "author": "Your Name"
  }
  

3. Preparing Files for Publication

Prepare the information needed for your theme to be displayed in the store.

• README.md: Write a manual for the users.
  

• screenshot.png: Create a thumbnail image that will be displayed in the store list.
  

4. Creating a Release

Perform the release process on GitHub.

1. Commit and push your changes.

2. If GitHub Actions are set up in your repository, distribution files (theme.css, manifest.json) will be generated by tagging or manually creating a Release.

5. Applying for Official Registration (Pull Request)

This is the procedure to have your theme added to the official Obsidian list.

1. Fork obsidian-releases.

2. Edit community-css-themes.json in your forked repository and add your theme information to the end.

3. Send a Pull Request to the original repository. The default Pull Request template contains links for plugins or themes; preview it and click the theme link.

4. Follow the theme Pull Request template to fill in the details and check off the checklist.

5. Automatic tests will run, so ensure they Pass.

6. Wait for the reviewer's check, fix any issues if pointed out, and once merged, you are done.

Development Tips
To check the appearance locally, you can immediately see the changes by placing the files you are working on (theme.css, manifest.json) inside the .obsidian/themes/ folder within your Obsidian Vault.

Details, Observations, and Points to Note

I will share the points where I stumbled (things likely to be pointed out during review) based on my experience actually applying.

1. Folder Name and Manifest Name Must Match Exactly

This is a point to note during local testing and distribution.

The folder name placed in .obsidian/themes/ must match the name field in manifest.json exactly. If these differ, Obsidian may not recognize the theme correctly.

2. Branch Names Are Not Required in the JSON Description

When adding an entry to community-css-themes.json, you specify the GitHub repository URL, but you must not include branch names (such as main or master) here.

kinn00kinn/LatteLogic

3. Screenshot Resolution Requirements

There are strict size regulations for the screenshot.png displayed in the store.

• Required Resolution: 512 × 288 px

If you submit it at any other size (for example, leaving it at FHD resolution), it will be rejected by the bot or the reviewer. Even if the aspect ratio is correct, it will be rejected if the pixel count is different, so you need to match it precisely using a resizing tool or similar.

Summary

Creating an Obsidian theme can be enjoyed relatively freely if you have knowledge of CSS, but there are several "etiquettes" for registering it in the official list.

• Steps: Fork the template to create it, then send a PR to obsidian-releases.

• Notes: Ensure file name consistency, follow JSON description rules, and adhere to image resolution (512x288).

By clearing these points, you have a chance for users all over the world to use your theme. Please give it a try. If you like it, it would be very encouraging if you could give a star to the GitHub repository!

Reference Links

• Build a theme - Obsidian Help

• obsidian-sample-theme (GitHub)

• The theme I created this time