Markdown Module

Content

Represents the body of a note, organized into titled sections.

Attributes:

Name	Type	Description
sections	Dict[str, ContentSection]	A dictionary mapping section titles to ContentSection objects.

Source code in ures/markdown/manipulator.py

class Content:
    """Represents the body of a note, organized into titled sections.

    Attributes:
        sections (Dict[str, ContentSection]): A dictionary mapping section titles to ContentSection objects.
    """

    def __init__(self):
        """Initializes an empty Content container."""
        self.sections: OrderedDict[str, ContentSection] = OrderedDict()

    def new_section(self, title: str, level: int):
        """Creates a new empty section if it does not already exist.

        Args:
            title (str): The unique title of the section.
            level (int): The Markdown heading level for the section.
        """
        if title not in self.sections:
            self.sections[title] = ContentSection(title, level)

    def add_section(self, section: ContentSection):
        """Adds an existing ContentSection object to the content.

        If a section with the same title already exists, this operation is ignored.

        Args:
            section (ContentSection): The section object to add.
        """
        if section.title not in self.sections.keys():
            self.sections[section.title] = section

    def add_content(
        self,
        content: Union[str, list],
        section_title: str = "default",
        section_level: int = 1,
    ):
        """Adds content to a specific section, creating the section if it does not exist.

        Args:
            content (str, list): The text content to add.
            section_title (str, optional): The title of the target section. Defaults to "default".
            section_level (int, optional): The heading level if a new section needs to be created. Defaults to 1.
        """
        if section_title not in self.sections:
            self.new_section(section_title, section_level)
        self.sections[section_title].add_content(content)

    def to_string(self) -> str:
        """Serializes the entire content into a Markdown-formatted string.

        Returns:
            str: The complete Markdown content with section headers.
        """
        markdown_lines: List[str] = []
        for section in self.sections.values():
            if section.title != "default":
                markdown_lines.append(f"{'#' * section.level} {section.title}")
            markdown_lines.extend(section.content)
            markdown_lines.append("")  # Add a blank line after each section
        return "\n".join(markdown_lines).strip()

__init__()

Initializes an empty Content container.

Source code in ures/markdown/manipulator.py

def __init__(self):
    """Initializes an empty Content container."""
    self.sections: OrderedDict[str, ContentSection] = OrderedDict()

add_content(content, section_title='default', section_level=1)

Adds content to a specific section, creating the section if it does not exist.

Parameters:

Name	Type	Description	Default
content	(str, list)	The text content to add.	required
section_title	str	The title of the target section. Defaults to "default".	'default'
section_level	int	The heading level if a new section needs to be created. Defaults to 1.	1

Source code in ures/markdown/manipulator.py

def add_content(
    self,
    content: Union[str, list],
    section_title: str = "default",
    section_level: int = 1,
):
    """Adds content to a specific section, creating the section if it does not exist.

    Args:
        content (str, list): The text content to add.
        section_title (str, optional): The title of the target section. Defaults to "default".
        section_level (int, optional): The heading level if a new section needs to be created. Defaults to 1.
    """
    if section_title not in self.sections:
        self.new_section(section_title, section_level)
    self.sections[section_title].add_content(content)

add_section(section)

Adds an existing ContentSection object to the content.

If a section with the same title already exists, this operation is ignored.

Parameters:

Name	Type	Description	Default
section	ContentSection	The section object to add.	required

Source code in ures/markdown/manipulator.py

def add_section(self, section: ContentSection):
    """Adds an existing ContentSection object to the content.

    If a section with the same title already exists, this operation is ignored.

    Args:
        section (ContentSection): The section object to add.
    """
    if section.title not in self.sections.keys():
        self.sections[section.title] = section

new_section(title, level)

Creates a new empty section if it does not already exist.

Parameters:

Name	Type	Description	Default
title	str	The unique title of the section.	required
level	int	The Markdown heading level for the section.	required

Source code in ures/markdown/manipulator.py

def new_section(self, title: str, level: int):
    """Creates a new empty section if it does not already exist.

    Args:
        title (str): The unique title of the section.
        level (int): The Markdown heading level for the section.
    """
    if title not in self.sections:
        self.sections[title] = ContentSection(title, level)

to_string()

Serializes the entire content into a Markdown-formatted string.

Returns:

Name	Type	Description
str	str	The complete Markdown content with section headers.

Source code in ures/markdown/manipulator.py

def to_string(self) -> str:
    """Serializes the entire content into a Markdown-formatted string.

    Returns:
        str: The complete Markdown content with section headers.
    """
    markdown_lines: List[str] = []
    for section in self.sections.values():
        if section.title != "default":
            markdown_lines.append(f"{'#' * section.level} {section.title}")
        markdown_lines.extend(section.content)
        markdown_lines.append("")  # Add a blank line after each section
    return "\n".join(markdown_lines).strip()

ContentSection

Represents a specific section within a note, containing a title, hierarchy level, and text content.

Attributes:

