# Style guide

The Obsidian documentation follows the style guidelines listed on this page. These guidelines are based on industry best practices, particularly the Google developer documentation style guide and Microsoft Style Guide. For edge cases not covered below, consult those external guides as secondary references.

For our English documentation, it is recommended to use Global English to better serve our worldwide audience and to assist with Translations. This means:

• Avoiding idioms and culturally-specific expressions
• Using active voice and direct sentence construction
• Preferring simple, common words over complex terminology
• Being explicit rather than implied
• For spelling conventions, use American English (e.g., 'organize' not 'organise').

• 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".

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.

• Use bold to indicate button text
• Prefer "select" over "tap" or "click".
  • For mobile-specific instructions, "tap" is acceptable when describing touch interactions as "click" is not available.
• 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".

• 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.

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.

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.

When describing vertical direction in UI elements, use "above" and "below" for spatial relationships. Avoid "up" and "down" as they're ambiguous in different contexts.

Recommended:

• The search box appears above the file list.
• Additional options are available below.

Not recommended:

• The search box is up from the file list.
• More options are down below.

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"

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

Prefer realistic examples over nonsense terms.

Recommended:

• task:(call OR schedule)

Not recommended:

• task:(foo OR bar)

When referring to keyboard keys and shortcuts, use consistent notation.

Individual key names:

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

Recommended:

• Press the hyphen (-) key to add a dash.
• Use the question mark (?) to search.

Not recommended:

• Press the hyphen key to add a dash.
• Use the ? to search.
• Add a - in front of the word.

Keyboard shortcuts:

Format keyboard shortcuts with no spaces around the plus sign. When a shortcut differs between operating systems, specify both.

Recommended:

• Press Ctrl+Z (Windows) or Command+Z (macOS) to undo.
• Press Escape to close this window.
• Use Tab to move between fields.

Not recommended:

• Press Cmd+Z to undo.
• Press Ctrl + Z (with spaces) to undo.
• Press Ctrl/Cmd+Z to undo.

For shortcuts that are identical across all platforms, you don't need to specify the OS. If you're unsure whether a shortcut differs by platform, specify the OS to be safe. Windows and Linux typically use the same shortcuts.

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

Em dashes in lists:

Use em dashes (—) to separate bolded terms from their descriptions in bullet lists. Do not use em dashes in simple nested bullet lists with links.

Recommended:

• View menu — create, edit, and switch views.
• Calculate values — add prices, compute totals, or perform math operations.

Not recommended:

• Create a base — Learn how to create and embed a base.

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

Example:

Recommended image dimensions: 1920 x 1080 pixels.

Use callouts strategically to highlight specific types of information:

Tip ([!tip]-) - Practical advice or best practices that enhance the user's workflow. Use for shortcuts, workarounds, or non-essential but helpful information. These callouts start out collapsed.

Info ([!info]+) - Additional context, background information, or clarifications. Use when information adds understanding but isn't required to complete a task. These callouts start out open.

Warning ([!warning]+) - Important cautions that prevent data loss, errors, or unintended consequences. Use sparingly for genuinely risky situations. These callouts should never be collapsed.

Example ([!example]-) - General asides or supplementary details. Use for tangential information that some users may find relevant. These callouts start out collapsed.

Examples:

> [!tip]- Use keyboard shortcuts
> You can speed up your workflow by memorizing the most-used shortcuts.

> [!info]+ This is a paid addon
> This feature requires a paid subscription to use.

> [!warning]+ This action cannot be undone
> Deleting a vault is permanent. Consider exporting your notes first.

> [!example]- Advanced usage
> You can also configure this setting via the Graph menu.

Use lists when presenting discrete items that don't have strong sequential or causal relationships. Use prose and paragraphs when items build on each other, require explanation, or benefit from narrative flow.

Use a list for:

• A set of unrelated features
• Installation requirements
• Configuration options
• Troubleshooting steps

Use prose for:

• Explanations of how something works
• Workflows with dependencies
• Conceptual overviews
• Guidance requiring context

Use tables to compare features, versions, or related data points where alignment aids understanding. Avoid tables for simple lists or single-column data.

Good use case:

Use internal wiki links ([[Note name]]) liberally to help users navigate related topics. However, avoid over-linking:

• Don't link the same term multiple times in a single page
• Link only when the referenced page provides significant added context
• Use descriptive link text when helpful: [[Note name#Section|descriptive text]]

Example:

First mention: "Learn about Obsidian Sync to keep your vault updated across devices." Later mention: "You can configure Sync for each device separately."

When documenting features that differ between platforms, use section headings to organize the content.

Use Desktop and Mobile as subsection headings to separate platform-specific instructions or features.

Recommended:

## Customizing the ribbon

### Desktop

On the desktop version, you can customize the ribbon as follows:

- Rearrange the order of ribbon actions by dragging and dropping the icons.
- To hide specific actions, right-click on an empty space and uncheck the actions you want to hide.

### Mobile

In the mobile version, you can customize the ribbon through settings:

1. Open **[[Settings]]**.
2. Navigate to **Appearance**.
3. Click **Manage** under **Ribbon menu**.

[!info]+ When to create sections? Only create separate sections if content significantly differs. If instructions are largely the same with minor variations, use inline notes instead.

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.

  

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.

<svg xmlns="http://www.w3.org/2000/svg" width="WIDTH" height="HEIGHT" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="STROKE-WIDTH" stroke-linecap="round" stroke-linejoin="round" class="lucide lucide-layout-dashboard"><rect width="7" height="9" x="3" y="3" rx="1"/><rect width="7" height="5" x="14" y="3" rx="1"/><rect width="7" height="9" x="14" y="12" rx="1"/><rect width="7" height="5" x="3" y="16" rx="1"/></svg>

• 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 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.

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.

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.

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.

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.

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.

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