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 fileaction - 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:
TabsTabItem
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 Pluginis 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