Block-level properties: metadata below the note level
Use case or problem
Properties in Obsidian exist at the note level. A note can have a status, a type, a project assignment – but the note is the smallest unit that can carry metadata. Everything below that level – sections, paragraphs, individual blocks – is invisible to the property system.
This creates friction in several workflows.
Technical documentation. A guide or reference document is rarely uniform. Some sections become outdated while others remain current. Some sections target beginners, others assume advanced knowledge. Some sections describe features introduced in a specific version. Currently, there’s no way to mark these distinctions at the section level. The entire document has one status, one audience, one version – even when different parts have different characteristics.
A practical example: A documentation file covers an API. Section A describes a stable endpoint, Section B describes a deprecated endpoint (removed in v3.0), Section C describes a new endpoint (added in v2.5). There’s no way to query “show me all deprecated sections across my documentation” or to mark Section B as deprecated: true, removed-in: v3.0 without creating a separate note for each section – which fragments the document unnaturally.
Long-form writing. A novel chapter or essay isn’t monolithic. Different passages may be in different states – one paragraph is polished, another needs revision, a third requires fact-checking. Different passages may have different characteristics worth tracking – POV shifts, timeline markers, connections to other parts of the manuscript.
A practical example: A scene contains a flashback embedded in present-time narration. The flashback paragraph should link to the event it references elsewhere in the manuscript. The surrounding paragraphs exist in a different timeline. Currently, this temporal structure can only be expressed through prose or comments – it’s not queryable, not filterable, not systematically trackable.
Reference materials. Notes that aggregate information from multiple sources – literature notes, research compilations, meeting notes with multiple topics – contain blocks with different provenance, different confidence levels, different relationships to other notes.
A practical example: A literature note contains five key claims extracted from a paper. Each claim has a different relationship to other notes in the vault – one supports a hypothesis, one contradicts it, one is tangential. At the note level, this nuance is invisible. The note links to other notes, but which part of the note relates to which other note is lost.
The fundamental issue: Obsidian treats notes as atomic units, but knowledge isn’t atomic. Notes contain structure – sections, paragraphs, blocks – and that structure carries meaning that the current property system can’t capture.
Proposed solution
A system for attaching properties to blocks – paragraphs, sections, or any content chunk – with editor support for visibility and potential integration with query tools like Dataview.
Core concept
The idea extends the existing property system downward in granularity. Just as a note can carry frontmatter that describes the note as a whole, a block within that note could carry properties that describe just that block. These block-level properties would function independently of the note’s properties – a note might have status: complete while one of its sections has status: needs-update, because the document overall is finished but a specific section has fallen behind.
The key design questions center on how properties attach to blocks, how they’re displayed in the editor, and whether they become queryable.
For attachment, the system needs a clear way to associate a set of properties with a specific piece of content. This could work by extending existing block IDs, by wrapping content in a container syntax, or by using special comments that the parser recognizes. Each approach has trade-offs in terms of visual intrusiveness, compatibility with existing Markdown conventions, and ease of use.
For display, the goal is visibility without distraction. Properties should be accessible when needed – when editing, when reviewing structure, when looking for something that needs attention – but shouldn’t clutter the reading or writing experience. This suggests either a dimmed inline display that makes properties visible but visually secondary, or a hidden-by-default approach where properties reveal themselves on hover or through a dedicated panel.
For queryability, the full value emerges when block properties integrate with tools like Dataview. A query asking for “all blocks with status: deprecated” would return not notes, but specific sections within notes – with links that jump directly to the relevant block. This transforms how documentation can be maintained, how manuscripts can be tracked, how research can be organized. Instead of knowing “this note contains something deprecated,” the query shows exactly which section, in which document, needs attention.
Possible syntaxes
Several approaches could work. Each has trade-offs in readability, compatibility, and implementation complexity. Presenting three options for discussion:
Option A – Block-ID extension
Obsidian already supports block IDs with the ^block-id syntax for creating references to specific blocks. This existing infrastructure could be extended to carry properties alongside the ID. A section about installation could end with a line that both identifies the block and attaches metadata to it – marking it as needing an update, specifying which version it applies to, indicating its target audience. The syntax would feel familiar to anyone already using Dataview’s inline fields, but with the crucial difference that these properties attach to the specific block rather than the note as a whole.
The advantage of this approach is that it builds on existing behavior. Block IDs are already parsed and understood. The extension is conceptually minimal – just allowing more information to travel with the ID. The disadvantage is that it only works for blocks that have IDs, and it might create confusion with current block-reference behavior.
Option B – Wrapper syntax
An alternative approach uses explicit fences to wrap content and attach properties to it. Similar to how code blocks use triple backticks to fence code, a wrapper syntax could use a different marker to fence content that carries metadata. The opening fence would include the properties in an attribute syntax – key-value pairs that describe the wrapped content.
This approach provides clear visual boundaries. There’s no ambiguity about which content the properties apply to – everything between the opening and closing fence. It can wrap multiple paragraphs, entire sections, or even nested structures. The syntax resembles Pandoc’s fenced divs, which may be familiar to users coming from academic or technical writing backgrounds. The disadvantage is visual intrusiveness – the fences add lines to the document that aren’t content, and deeply nested wrappers could become hard to read.
Option C – Comment-based
A third approach hides properties in special comments that the parser recognizes and associates with the following block. This keeps the document visually clean – in reading view, the properties are invisible. In editing view, they appear as comments, clearly distinct from content. The parser knows to interpret these specific comments as metadata rather than as regular comments.
The advantage is minimal visual disruption. The document reads naturally; the metadata is present but unobtrusive. The disadvantage is discoverability – it’s less obvious that a block has properties when those properties are hidden. There’s also the risk of accidental deletion if someone removes what looks like a comment without realizing it carries structural information.
Visibility and interaction
Block properties should be visible in the editor but not intrusive. Two possible approaches:
Inline display with dimming. Properties appear in the editor, styled distinctly – grayed out, smaller font, different color – so they’re visible but clearly secondary to content. This keeps properties accessible without requiring extra interaction. Writers can see at a glance which blocks carry metadata and what that metadata says. The trade-off is visual density; documents with many block properties could feel cluttered.
Hover reveal. Properties are hidden by default. A small indicator – perhaps a subtle icon or a faint highlight – shows that a block has properties attached. Hovering over the indicator or the block itself reveals the properties in a tooltip or popover. This keeps the writing surface clean while maintaining access to the metadata. The trade-off is discoverability; properties don’t announce themselves, so they’re easy to forget about.
A setting could let users choose their preferred display mode. Different workflows might favor different approaches – dense technical documentation might benefit from visible properties, while long-form writing might prefer the cleaner hover-reveal interface.
Queryability as extension
The full value of block-level properties emerges when they’re queryable. This could integrate with Dataview or a similar tool, extending the query language to address blocks rather than just notes.
A query for deprecated sections across a documentation folder would return a list of blocks – not notes containing deprecated content, but the specific sections themselves. Each result would link directly to the block, using existing block-reference syntax. A table query could show all sections needing updates, with columns for version information, audience, and last-modified date – all at block granularity.
More sophisticated queries become possible once blocks carry properties. Find all flashback passages in a manuscript. Find all beginner-level sections across a tutorial series. Find all blocks linked to a specific source note. The vault becomes queryable at a finer grain than the note level.
This is a significant extension that would require coordination with Dataview or a new query system. It’s presented here as a logical evolution of the core proposal rather than a requirement for initial implementation. Even without queryability, block properties provide value for annotation and organization – but queryability is where the concept reaches its full potential.
Interaction with existing features
Block references. Block IDs already exist for creating references to specific blocks. Block properties would complement them – a block could have both an ID (for referencing) and properties (for metadata). The two features serve different purposes but could share syntax or infrastructure.
Inline fields. Dataview’s inline fields (field:: value) can appear anywhere in a note. But these fields aren’t block-scoped – they’re associated with the note as a whole, not with the specific paragraph they appear in. A query for notes with a certain inline field returns notes, not the blocks containing that field. Block properties would be explicitly scoped to their block, enabling queries that return blocks rather than notes.
Headings. Sections defined by headings are natural candidates for properties. A heading could implicitly define a block scope, with properties attached to the heading applying to the entire section until the next heading of equal or higher level. This would allow section-level metadata without requiring explicit block markers – the heading structure that already exists would serve as the block boundary.
Current workaround
Several partial workarounds exist, none satisfactory:
Splitting into multiple notes. Each section becomes its own note, with note-level properties. This fragments naturally unified content and creates navigation overhead. A documentation page that should be one coherent document becomes a folder of fragments. The cure is worse than the disease.
Inline fields in prose. Dataview’s field:: value syntax can appear anywhere in a note. But these fields aren’t block-scoped – they’re associated with the entire note, not the paragraph they appear in. Querying them returns notes, not blocks. The granularity problem remains unsolved.
Comments and conventions. Manual markers like %%TODO: update for v3%% or <!-- deprecated --> can annotate blocks. But these aren’t structured, aren’t queryable, and rely on human discipline to maintain consistency. They’re notes to self, not system-integrated metadata.
Tags on headings. Tags can appear after headings (## Installation #needs-update). This provides some block-level marking but is limited to headings, limited to tags (not key-value properties), and not queryable at the block level. It’s a partial solution that highlights the gap rather than filling it.
None of these approaches provide true block-level properties that are structured, queryable, and integrated into the editor experience.
Related feature requests
- Block metadata - extension of block-id syntax – a 2020 proposal for YAML-style block metadata, suggesting syntax like
^{id: block-id, key: value} - Make file metadata and properties separate concepts – discusses the distinction between note-level metadata and content metadata
- Being able to move properties to another place of the note – requests flexibility in property placement, related to the broader question of where metadata lives
- Assign metadata values to links – requests metadata on links, another form of sub-note-level properties