Skip to main content

MAC Obsidian Plugin

PropertyValue
descriptionMAC Obsidian Plugin
tagsindex, doc, mac-obsidian-plugin

Overview

MAC Obsidian Plugin is intended to handle the behavior and compatibility layer for this vault inside Obsidian.

Where a theme handles how things look, the plugin should handle the things that require actual logic:

  • custom rendering
  • compatibility helpers
  • richer preview behavior
  • authoring workflow improvements

Current Status

There is currently a local plugin scaffold in this vault:

  • .obsidian/plugins/mac-obsidian-plugin/

But it is not in a stable or trusted state right now.

The earlier code-file embed experiment was started, then intentionally stripped back, so the current local plugin folder should be treated as groundwork only, not as an active feature set.

Why It Exists

This vault is authored in Obsidian but published through a heavily customized Docusaurus pipeline.

That means some markdown patterns work very well on the site but not locally in Obsidian.

MAC Obsidian Plugin exists to reduce that gap without changing the canonical source files just to satisfy local preview behavior.

Planned Scope

The plugin should stay narrow and solve real authoring problems.

Planned areas include:

  • code-file embeds
  • Docusaurus admonitions
  • Docusaurus tabs
  • other small compatibility helpers only when they clearly reduce friction

It should not become a giant “make Obsidian behave exactly like the site” parser.

Planned Implementation Order

1. Code-File Embeds

This is still the right first feature.

The intended behavior is:

  • detect allowlisted embedded local code/config files
  • read the target file through the Obsidian vault API
  • render the file as a normal Obsidian code block
  • show the filename above the block
  • show an Edit file action
  • use a generous file-size cap
  • if the cap is exceeded, leave the embed alone and let Obsidian render it normally

That fallback behavior is important. The plugin should degrade conservatively, not try to force everything through a custom renderer.

2. Docusaurus Admonitions

After code-file embeds, the next feature should be better local rendering for Docusaurus admonition syntax such as:

  • :::note
  • :::tip
  • :::info
  • :::warning
  • :::danger

This is the next most useful authoring improvement because it solves a real mismatch between the canonical vault syntax and the local preview experience.

3. Docusaurus Tabs

After admonitions, the next likely feature is handling Docusaurus tabs such as:

  • Tabs
  • TabItem

Tabs are intentionally later because they are more structurally involved and more likely to need a richer editor/rendering approach.

Constraints

MAC Obsidian Plugin should focus on:

  • compatibility
  • authoring quality
  • preview correctness
  • targeted workflow improvements

It should not:

  • mutate vault files just to improve preview
  • duplicate theme responsibilities
  • try to reproduce the entire site stack inside Obsidian

Relationship To Other MAC Docs Products

  • MAC Docusaurus is the active site-side build and compatibility layer
  • MAC Obsidian Theme is the planned Obsidian-side visual layer
  • MAC Obsidian Plugin is the planned Obsidian-side behavior layer

The long-term goal is one canonical vault that works well in both places:

  • Obsidian for writing
  • Docusaurus for publishing