The CachedMetadata interface represents the parsed and cached metadata for a file in the vault. This includes links, embeds, tags, headings, frontmatter, and other structural elements.
Interface Definition
export interface CachedMetadata
Properties
Array of internal links found in the file. Each link includes position information and the link text.
Array of embedded files (using ![[]] syntax). Includes images, PDFs, and other embedded content.
Array of tags found in the file (both #tag and frontmatter tags).
Array of headings found in the file, with information about heading level and position.
Available since version 1.6.6
Available since version 1.8.7
Available since version 1.8.7
[link]: https://example.com).Sections are root level markdown blocks, which can be used to divide the document up.
Array of list items found in the file.
Parsed frontmatter data from the YAML front matter block.
Available since version 1.4.0
Available since version 1.4.0
blocks
Record<string, BlockCache>
A mapping of block IDs to their cache information. Block IDs are defined using the ^block-id syntax.
CacheItem
Base interface for cached items that have a position in the file.
export interface CacheItem {
position: Pos;
}
Pos
Represents a position range in a file.
export interface Pos {
start: { line: number; col: number; offset: number };
end: { line: number; col: number; offset: number };
}
Example
const file = this.app.workspace.getActiveFile();
if (file) {
const cache = this.app.metadataCache.getFileCache(file);
if (cache) {
// Access headings
if (cache.headings) {
cache.headings.forEach(heading => {
console.log(`Level ${heading.level}: ${heading.heading}`);
});
}
// Access links
if (cache.links) {
cache.links.forEach(link => {
console.log(`Link to: ${link.link}`);
});
}
// Access tags
if (cache.tags) {
cache.tags.forEach(tag => {
console.log(`Tag: ${tag.tag}`);
});
}
// Access frontmatter
if (cache.frontmatter) {
console.log('Title:', cache.frontmatter.title);
console.log('Tags:', cache.frontmatter.tags);
}
// Access blocks
if (cache.blocks) {
for (const blockId in cache.blocks) {
console.log(`Block ID: ${blockId}`);
}
}
}
}
Use Cases
Building a Table of Contents
function buildTableOfContents(file: TFile): string[] {
const cache = this.app.metadataCache.getFileCache(file);
if (!cache || !cache.headings) return [];
return cache.headings.map(heading => {
const indent = ' '.repeat(heading.level - 1);
return `${indent}- ${heading.heading}`;
});
}
Finding All Links in a File
function getAllLinks(file: TFile): string[] {
const cache = this.app.metadataCache.getFileCache(file);
if (!cache) return [];
const links: string[] = [];
// Links from content
if (cache.links) {
links.push(...cache.links.map(link => link.link));
}
// Links from embeds
if (cache.embeds) {
links.push(...cache.embeds.map(embed => embed.link));
}
// Links from frontmatter
if (cache.frontmatterLinks) {
links.push(...cache.frontmatterLinks.map(link => link.link));
}
return links;
}
import { getAllTags } from 'obsidian';
function extractTags(file: TFile): string[] | null {
const cache = this.app.metadataCache.getFileCache(file);
if (!cache) return null;
// Use the built-in helper function
return getAllTags(cache);
}
