[FR] Markdown-Based File Format for Canvas

[Developer-Mike]

Background

The current JSON-based Canvas file format has several issues:

• Poor Extensibility: No standardized way to extend the basic fields
• Lack of Versioning: No version field, making improvements to the whole format nearly impossible without breaking compatibility.
• No Metadata Object: No structured way to store additional information. It only supports nodes and edges as keys for the top level keys.
• Poorly Named JSON Keys: The current keys (In my opinion) are poorly named and structured.

While the metadataCache issue for Canvas files was recently resolved by this plugin, I believe a Markdown-based format could provide additional benefits.

Proposal: Markdown-Based Canvas Files

Instead of JSON, Canvas files could be represented in a Markdown-based format that integrates naturally with Obsidian’s core features. Benefits include:
✅ Human Readability – Markdown is easy to read and edit, aligning with the needs of many Obsidian users.
✅ Full Linking Support – Allows linking to subtitles, textblock IDs, and even specific nodes (which is currently not even possible).
✅ Frontmatter Support – Enables metadata, making it easier to work with.
✅ Improved Searchability – Markdown files can be searched using Obsidian’s default search.
✅ Enhanced Metadata Handling – Tags, properties, and other metadata can be stored in a structured way.

Proposed Format

A possible format could be (Backslash before backtick only there for GitHub to format it properly):

--- node ---
# Node Id
edges: [[#Other Node Id]] [[#And Another Node Id]]
\```node-attributes
x: 100
y: 100
styleAttributes: { "border": "invisible" }
\```

# Anything
This is the markdown content of the node.

--- node ---
# Other Node Id
...and so on

The addition of this format by Advanced Canvas would allows users to seamlessly switch between the Markdown view and the Canvas view, offering flexibility in how they interact with their files.

Questions for the Community

• What do you think about this approach?
• How can we improve this format further?
• Is this even a good idea and what would be the priority of implementing something like this?

Would love to hear your thoughts! 🚀

[brimwats]

From a metadata angle this looks pretty solid to me! I'm wondering if you'd run into any issues with the YAML, Markdown, or JSON specs this way? Not necessarily saying I notice anything or that its necessary, just a consideration

[Developer-Mike]

Thanks for sharing your thoughts. If I'm not completely wrong, neither the YAML, MD, nor JSON format would get in the way.

MD: While it would be the file type of the whole format, only the actual node content would get stored as MD text.
YAML: This only affects the frontmatter and it won't differ from other MD files' frontmatter.
JSON: The only JSON this file format would store is the nodes/edges metadata. But this JSON would (currently) be stored inside a custom MD code block.

Please correct me if I'm wrong.

[jessmartin]

@Developer-Mike Really nice plugin! We've been working on an infinite canvas format for over a year that I think you should check out: https://spec.canvasprotocol.org. I think it should more than meet your needs. If it doesn't we'd certainly like to know why, as we're designing it for this use case.

It's JSON rather than Markdown, but I'd be up for helping with a "render to Markdown" version if markdown is something you're committed to.

[Developer-Mike]

Thank you for your proposal. I think a fundamental problem is the json format. First of all, I don't want users to have "useless" files upon disabling the plugin. Secondly, I really think plain markdown is the way to go (for easier embeds and native frontmatter/indexing). I hope you understand.

[jessmartin]

@Developer-Mike I definitely understand the desire for readability and longevity!

With OCIF, we had early conversations about the importance of readability and being able to directly edit the canvas by editing the text file. We ultimately decided that the most common reader/writer of the file format would actually be computers, so JSON made more sense. The Obsidian community is a notable exception to that general rule, however.

However, I love these little custom markdown DSLs for specific data types. I'll keep an eye on where you're going here, and if your markdown format looks compelling, maybe we'll implement it in the OCIF toolchain as a OCIF -> MD exporter!