Help
Powered by

# Style guide

The Obsidian documentation uses the Google developer documentation style guide. For any topics not covered by the Google style guide, use the Microsoft Style Guide.

This page lists any deviations from the Google style guide, or terminology worth highlighting.

# Terminology and grammar

# Language style

For our English documentation, it is recommended to use Global English to better serve our worldwide audience.

# Terms

  • Prefer "keyboard shortcut" over "hotkey". Use Hotkey when referring to the specific feature.
  • Prefer "the Obsidian app" on mobile, and "the Obsidian application" on desktop.
  • Prefer "sync" or "syncing" over "synchronise" or "synchronising".
  • Prefer "search term" over "search query".
  • Prefer "heading" over "header" when referring to a text that introduces a section.
  • Prefer "maximum" over "max" and "minimum" over "min".

# Product names

Obsidian product names start with "Obsidian", for example "Obsidian Publish" and "Obsidian Sync".

If a paragraph becomes overly repetitive, you can use the short form in subsequent references.

For example:

To allow device-specific configuration, Obsidian Sync doesn't sync its own settings. You need to configure Sync for each of your devices.

# UI and interactions

  • Use bold to indicate button text
  • Prefer "select" over "tap" or "click".
  • Prefer "sidebar" over "side bar".
  • Prefer "perform" over "invoke" and "execute" when referring to commands or actions.

When referring to multiple UI interactions in a sequence, use the → (U+2192) symbol. For example, "Settings → Community plugins".

# Notes, files, and folders

  • Use "note" when referring to a Markdown file in the vault.
  • Use "file" when referring to other file extensions than Markdown.
  • Prefer "note name" over "note title".
  • Prefer "active note" over "current note".
  • Prefer "folder" over "directory".
  • Prefer "file type" over "file format", unless specifically referring to the data format of the file content.

When moving between notes, use "open" if the destination is hidden, and "switch" if both source and destination notes are open in separate splits.

# Reference documentation for settings

When possible, any settings should be documented within Obsidian using a descriptive text. Avoid documenting a specific setting in Obsidian Help unless:

  • It requires more in-depth knowledge on how and when to use it.
  • It's commonly misused or asked about.
  • It drastically changes the user experience.

Consider using a tip callout if you want to draw attention to a specific setting.

# Directional terms

Hyphenate directional terms when using them as adjectives. Avoid hyphenation when direction is used as a noun.

Recommended:

  • Select Settings in the bottom-left corner.
  • Select Settings in the bottom left.

Not recommended:

  • Select Settings in the bottom left corner.
  • Select Settings in the bottom-left.

Prefer "upper-left" and "upper-right" over "top-left" and "top-right".

Don't indicate a direction when referring to settings. The location of the settings control depends on the device.

Recommended:

  • Next to Pick remote vault, select Choose.

Not recommended:

  • To the right of Pick remote vault, select Choose.

# Instructions

Use imperatives for the names of guides, section headings, and step-by-step instructions. The imperative mood is concise and action-oriented, which is more straightforward for users following instructions.

  • Prefer "Set up" over "Setting up"
  • Prefer "Move a file" over "Moving a file"
  • Prefer "Import your notes" over "Importing your notes"

# Sentence case

Prefer sentence case over title case for headings, buttons, and titles. When referencing UI elements always match the case of the text in the UI.

Recommended:

  • How Obsidian stores data

Not recommended:

  • How Obsidian Stores Data

# Examples

Prefer realistic examples over nonsense terms.

Recommended:

  • task:(call OR schedule)

Not recommended:

  • task:(foo OR bar)

# Key names

When referring to a character on the keyboard by name, add the character between parentheses right after the name:

Recommended:

  • Add a hyphen (-) in front of the word.

Not recommended:

  • Add a hyphen in front of the word.
  • Add a - in front of the word.

# Markdown

Use newlines between Markdown blocks:

Recommended:

# Heading 1

This is a section.

1. First item
2. Second item
3. Third item

Not recommended:

# Heading 1
This is a section.
1. First item
2. Second item
3. Third item

# Images

Use "width x height pixels" for describing image or screen dimensions.

Example:

Recommended image dimensions: 1920 x 1080 pixels.

# Icons and images

Include icons and images when they make it easier to explain things that are hard to describe with words, or when you need to show important parts of the Obsidian application. You can save images in the Attachments folder.

  • The image should make the text it accompanies easier to understand.

Example: Once enabled, the Word count plugin will create a new entry on your bottom statusbar.

  • Images should be in either .png or .svg format.
  • If an image looks too big in the note, make it smaller outside of Obsidian, or adjust its dimensions as explained in embedding an image in a note.
  • In rare cases, you may want to place especially large or complex images in a folded callout.
  • For pop-up windows or modals, the image should show the entire Obsidian application window.

# Icons

Lucide and custom Obsidian icons can be used alongside detailed elements to provide a visual representation of a feature.

Example: In the ribbon on the left, select Create new canvas ( ) to create a canvas in the same folder as the active file.

Guidelines for icons

  • Store icons in the Attachments/icons folder.
  • Add the prefix lucide- before the Lucide icon name.
  • Add the prefix obsidian-icon- before the Obsidian icon name.

Example: The icon for creating a new canvas should be named lucide-layout-dashboard.

  • Use the SVG version of the icons available.
  • Icons should be 18 pixels in width, 18 pixels in height, and have a stroke width of 1.5. You can adjust these settings in the SVG data.
  • Utilize the icon anchor in embedded images, to tweak the spacing around the icon so that it aligns neatly with the text in the vicinity.
  • Icons should be surrounded by parenthesis. ( )

Example: ( ![[lucide-cog.svg#icon]] )

# Image anchor tags

Image anchors tags are available to add decorative changes to the embedded images.

Icon

![[lucide-menu.svg#icon]]

The icon anchor tag ensures correct vertical alignment for icons used to indicate interface elements.

The first menu icon uses the anchor tag ( ), while the second menu icon ( ) does not.

Interface

![[Vault picker.png#interface]]

The interface anchor tag adds a decorative box shadow around the image. In the first image, the interface anchor tag is applied.

In contrast, the second image does not have the interface anchor applied.

Outline

![[Backlinks.png#outline]]

The outline anchor tag adds a subtle border around the image. In the first image, the outline anchor tag is applied.

The second image lacks the outline anchor tag.

# Optimization

Images slow the loading time of the page, and take valuable Publish storage space. Optimizing images allows a reduction in file size, but maintains the visual integrity of the image.

Both images and icons should be optimized.

# Layout

# Broken links

Before submitting your Pull Request, please check for any broken links in the documentation of the translation you are working on and correct them. Broken links can occur naturally over time, so verifying their accuracy helps maintain the quality of the documentation.

You can check for broken links using Community plugins or tools available in your IDE.

# Descriptions

This documentation is edited on GitHub and hosted online via Obsidian Publish, which includes descriptions for social cards and other SEO elements.

If the page you are working on does not have a description property, please add one. The description should be 150 characters or fewer and provide an objective summary of the page’s content.

Good: Learn to create templates that capture and organize web page metadata automatically with Web Clipper. Could be tweaked: Learn how to create templates that automatically capture and organize metadata from web pages with Web Clipper.

# Directions

When writing or rewriting Instructions on how to perform an action within the app, be sure to include steps for both the mobile and desktop versions.

If you do not have access to a mobile or desktop device, please mention this when submitting your Pull Request.

# Translations

Translate the entirety of the content when completing a translation. This includes and is not limited to:

  • Note names
  • Folder names
  • Aliases
  • Attachment names
  • Alt link text

© 2025 Obsidian