@spec empty?(t()) :: boolean()

Checks if the given section is empty, i.e. it has no content and nested sections.

@spec empty_content?(t()) :: boolean()

Checks if the given section consists solely of subsection headers.

@spec fetch(t() | Magma.DocumentStruct.compatible(), binary()) :: {:ok, t()} | :error

Fetches the section with the given title and returns it in an ok tuple.

If no section with section exists, it returns :error.

This implements Access.fetch/2 function, so that the section[title] syntax and the Kernel macros for accessing nested data structures like get_in/2 are supported.

This function only searches sections directly under the given section. For a recursive search, use section_by_title/2.

@spec new(
  Panpipe.AST.Header.t() | {pos_integer(), binary()},
  [Panpipe.AST.Node.t()],
  [t()]
) :: t()

Creates a new section.

@spec remove_comments(t()) :: t()

@spec remove_comments([Panpipe.AST.Node.t()]) :: [Panpipe.AST.Node.t()]

Removes all comment blocks from the given section_or_content.

This function cleans up the document by removing all comment blocks (<!-- comment -->).

@spec resolve_links(
  t(),
  keyword()
) :: t()

Resolves internal links in the provided section by replacing them with their content or display text.

The style of the resolved links can be specified with the :style option, which accepts the following values:

• :plain (default) - no styling
• :emph - italic
• :strong - bold
• :underline - underlined
• :at_file_ref - file path of the linked document in the form @"path/to/file.md", that is used by many coding agents (Claude Code, Cursor etc.) to reference files
• a function accepting the children of the link AST and returning the replacement AST node

Processes and resolves transclusions within the given section.

Transclusion resolution in Magma is a procedure where an Obsidian transclusion, such as ![[Some document]], is replaced with its actual content. This mechanism forms the foundation for constructing LLM prompts in Magma. The content from the referenced document or section undergoes several processing steps before its insertion:

• Comments (<!-- comment -->) are removed.
• Internal links are replaced with the target as plain text.
• Transclusions within the transcluded content itself are resolved recursively (unless it would result in an infinite recursion).
• If the transcluded content (after removing the comments), consists exclusively of a heading with no content below it, the transclusion is resolved with the empty string.
• The level of the transcluded sections is adjusted according to the current level at the point of the transclusion.

Different types of transclusions are resolved in slightly varied ways, particularly regarding the leading header of the transcluded content:

• Inline transclusions: Exclude the leading header.
• Custom header transclusions: Replace the leading header.
• Empty header transclusions: Retain the leading header.

@spec section_by_title(t(), binary()) :: t() | nil

Fetches the first section with the given title.

Other than accessing the sections with the fetch/2, this searches the sections recursively.

Sets a new header for the given section, updating the :title and :level fields accordingly.

Sets a new header with the given title and level for the given section, updating the :title and :level fields accordingly.

@spec set_level(t(), non_neg_integer()) :: t()

Changes the header level of section to the given level.

Computes the difference to the current level of section and shifts the level recursively on all subsections using shift_level/2.

@spec shift_level(t(), integer()) :: t()

Shifts the header level of section by the given shift_level.

All subsections are shifted recursively.

@spec to_markdown(
  t(),
  keyword()
) :: binary()

Converts a Magma.DocumentStruct.Section into a Markdown string.