Name	Type	Description
title	str	The title of the section (e.g., "Introduction").
level	int	The heading level of the section (e.g., 1 for #, 2 for ##).
content	List[str]	A list of strings representing the lines of content in this section.

Source code in ures/markdown/manipulator.py

class ContentSection:
    """Represents a specific section within a note, containing a title, hierarchy level, and text content.

    Attributes:
        title (str): The title of the section (e.g., "Introduction").
        level (int): The heading level of the section (e.g., 1 for #, 2 for ##).
        content (List[str]): A list of strings representing the lines of content in this section.
    """

    def __init__(self, title: str, level: int):
        """Initializes a ContentSection with a title and a heading level.

        Args:
            title (str): The title of the section.
            level (int): The Markdown heading level (e.g., 1, 2, 3).
        """
        self.title = title
        self.level = level
        self.content: List[str] = []

    def add_content(self, content: Union[str, List[str]]):
        """Appends text content to this section.

        Args:
            content (Union[str, List[str]]): A single string line or a list of string lines to add.
        """
        if isinstance(content, list):
            self.content.extend(content)
        else:
            self.content.append(content)

__init__(title, level)

Initializes a ContentSection with a title and a heading level.

Parameters:

Name	Type	Description	Default
title	str	The title of the section.	required
level	int	The Markdown heading level (e.g., 1, 2, 3).	required

Source code in ures/markdown/manipulator.py

def __init__(self, title: str, level: int):
    """Initializes a ContentSection with a title and a heading level.

    Args:
        title (str): The title of the section.
        level (int): The Markdown heading level (e.g., 1, 2, 3).
    """
    self.title = title
    self.level = level
    self.content: List[str] = []

add_content(content)

Appends text content to this section.

Parameters:

Name	Type	Description	Default
content	Union[str, List[str]]	A single string line or a list of string lines to add.	required

Source code in ures/markdown/manipulator.py

def add_content(self, content: Union[str, List[str]]):
    """Appends text content to this section.

    Args:
        content (Union[str, List[str]]): A single string line or a list of string lines to add.
    """
    if isinstance(content, list):
        self.content.extend(content)
    else:
        self.content.append(content)

MarkdownDocument

A low-level class for manipulating Markdown files with front matter.

This class provides methods to add and modify Markdown content and front matter, supporting nested structures in front matter (e.g., dictionaries within YAML front matter).

Source code in ures/markdown/manipulator.py

class MarkdownDocument:
    """
    A low-level class for manipulating Markdown files with front matter.

    This class provides methods to add and modify Markdown content and front matter,
    supporting nested structures in front matter (e.g., dictionaries within YAML front matter).
    """

    MANDATORY_FIELDS: List[AnyStr] = []

    def __init__(self, content: str = "", metadata: Optional[Dict[str, Any]] = None):
        """
        Initializes a new MarkdownDocument instance.

        Args:
            content (str): The Markdown content. Defaults to an empty string.
            metadata (Optional[Dict[str, Any]]): The front matter metadata as a dictionary. Defaults to None.

        Example:
            >>> doc = MarkdownDocument(
            ...     content="# Hello World",
            ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
            ... )
        """
        if metadata is None:
            metadata = {}
        self.post = frontmatter.Post(content, **metadata)

    @staticmethod
    def path_preprocess(input_path: Union[str, Path]) -> Path:
        if isinstance(input_path, str):
            output_path = Path(input_path)
        else:
            output_path = input_path
        return output_path

    @classmethod
    def from_file(cls, file_path: Union[Path, str]) -> "MarkdownDocument":
        """
        Creates a MarkdownDocument instance by loading a Markdown file.

        Args:
            file_path (str): The path to the Markdown file.

        Returns:
            MarkdownDocument: An instance representing the loaded Markdown file.

        Raises:
            FileNotFoundError: If the specified file does not exist.
            frontmatter.InvalidFrontMatterError: If the front matter is malformed.
        """
        file_path = cls.path_preprocess(file_path)
        if not file_path.is_file():
            raise FileNotFoundError(f"The file '{file_path}' does not exist.")

        with open(file_path, "r", encoding="utf-8") as f:
            post = frontmatter.load(f)
        return cls(content=post.content, metadata=deepcopy(post.metadata))

    @property
    def content(self) -> str:
        """
        Retrieves the Markdown content.

        Returns:
            str: The Markdown content.

        Example:
            >>> doc = MarkdownDocument(content="# Hello World")
            >>> doc.content
            "# Hello World"
        """
        return self.post.content

    @content.setter
    def content(self, new_content: str) -> None:
        """
        Sets the Markdown content.

        Args:
            new_content (str): The new Markdown content.

        Example:
            >>> doc = MarkdownDocument()
            >>> doc.content = "# New Title"
        """
        self.post.content = new_content

    @property
    def metadata(self) -> Dict[str, Any]:
        """
        Retrieves the front matter metadata.

        Returns:
            Dict[str, Any]: The metadata dictionary.

        Example:
            >>> doc = MarkdownDocument(metadata={"title": "Greeting", "tags": ["intro", "welcome"]})
            >>> doc.metadata
            {"title": "Greeting", "tags": ["intro", "welcome"]}
        """
        return self.post.metadata

    @metadata.setter
    def metadata(self, new_metadata: Dict[str, Any]) -> None:
        """
        Sets the front matter metadata.

        Args:
            new_metadata (Dict[str, Any]): The new metadata dictionary.

        Example:
            >>> doc = MarkdownDocument()
            >>> doc.metadata = {"title": "New Greeting", "tags": ["updated"]}
        """
        self.post.metadata = new_metadata

    def add_content(self, content: str, append: bool = True) -> None:
        """
        Adds content to the Markdown document.

        Args:
            content (str): The Markdown content to add.
            append (bool): If True, appends to existing content; otherwise, prepends.
                           Defaults to True.

        Example:
            >>> doc = MarkdownDocument()
            >>> doc.add_content("# Introduction")
            >>> doc.add_content("Some introductory text.", append=True)
        """
        if append:
            if self.post.content:
                self.post.content += "\n" + content
            else:
                self.post.content = content
        else:
            if self.post.content:
                self.post.content = content + "\n" + self.post.content
            else:
                self.post.content = content

    def set_frontmatter(
        self, key_path: str, value: Any, overwrite: bool = True
    ) -> None:
        """
        Sets a front matter key to a specified value. Supports nested keys using dot notation,
        including mixed types such as dictionaries within lists.

        Args:
            key_path (str): The front matter key path. Use dot notation for nested keys
                            (e.g., "author.name" or "sections.0.title").
            value (Any): The value to set for the key.
            overwrite (bool): If True, overwrites the existing value; otherwise, appends to lists
                              or creates new entries in lists. Defaults to True.

        Example:
            >>> doc = MarkdownDocument()
            >>> doc.set_frontmatter("author.name", "John Doe")
            >>> doc.set_frontmatter("author.contact.email", "john@example.com")
            >>> doc.set_frontmatter("sections.0.title", "Introduction")
            >>> doc.set_frontmatter("sections.0.content", "Welcome to the introduction.")
            >>> doc.set_frontmatter("sections.1.title", "Conclusion")
            >>> doc.set_frontmatter("sections.1.content", "Wrapping up.")
        """
        keys = key_path.split(".")
        current = self.post.metadata

        for i, key in enumerate(keys):
            is_last = i == len(keys) - 1
            # Determine if the current key is meant to be a list index
            if key.isdigit():
                index = int(key)
                if not isinstance(current, list):
                    if overwrite:
                        # Initialize as list
                        parent = self.post.metadata
                        for k in keys[:i]:
                            if k.isdigit():
                                parent = parent[int(k)]
                            else:
                                parent = parent[k]
                        parent[int(keys[i - 1])] = []
                        current = parent[int(keys[i - 1])]
                    else:
                        raise TypeError(
                            f"Expected list at {'.'.join(keys[:i])}, found {type(current).__name__}"
                        )
                # Extend the list if necessary
                while len(current) <= index:
                    current.append({})
                if is_last:
                    if isinstance(current[index], list) and not overwrite:
                        current[index].append(value)
                    elif isinstance(current[index], dict):
                        if isinstance(value, dict):
                            current[index].update(value)
                        else:
                            current[index]["value"] = value
                    elif not overwrite:
                        current[index] = [current[index], value]
                    else:
                        current[index] = value
                else:
                    if not isinstance(current[index], (dict, list)):
                        # Initialize as dict or list based on next key
                        next_key = keys[i + 1]
                        if next_key.isdigit():
                            current[index] = []
                        else:
                            current[index] = {}
                    current = current[index]
            else:
                if not isinstance(current, dict):
                    if overwrite:
                        # Initialize as dict
                        parent = self.post.metadata
                        for k in keys[:i]:
                            if k.isdigit():
                                parent = parent[int(k)]
                            else:
                                parent = parent[k]
                        parent[keys[i - 1]] = {}
                        current = parent[keys[i - 1]]
                    else:
                        raise TypeError(
                            f"Expected dict at {'.'.join(keys[:i])}, found {type(current).__name__}"
                        )
                if is_last:
                    if key in current:
                        if isinstance(current[key], list) and not overwrite:
                            current[key].append(value)
                        elif isinstance(current[key], dict):
                            if isinstance(value, dict):
                                current[key].update(value)
                            else:
                                current[key]["value"] = value
                        elif not overwrite:
                            current[key] = [current[key], value]
                        else:
                            current[key] = value
                    else:
                        current[key] = value
                else:
                    if key not in current or not isinstance(current[key], (dict, list)):
                        # Initialize as dict or list based on next key
                        next_key = keys[i + 1]
                        if next_key.isdigit():
                            current[key] = []
                        else:
                            current[key] = {}
                    current = current[key]

    def get_frontmatter(self, key_path: str) -> Any:
        """
        Retrieves the value of a front matter key. Supports nested keys using dot notation,
        including list indices.

        Args:
            key_path (str): The front matter key path. Use dot notation for nested keys
                            (e.g., "author.name" or "sections.0.title").

        Returns:
            Any: The value associated with the key, or None if the key does not exist.

        Example:
            >>> doc = MarkdownDocument(
            ...     metadata={
            ...         "author": {"name": "John Doe", "contact": {"email": "john@example.com"}},
            ...         "sections": [
            ...             {"title": "Introduction", "content": "Welcome."},
            ...             {"title": "Conclusion", "content": "Goodbye."}
            ...         ]
            ...     }
            ... )
            >>> doc.get_frontmatter("author.name")
            "John Doe"
            >>> doc.get_frontmatter("sections.0.title")
            "Introduction"
            >>> doc.get_frontmatter("sections.1.content")
            "Goodbye."
        """
        keys = key_path.split(".")
        metadata = self.post.metadata

        for key in keys:
            if isinstance(metadata, dict):
                metadata = metadata.get(key, None)
            elif isinstance(metadata, list):
                if key.isdigit():
                    index = int(key)
                    if 0 <= index < len(metadata):
                        metadata = metadata[index]
                    else:
                        return None
                else:
                    return None
            else:
                return None

            if metadata is None:
                return None

        return metadata

    def remove_frontmatter(self, key_path: str) -> None:
        """
        Removes a front matter key. Supports nested keys using dot notation,
        including list indices.

        Args:
            key_path (str): The front matter key path to remove. Use dot notation for nested keys
                            (e.g., "author.contact.email" or "sections.0.title").

        Example:
            >>> doc = MarkdownDocument(
            ...     metadata={
            ...         "author": {"name": "John Doe", "contact": {"email": "john@example.com"}},
            ...         "sections": [
            ...             {"title": "Introduction", "content": "Welcome."},
            ...             {"title": "Conclusion", "content": "Goodbye."}
            ...         ]
            ...     }
            ... )
            >>> doc.remove_frontmatter("author.contact.email")
            >>> doc.get_frontmatter("author.contact.email") is None
            True
            >>> doc.remove_frontmatter("sections.1.title")
            >>> doc.get_frontmatter("sections.1.title") is None
            True
        """
        keys = key_path.split(".")
        metadata = self.post.metadata

        for i, key in enumerate(keys):
            is_last = i == len(keys) - 1
            if isinstance(metadata, dict):
                if key not in metadata:
                    return  # Key path does not exist; nothing to remove
                if is_last:
                    del metadata[key]
                    return
                metadata = metadata[key]
            elif isinstance(metadata, list):
                if key.isdigit():
                    index = int(key)
                    if 0 <= index < len(metadata):
                        if is_last:
                            del metadata[index]
                            return
                        metadata = metadata[index]
                    else:
                        return  # Index out of range; nothing to remove
                else:
                    return  # Invalid key for list; nothing to remove
            else:
                return  # Neither dict nor list; nothing to remove

    def to_markdown(self) -> str:
        """
        Serializes the MarkdownDocument to a Markdown-formatted string, including front matter.

        Returns:
            str: The complete Markdown content with front matter.

        ERROR:
            ValueError: If the front matter is missing mandatory fields.

        Example:
            >>> doc = MarkdownDocument(
            ...     content="# Hello World",
            ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
            ... )
            >>> print(doc.to_markdown())
            ---
            title: Greeting
            tags:
              - intro
              - welcome
            ---

            # Hello World
        """
        self.validation_frontmatter()
        return frontmatter.dumps(self.post)

    def save(self, file_path: Union[Path, str]) -> None:
        """
        Saves the MarkdownDocument to a specified file.

        Args:
            file_path (str): The path where the Markdown file will be saved.

        Example:
            >>> doc = MarkdownDocument(
            ...     content="# Hello World",
            ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
            ... )
            >>> doc.save_to_file("greeting.md")
        """
        file_path = self.path_preprocess(file_path)
        markdown_str = self.to_markdown()
        with open(file_path, "w", encoding="utf-8") as f:
            f.write(markdown_str)

    def load_from_file(self, file_path: Union[Path, str]) -> None:
        """
        Loads Markdown content and front matter from a specified file into the current instance.

        Args:
            file_path (str): The path to the Markdown file to load.

        Raises:
            FileNotFoundError: If the specified file does not exist.
            frontmatter.InvalidFrontMatterError: If the front matter is malformed.

        Example:
            >>> doc = MarkdownDocument()
            >>> doc.load_from_file("existing.md")
        """
        file_path = self.path_preprocess(file_path)
        if not os.path.isfile(file_path):
            raise FileNotFoundError(f"The file '{file_path}' does not exist.")

        with open(file_path, "r", encoding="utf-8") as f:
            post = frontmatter.load(f)

        self.post.content = post.content
        self.post.metadata = deepcopy(post.metadata)

    def parse_content(self) -> Content:
        """Parses the raw note content into a structured Content object.

        Iterates through the raw text line by line, identifying Markdown headers
        (e.g., '# Title') to delimit sections. Text found before the first header
        is assigned to a 'default' section.

        Returns:
            Content: An object containing the parsed sections, their hierarchy levels,
            and associated text content.
        """
        lines = self.content.split("\n")
        current_section = "default"
        current_head_level = 1
        content_buffer: List[str] = []
        new_content = Content()

        for line in lines:
            header_match = re.match(r"^(#+)\s+(.+)$", line)

            if header_match:
                if len(content_buffer) > 0:
                    new_content.add_content(
                        content="\n".join(content_buffer).strip(),
                        section_title=current_section,
                        section_level=current_head_level,
                    )
                    content_buffer = []

                current_head_level = len(header_match.group(1))
                current_section = header_match.group(2).strip()

                new_content.new_section(title=current_section, level=current_head_level)
            else:
                if line.strip() or len(content_buffer) > 0:
                    content_buffer.append(line)

        if len(content_buffer) > 0:
            new_content.add_content(
                content="\n".join(content_buffer).strip(),
                section_title=current_section,
                section_level=current_head_level,
            )

        return new_content

    def clear_content(self) -> None:
        """
        Clears all Markdown content, leaving only the front matter.

        Example:
            >>> doc = MarkdownDocument(content="# Hello World")
            >>> doc.clear_content()
            >>> print(doc.content)
            ""
        """
        self.post.content = ""

    def clear_frontmatter(self) -> None:
        """
        Clears all front matter metadata, leaving only the Markdown content.

        Example:
            >>> doc = MarkdownDocument(
            ...     content="# Hello World",
            ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
            ... )
            >>> doc.clear_frontmatter()
            >>> print(doc.metadata)
            {}
        """
        self.post.metadata = {}

    def validation_frontmatter(self):
        """
        Validate the frontmatter metadata against the mandatory fields.
        """
        missing_fields = []
        for field in self.MANDATORY_FIELDS:
            if self.get_frontmatter(field) is None:
                missing_fields.append(field)

        if missing_fields:
            missing = ", ".join(missing_fields)
            raise ValueError(f"Missing mandatory front matter fields: {missing}")

content property writable

Retrieves the Markdown content.

Returns:

Name	Type	Description
str	str	The Markdown content.

Example

doc = MarkdownDocument(content="# Hello World") doc.content "# Hello World"

metadata property writable

Retrieves the front matter metadata.

Returns:

Type	Description
Dict[str, Any]	Dict[str, Any]: The metadata dictionary.

Example

doc = MarkdownDocument(metadata={"title": "Greeting", "tags": ["intro", "welcome"]}) doc.metadata {"title": "Greeting", "tags": ["intro", "welcome"]}

__init__(content='', metadata=None)

Initializes a new MarkdownDocument instance.

Parameters:

Name	Type	Description	Default
content	str	The Markdown content. Defaults to an empty string.	''
metadata	Optional[Dict[str, Any]]	The front matter metadata as a dictionary. Defaults to None.	None

Example

doc = MarkdownDocument( ... content="# Hello World", ... metadata={"title": "Greeting", "tags": ["intro", "welcome"]} ... )

Source code in ures/markdown/manipulator.py

def __init__(self, content: str = "", metadata: Optional[Dict[str, Any]] = None):
    """
    Initializes a new MarkdownDocument instance.

    Args:
        content (str): The Markdown content. Defaults to an empty string.
        metadata (Optional[Dict[str, Any]]): The front matter metadata as a dictionary. Defaults to None.

    Example:
        >>> doc = MarkdownDocument(
        ...     content="# Hello World",
        ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
        ... )
    """
    if metadata is None:
        metadata = {}
    self.post = frontmatter.Post(content, **metadata)

add_content(content, append=True)

Adds content to the Markdown document.

Parameters:

Name	Type	Description	Default
content	str	The Markdown content to add.	required
append	bool	If True, appends to existing content; otherwise, prepends. Defaults to True.	True

Example

doc = MarkdownDocument() doc.add_content("# Introduction") doc.add_content("Some introductory text.", append=True)

Source code in ures/markdown/manipulator.py

def add_content(self, content: str, append: bool = True) -> None:
    """
    Adds content to the Markdown document.

    Args:
        content (str): The Markdown content to add.
        append (bool): If True, appends to existing content; otherwise, prepends.
                       Defaults to True.

    Example:
        >>> doc = MarkdownDocument()
        >>> doc.add_content("# Introduction")
        >>> doc.add_content("Some introductory text.", append=True)
    """
    if append:
        if self.post.content:
            self.post.content += "\n" + content
        else:
            self.post.content = content
    else:
        if self.post.content:
            self.post.content = content + "\n" + self.post.content
        else:
            self.post.content = content

clear_content()

Clears all Markdown content, leaving only the front matter.

Example

doc = MarkdownDocument(content="# Hello World") doc.clear_content() print(doc.content) ""

Source code in ures/markdown/manipulator.py

def clear_content(self) -> None:
    """
    Clears all Markdown content, leaving only the front matter.

    Example:
        >>> doc = MarkdownDocument(content="# Hello World")
        >>> doc.clear_content()
        >>> print(doc.content)
        ""
    """
    self.post.content = ""

clear_frontmatter()

Clears all front matter metadata, leaving only the Markdown content.

Example

doc = MarkdownDocument( ... content="# Hello World", ... metadata={"title": "Greeting", "tags": ["intro", "welcome"]} ... ) doc.clear_frontmatter() print(doc.metadata) {}

Source code in ures/markdown/manipulator.py

def clear_frontmatter(self) -> None:
    """
    Clears all front matter metadata, leaving only the Markdown content.

    Example:
        >>> doc = MarkdownDocument(
        ...     content="# Hello World",
        ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
        ... )
        >>> doc.clear_frontmatter()
        >>> print(doc.metadata)
        {}
    """
    self.post.metadata = {}

from_file(file_path) classmethod

Creates a MarkdownDocument instance by loading a Markdown file.

Parameters:

Name	Type	Description	Default
file_path	str	The path to the Markdown file.	required

Returns:

Name	Type	Description
MarkdownDocument	MarkdownDocument	An instance representing the loaded Markdown file.

Raises:

Type	Description
FileNotFoundError	If the specified file does not exist.
InvalidFrontMatterError	If the front matter is malformed.

Source code in ures/markdown/manipulator.py

@classmethod
def from_file(cls, file_path: Union[Path, str]) -> "MarkdownDocument":
    """
    Creates a MarkdownDocument instance by loading a Markdown file.

    Args:
        file_path (str): The path to the Markdown file.

    Returns:
        MarkdownDocument: An instance representing the loaded Markdown file.

    Raises:
        FileNotFoundError: If the specified file does not exist.
        frontmatter.InvalidFrontMatterError: If the front matter is malformed.
    """
    file_path = cls.path_preprocess(file_path)
    if not file_path.is_file():
        raise FileNotFoundError(f"The file '{file_path}' does not exist.")

    with open(file_path, "r", encoding="utf-8") as f:
        post = frontmatter.load(f)
    return cls(content=post.content, metadata=deepcopy(post.metadata))

get_frontmatter(key_path)

Retrieves the value of a front matter key. Supports nested keys using dot notation, including list indices.

Parameters:

Name	Type	Description	Default
key_path	str	The front matter key path. Use dot notation for nested keys (e.g., "author.name" or "sections.0.title").	required

Returns:

Name	Type	Description
Any	Any	The value associated with the key, or None if the key does not exist.

Example

doc = MarkdownDocument( ... metadata={ ... "author": {"name": "John Doe", "contact": {"email": "john@example.com"}}, ... "sections": [ ... {"title": "Introduction", "content": "Welcome."}, ... {"title": "Conclusion", "content": "Goodbye."} ... ] ... } ... ) doc.get_frontmatter("author.name") "John Doe" doc.get_frontmatter("sections.0.title") "Introduction" doc.get_frontmatter("sections.1.content") "Goodbye."

Source code in ures/markdown/manipulator.py

def get_frontmatter(self, key_path: str) -> Any:
    """
    Retrieves the value of a front matter key. Supports nested keys using dot notation,
    including list indices.

    Args:
        key_path (str): The front matter key path. Use dot notation for nested keys
                        (e.g., "author.name" or "sections.0.title").

    Returns:
        Any: The value associated with the key, or None if the key does not exist.

    Example:
        >>> doc = MarkdownDocument(
        ...     metadata={
        ...         "author": {"name": "John Doe", "contact": {"email": "john@example.com"}},
        ...         "sections": [
        ...             {"title": "Introduction", "content": "Welcome."},
        ...             {"title": "Conclusion", "content": "Goodbye."}
        ...         ]
        ...     }
        ... )
        >>> doc.get_frontmatter("author.name")
        "John Doe"
        >>> doc.get_frontmatter("sections.0.title")
        "Introduction"
        >>> doc.get_frontmatter("sections.1.content")
        "Goodbye."
    """
    keys = key_path.split(".")
    metadata = self.post.metadata

    for key in keys:
        if isinstance(metadata, dict):
            metadata = metadata.get(key, None)
        elif isinstance(metadata, list):
            if key.isdigit():
                index = int(key)
                if 0 <= index < len(metadata):
                    metadata = metadata[index]
                else:
                    return None
            else:
                return None
        else:
            return None

        if metadata is None:
            return None

    return metadata

load_from_file(file_path)

Loads Markdown content and front matter from a specified file into the current instance.

Parameters:

Name	Type	Description	Default
file_path	str	The path to the Markdown file to load.	required

Raises:

Type	Description
FileNotFoundError	If the specified file does not exist.
InvalidFrontMatterError	If the front matter is malformed.

Example

doc = MarkdownDocument() doc.load_from_file("existing.md")

Source code in ures/markdown/manipulator.py

def load_from_file(self, file_path: Union[Path, str]) -> None:
    """
    Loads Markdown content and front matter from a specified file into the current instance.

    Args:
        file_path (str): The path to the Markdown file to load.

    Raises:
        FileNotFoundError: If the specified file does not exist.
        frontmatter.InvalidFrontMatterError: If the front matter is malformed.

    Example:
        >>> doc = MarkdownDocument()
        >>> doc.load_from_file("existing.md")
    """
    file_path = self.path_preprocess(file_path)
    if not os.path.isfile(file_path):
        raise FileNotFoundError(f"The file '{file_path}' does not exist.")

    with open(file_path, "r", encoding="utf-8") as f:
        post = frontmatter.load(f)

    self.post.content = post.content
    self.post.metadata = deepcopy(post.metadata)

parse_content()

Parses the raw note content into a structured Content object.

Iterates through the raw text line by line, identifying Markdown headers (e.g., '# Title') to delimit sections. Text found before the first header is assigned to a 'default' section.

Returns:

Name	Type	Description
Content	Content	An object containing the parsed sections, their hierarchy levels,
	Content	and associated text content.

Source code in ures/markdown/manipulator.py

def parse_content(self) -> Content:
    """Parses the raw note content into a structured Content object.

    Iterates through the raw text line by line, identifying Markdown headers
    (e.g., '# Title') to delimit sections. Text found before the first header
    is assigned to a 'default' section.

    Returns:
        Content: An object containing the parsed sections, their hierarchy levels,
        and associated text content.
    """
    lines = self.content.split("\n")
    current_section = "default"
    current_head_level = 1
    content_buffer: List[str] = []
    new_content = Content()

    for line in lines:
        header_match = re.match(r"^(#+)\s+(.+)$", line)

        if header_match:
            if len(content_buffer) > 0:
                new_content.add_content(
                    content="\n".join(content_buffer).strip(),
                    section_title=current_section,
                    section_level=current_head_level,
                )
                content_buffer = []

            current_head_level = len(header_match.group(1))
            current_section = header_match.group(2).strip()

            new_content.new_section(title=current_section, level=current_head_level)
        else:
            if line.strip() or len(content_buffer) > 0:
                content_buffer.append(line)

    if len(content_buffer) > 0:
        new_content.add_content(
            content="\n".join(content_buffer).strip(),
            section_title=current_section,
            section_level=current_head_level,
        )

    return new_content

remove_frontmatter(key_path)

Removes a front matter key. Supports nested keys using dot notation, including list indices.

Parameters:

Name	Type	Description	Default
key_path	str	The front matter key path to remove. Use dot notation for nested keys (e.g., "author.contact.email" or "sections.0.title").	required

Example

doc = MarkdownDocument( ... metadata={ ... "author": {"name": "John Doe", "contact": {"email": "john@example.com"}}, ... "sections": [ ... {"title": "Introduction", "content": "Welcome."}, ... {"title": "Conclusion", "content": "Goodbye."} ... ] ... } ... ) doc.remove_frontmatter("author.contact.email") doc.get_frontmatter("author.contact.email") is None True doc.remove_frontmatter("sections.1.title") doc.get_frontmatter("sections.1.title") is None True

Source code in ures/markdown/manipulator.py

def remove_frontmatter(self, key_path: str) -> None:
    """
    Removes a front matter key. Supports nested keys using dot notation,
    including list indices.

    Args:
        key_path (str): The front matter key path to remove. Use dot notation for nested keys
                        (e.g., "author.contact.email" or "sections.0.title").

    Example:
        >>> doc = MarkdownDocument(
        ...     metadata={
        ...         "author": {"name": "John Doe", "contact": {"email": "john@example.com"}},
        ...         "sections": [
        ...             {"title": "Introduction", "content": "Welcome."},
        ...             {"title": "Conclusion", "content": "Goodbye."}
        ...         ]
        ...     }
        ... )
        >>> doc.remove_frontmatter("author.contact.email")
        >>> doc.get_frontmatter("author.contact.email") is None
        True
        >>> doc.remove_frontmatter("sections.1.title")
        >>> doc.get_frontmatter("sections.1.title") is None
        True
    """
    keys = key_path.split(".")
    metadata = self.post.metadata

    for i, key in enumerate(keys):
        is_last = i == len(keys) - 1
        if isinstance(metadata, dict):
            if key not in metadata:
                return  # Key path does not exist; nothing to remove
            if is_last:
                del metadata[key]
                return
            metadata = metadata[key]
        elif isinstance(metadata, list):
            if key.isdigit():
                index = int(key)
                if 0 <= index < len(metadata):
                    if is_last:
                        del metadata[index]
                        return
                    metadata = metadata[index]
                else:
                    return  # Index out of range; nothing to remove
            else:
                return  # Invalid key for list; nothing to remove
        else:
            return  # Neither dict nor list; nothing to remove

save(file_path)

Saves the MarkdownDocument to a specified file.

Parameters:

Name	Type	Description	Default
file_path	str	The path where the Markdown file will be saved.	required

Example

doc = MarkdownDocument( ... content="# Hello World", ... metadata={"title": "Greeting", "tags": ["intro", "welcome"]} ... ) doc.save_to_file("greeting.md")

Source code in ures/markdown/manipulator.py

def save(self, file_path: Union[Path, str]) -> None:
    """
    Saves the MarkdownDocument to a specified file.

    Args:
        file_path (str): The path where the Markdown file will be saved.

    Example:
        >>> doc = MarkdownDocument(
        ...     content="# Hello World",
        ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
        ... )
        >>> doc.save_to_file("greeting.md")
    """
    file_path = self.path_preprocess(file_path)
    markdown_str = self.to_markdown()
    with open(file_path, "w", encoding="utf-8") as f:
        f.write(markdown_str)

set_frontmatter(key_path, value, overwrite=True)

Sets a front matter key to a specified value. Supports nested keys using dot notation, including mixed types such as dictionaries within lists.

Parameters:

Name	Type	Description	Default
key_path	str	The front matter key path. Use dot notation for nested keys (e.g., "author.name" or "sections.0.title").	required
value	Any	The value to set for the key.	required
overwrite	bool	If True, overwrites the existing value; otherwise, appends to lists or creates new entries in lists. Defaults to True.	True

Example

doc = MarkdownDocument() doc.set_frontmatter("author.name", "John Doe") doc.set_frontmatter("author.contact.email", "john@example.com") doc.set_frontmatter("sections.0.title", "Introduction") doc.set_frontmatter("sections.0.content", "Welcome to the introduction.") doc.set_frontmatter("sections.1.title", "Conclusion") doc.set_frontmatter("sections.1.content", "Wrapping up.")

Source code in ures/markdown/manipulator.py

def set_frontmatter(
    self, key_path: str, value: Any, overwrite: bool = True
) -> None:
    """
    Sets a front matter key to a specified value. Supports nested keys using dot notation,
    including mixed types such as dictionaries within lists.

    Args:
        key_path (str): The front matter key path. Use dot notation for nested keys
                        (e.g., "author.name" or "sections.0.title").
        value (Any): The value to set for the key.
        overwrite (bool): If True, overwrites the existing value; otherwise, appends to lists
                          or creates new entries in lists. Defaults to True.

    Example:
        >>> doc = MarkdownDocument()
        >>> doc.set_frontmatter("author.name", "John Doe")
        >>> doc.set_frontmatter("author.contact.email", "john@example.com")
        >>> doc.set_frontmatter("sections.0.title", "Introduction")
        >>> doc.set_frontmatter("sections.0.content", "Welcome to the introduction.")
        >>> doc.set_frontmatter("sections.1.title", "Conclusion")
        >>> doc.set_frontmatter("sections.1.content", "Wrapping up.")
    """
    keys = key_path.split(".")
    current = self.post.metadata

    for i, key in enumerate(keys):
        is_last = i == len(keys) - 1
        # Determine if the current key is meant to be a list index
        if key.isdigit():
            index = int(key)
            if not isinstance(current, list):
                if overwrite:
                    # Initialize as list
                    parent = self.post.metadata
                    for k in keys[:i]:
                        if k.isdigit():
                            parent = parent[int(k)]
                        else:
                            parent = parent[k]
                    parent[int(keys[i - 1])] = []
                    current = parent[int(keys[i - 1])]
                else:
                    raise TypeError(
                        f"Expected list at {'.'.join(keys[:i])}, found {type(current).__name__}"
                    )
            # Extend the list if necessary
            while len(current) <= index:
                current.append({})
            if is_last:
                if isinstance(current[index], list) and not overwrite:
                    current[index].append(value)
                elif isinstance(current[index], dict):
                    if isinstance(value, dict):
                        current[index].update(value)
                    else:
                        current[index]["value"] = value
                elif not overwrite:
                    current[index] = [current[index], value]
                else:
                    current[index] = value
            else:
                if not isinstance(current[index], (dict, list)):
                    # Initialize as dict or list based on next key
                    next_key = keys[i + 1]
                    if next_key.isdigit():
                        current[index] = []
                    else:
                        current[index] = {}
                current = current[index]
        else:
            if not isinstance(current, dict):
                if overwrite:
                    # Initialize as dict
                    parent = self.post.metadata
                    for k in keys[:i]:
                        if k.isdigit():
                            parent = parent[int(k)]
                        else:
                            parent = parent[k]
                    parent[keys[i - 1]] = {}
                    current = parent[keys[i - 1]]
                else:
                    raise TypeError(
                        f"Expected dict at {'.'.join(keys[:i])}, found {type(current).__name__}"
                    )
            if is_last:
                if key in current:
                    if isinstance(current[key], list) and not overwrite:
                        current[key].append(value)
                    elif isinstance(current[key], dict):
                        if isinstance(value, dict):
                            current[key].update(value)
                        else:
                            current[key]["value"] = value
                    elif not overwrite:
                        current[key] = [current[key], value]
                    else:
                        current[key] = value
                else:
                    current[key] = value
            else:
                if key not in current or not isinstance(current[key], (dict, list)):
                    # Initialize as dict or list based on next key
                    next_key = keys[i + 1]
                    if next_key.isdigit():
                        current[key] = []
                    else:
                        current[key] = {}
                current = current[key]

to_markdown()

Serializes the MarkdownDocument to a Markdown-formatted string, including front matter.

Returns:

Name	Type	Description
str	str	The complete Markdown content with front matter.

ERROR

ValueError: If the front matter is missing mandatory fields.

Example

doc = MarkdownDocument( ... content="# Hello World", ... metadata={"title": "Greeting", "tags": ["intro", "welcome"]} ... ) print(doc.to_markdown())

---

title: Greeting tags: - intro - welcome

---

Hello World

Source code in ures/markdown/manipulator.py

def to_markdown(self) -> str:
    """
    Serializes the MarkdownDocument to a Markdown-formatted string, including front matter.

    Returns:
        str: The complete Markdown content with front matter.

    ERROR:
        ValueError: If the front matter is missing mandatory fields.

    Example:
        >>> doc = MarkdownDocument(
        ...     content="# Hello World",
        ...     metadata={"title": "Greeting", "tags": ["intro", "welcome"]}
        ... )
        >>> print(doc.to_markdown())
        ---
        title: Greeting
        tags:
          - intro
          - welcome
        ---

        # Hello World
    """
    self.validation_frontmatter()
    return frontmatter.dumps(self.post)

validation_frontmatter()

Validate the frontmatter metadata against the mandatory fields.

Source code in ures/markdown/manipulator.py

def validation_frontmatter(self):
    """
    Validate the frontmatter metadata against the mandatory fields.
    """
    missing_fields = []
    for field in self.MANDATORY_FIELDS:
        if self.get_frontmatter(field) is None:
            missing_fields.append(field)

    if missing_fields:
        missing = ", ".join(missing_fields)
        raise ValueError(f"Missing mandatory front matter fields: {missing}")

Zettelkasten

Bases: MarkdownDocument

Class for handling Zettelkasten markdown files. In my case, a list of mandatory fields is defined in a class variable.

In Zettelkasten note-taking system, only three types of notes are supported: 'fleeting', 'literature', 'permanent', but I added 'atom' type for my own use.

Source code in ures/markdown/zettelkasten.py

class Zettelkasten(MarkdownDocument):
    """
    Class for handling Zettelkasten markdown files. In my case, a list of mandatory fields is defined in a class
    variable.

    In Zettelkasten note-taking system, only three types of notes are supported: 'fleeting', 'literature', 'permanent',
    but I added 'atom' type for my own use.
    """

    MANDATORY_FIELDS = ["title", "type", "url", "create", "id", "tags", "aliases"]
    ALLOWED_TYPES = ["fleeting", "literature", "permanent", "atom"]

    def __init__(
        self,
        title: str,
        n_type: str,
        url: Optional[str] = None,
        tags: Optional[list] = None,
        aliases: Optional[list] = None,
        **kwargs,
    ):
        """
        Initialize a Zettelkasten object
        Args:
            title (str): The title of the note.
            n_type (str): The type of the note, only support 'fleeting', 'literature', 'permanent' and 'atom'.
            url (str): The url of the note.
            tags (list): The tags of the note.
            aliases
        """
        if not isinstance(title, str) or not title.strip():
            raise ValueError("Title must be a non-empty string.")
        if n_type not in self.ALLOWED_TYPES:
            raise ValueError(
                f"Invalid type '{n_type}'. Allowed types are: {', '.join(self.ALLOWED_TYPES)}."
            )
        if url is not None and not isinstance(url, str):
            raise ValueError("URL must be a string.")
        if tags is not None and not isinstance(tags, list):
            raise ValueError("Tags must be a list.")
        if aliases is not None and not isinstance(aliases, list):
            raise ValueError("Aliases must be a list.")

        _metadata = {
            "title": title,
            "type": n_type,
            "url": url or "",
            "tags": tags or [],
            "aliases": aliases or [],
            "id": zettelkasten_id(),
            "create": time_now(),
        }
        if len(kwargs) > 0:
            _metadata.update(kwargs)
        super().__init__(metadata=_metadata)

    @classmethod
    def from_file(cls, file_path: str) -> Union["MarkdownDocument", "Zettelkasten"]:
        """
        Creates a MarkdownDocument instance by loading a Markdown file.

        Args:
            file_path (str): The path to the Markdown file.

        Returns:
            MarkdownDocument: An instance representing the loaded Markdown file.

        Raises:
            FileNotFoundError: If the specified file does not exist.
            frontmatter.InvalidFrontMatterError: If the front matter is malformed.
        """
        if not os.path.isfile(file_path):
            raise FileNotFoundError(f"The file '{file_path}' does not exist.")

        with open(file_path, "r", encoding="utf-8") as f:
            post = frontmatter.load(f)

        _params = dict(post.metadata)
        n_type = _params.get("type", None)
        if n_type is not None:
            del _params["type"]
        _params["n_type"] = n_type

        keywords = ["title", "n_type", "url", "tags", "aliases"]
        for keyword in keywords:
            if keyword not in _params.keys():
                _params[keyword] = None

        zk = cls(
            **_params,
        )
        # zk.metadata["id"] = post.metadata.get("id", zk.metadata["id"])
        # zk.metadata["create"] = post.metadata.get("create", zk.metadata["create"])
        zk.add_content(post.content)
        return zk

    @property
    def title(self) -> str:
        return self.get_frontmatter("title")

    @title.setter
    def title(self, value):
        if not isinstance(value, str) or not value.strip():
            raise ValueError("Title must be a non-empty string.")
        self.set_frontmatter("title", value)

    @property
    def type(self) -> str:
        return self.get_frontmatter("type")

    @type.setter
    def type(self, value):
        if value not in self.ALLOWED_TYPES:
            raise ValueError(
                f"Invalid type '{value}'. Allowed types are: {', '.join(self.ALLOWED_TYPES)}."
            )
        self.set_frontmatter("type", value)

    @property
    def url(self) -> str:
        return self.get_frontmatter("url")

    @url.setter
    def url(self, value):
        if not isinstance(value, str):
            raise ValueError("URL must be a string.")
        self.set_frontmatter("url", value)

    @property
    def tags(self) -> list:
        return self.get_frontmatter("tags")

    @tags.setter
    def tags(self, value):
        if not isinstance(value, list):
            raise ValueError("Tags must be a list.")
        self.set_frontmatter("tags", value)

    @property
    def aliases(self) -> list:
        return self.get_frontmatter("aliases")

    @aliases.setter
    def aliases(self, value):
        if not isinstance(value, list):
            raise ValueError("Aliases must be a list.")
        self.set_frontmatter("aliases", value)

    def add_tag(self, tag: str):
        self.tags.append(tag)

    def remove_tag(self, tag: str):
        self.tags.remove(tag)

    def add_alias(self, alias: str):
        self.aliases.append(alias)

    def remove_alias(self, alias: str):
        self.aliases.remove(alias)

    def to_llm_friendly_content(
        self, prop_ignores: Optional[list] = None, context: Optional[Content] = None
    ) -> Content:
        """Generates an LLM-friendly representation of the note, filtering metadata and merging context.

        This method creates a structured content object designed for LLM consumption. It first
        adds a 'Metadata' section (filtering out specified keys), then appends the note's
        main body, and finally merges any external context provided.

        Args:
            prop_ignores (Optional[List[str]]): A list of metadata keys to exclude from the output.
                Defaults to None. The keys "aliases", "url", "id", and "title" are always ignored
                by default.
            context (Optional[Content]): Additional contextual content to append to the note.
                Defaults to None.

        Returns:
            Content: A new Content object organized into 'Metadata', 'Main Content', and
            optionally 'Context' sections.
        """
        properties = self.metadata
        content = Content()
        # Create a new section for metadata
        properties_ignore_list = ["aliases", "url", "id", "title"]
        if prop_ignores:
            properties_ignore_list.extend(prop_ignores)
        for key, value in properties.items():
            if key not in properties_ignore_list:
                if isinstance(value, list):
                    value = ", ".join(value)
                else:
                    value = str(value)

                content.add_content(
                    content=f"**{key}**: {value}",
                    section_title="Metadata",
                    section_level=1,
                )

        # Merge all existing sections into the main body
        body_title = "Main Content"
        body_level = 1
        for key, value in self.parse_content().sections.items():
            content.add_content(
                content=f"**{key}**:",
                section_title=body_title,
                section_level=body_level,
            )
            content.add_content(
                content=value.content,
                section_title=body_title,
                section_level=body_level,
            )

        # If context is provided, merge it
        if context:
            context_title = "Context"
            context_level = 2
            for key, value in context.sections.items():
                content.add_content(
                    content=f"**{key}**:",
                    section_title=context_title,
                    section_level=context_level,
                )
                content.add_content(
                    content=value.content,
                    section_title=context_title,
                    section_level=context_level,
                )

        return content

__init__(title, n_type, url=None, tags=None, aliases=None, **kwargs)

Initialize a Zettelkasten object Args: title (str): The title of the note. n_type (str): The type of the note, only support 'fleeting', 'literature', 'permanent' and 'atom'. url (str): The url of the note. tags (list): The tags of the note. aliases

Source code in ures/markdown/zettelkasten.py

def __init__(
    self,
    title: str,
    n_type: str,
    url: Optional[str] = None,
    tags: Optional[list] = None,
    aliases: Optional[list] = None,
    **kwargs,
):
    """
    Initialize a Zettelkasten object
    Args:
        title (str): The title of the note.
        n_type (str): The type of the note, only support 'fleeting', 'literature', 'permanent' and 'atom'.
        url (str): The url of the note.
        tags (list): The tags of the note.
        aliases
    """
    if not isinstance(title, str) or not title.strip():
        raise ValueError("Title must be a non-empty string.")
    if n_type not in self.ALLOWED_TYPES:
        raise ValueError(
            f"Invalid type '{n_type}'. Allowed types are: {', '.join(self.ALLOWED_TYPES)}."
        )
    if url is not None and not isinstance(url, str):
        raise ValueError("URL must be a string.")
    if tags is not None and not isinstance(tags, list):
        raise ValueError("Tags must be a list.")
    if aliases is not None and not isinstance(aliases, list):
        raise ValueError("Aliases must be a list.")

    _metadata = {
        "title": title,
        "type": n_type,
        "url": url or "",
        "tags": tags or [],
        "aliases": aliases or [],
        "id": zettelkasten_id(),
        "create": time_now(),
    }
    if len(kwargs) > 0:
        _metadata.update(kwargs)
    super().__init__(metadata=_metadata)

from_file(file_path) classmethod

Creates a MarkdownDocument instance by loading a Markdown file.

Parameters:

Name	Type	Description	Default
file_path	str	The path to the Markdown file.	required

Returns:

Name	Type	Description
MarkdownDocument	Union[MarkdownDocument, Zettelkasten]	An instance representing the loaded Markdown file.

Raises:

Type	Description
FileNotFoundError	If the specified file does not exist.
InvalidFrontMatterError	If the front matter is malformed.

Source code in ures/markdown/zettelkasten.py

@classmethod
def from_file(cls, file_path: str) -> Union["MarkdownDocument", "Zettelkasten"]:
    """
    Creates a MarkdownDocument instance by loading a Markdown file.

    Args:
        file_path (str): The path to the Markdown file.

    Returns:
        MarkdownDocument: An instance representing the loaded Markdown file.

    Raises:
        FileNotFoundError: If the specified file does not exist.
        frontmatter.InvalidFrontMatterError: If the front matter is malformed.
    """
    if not os.path.isfile(file_path):
        raise FileNotFoundError(f"The file '{file_path}' does not exist.")

    with open(file_path, "r", encoding="utf-8") as f:
        post = frontmatter.load(f)

    _params = dict(post.metadata)
    n_type = _params.get("type", None)
    if n_type is not None:
        del _params["type"]
    _params["n_type"] = n_type

    keywords = ["title", "n_type", "url", "tags", "aliases"]
    for keyword in keywords:
        if keyword not in _params.keys():
            _params[keyword] = None

    zk = cls(
        **_params,
    )
    # zk.metadata["id"] = post.metadata.get("id", zk.metadata["id"])
    # zk.metadata["create"] = post.metadata.get("create", zk.metadata["create"])
    zk.add_content(post.content)
    return zk

to_llm_friendly_content(prop_ignores=None, context=None)

Generates an LLM-friendly representation of the note, filtering metadata and merging context.

This method creates a structured content object designed for LLM consumption. It first adds a 'Metadata' section (filtering out specified keys), then appends the note's main body, and finally merges any external context provided.

Parameters:

Name	Type	Description	Default
prop_ignores	Optional[List[str]]	A list of metadata keys to exclude from the output. Defaults to None. The keys "aliases", "url", "id", and "title" are always ignored by default.	None
context	Optional[Content]	Additional contextual content to append to the note. Defaults to None.	None

Returns:

Name	Type	Description
Content	Content	A new Content object organized into 'Metadata', 'Main Content', and
	Content	optionally 'Context' sections.

Source code in ures/markdown/zettelkasten.py

def to_llm_friendly_content(
    self, prop_ignores: Optional[list] = None, context: Optional[Content] = None
) -> Content:
    """Generates an LLM-friendly representation of the note, filtering metadata and merging context.

    This method creates a structured content object designed for LLM consumption. It first
    adds a 'Metadata' section (filtering out specified keys), then appends the note's
    main body, and finally merges any external context provided.

    Args:
        prop_ignores (Optional[List[str]]): A list of metadata keys to exclude from the output.
            Defaults to None. The keys "aliases", "url", "id", and "title" are always ignored
            by default.
        context (Optional[Content]): Additional contextual content to append to the note.
            Defaults to None.

    Returns:
        Content: A new Content object organized into 'Metadata', 'Main Content', and
        optionally 'Context' sections.
    """
    properties = self.metadata
    content = Content()
    # Create a new section for metadata
    properties_ignore_list = ["aliases", "url", "id", "title"]
    if prop_ignores:
        properties_ignore_list.extend(prop_ignores)
    for key, value in properties.items():
        if key not in properties_ignore_list:
            if isinstance(value, list):
                value = ", ".join(value)
            else:
                value = str(value)

            content.add_content(
                content=f"**{key}**: {value}",
                section_title="Metadata",
                section_level=1,
            )

    # Merge all existing sections into the main body
    body_title = "Main Content"
    body_level = 1
    for key, value in self.parse_content().sections.items():
        content.add_content(
            content=f"**{key}**:",
            section_title=body_title,
            section_level=body_level,
        )
        content.add_content(
            content=value.content,
            section_title=body_title,
            section_level=body_level,
        )

    # If context is provided, merge it
    if context:
        context_title = "Context"
        context_level = 2
        for key, value in context.sections.items():
            content.add_content(
                content=f"**{key}**:",
                section_title=context_title,
                section_level=context_level,
            )
            content.add_content(
                content=value.content,
                section_title=context_title,
                section_level=context_level,
            )

    return content