@callback artefacts() :: [Magma.Artefact.t()]

A callback that returns the list of Magma.Artefact types that are available for this matter type.

@callback concept_name(t()) :: binary()

A callback that returns the name of the Magma.Concept document.

Note that this name must unique across all document names in the vault.

@callback concept_title(t()) :: binary()

A callback that returns the title header text of the Magma.Concept document.

@callback context_knowledge(Magma.Concept.t()) :: binary() | nil

A callback that allows to specify texts which should be included generally in the "Context knowledge" section of the Magma.Artefact.Prompt document about this type of matter.

@callback custom_concept_sections(Magma.Concept.t()) :: binary() | nil

A callback that can be used to define additional sections for the Magma.Concept document.

@callback default_concept_aliases(t()) :: list()

A callback that returns a list of Obsidian aliases for the Magma.Concept document of this type of matter.

@callback default_description(
  t(),
  keyword()
) :: binary()

A callback that returns a text for the body of the "Description" section in the Magma.Concept document.

As the description is something written by the user, this should return a comment with a hint of what is expected to be written.

@callback extract_from_metadata(
  document_name :: binary(),
  document_title :: binary(),
  document_metadata :: map()
) :: {:ok, t(), keyword()} | {:error, any()}

A callback that extracts an instance of this matter type from the matter-specific fields of the metadata during deserialization of a Magma.Concept document.

All YAML frontmatter properties are loaded first into the :custom_metadata map of a Magma.Document. This callback implementation should Map.pop/2 the matter-specific entries from the given document_metadata and return the created instance of this matter type and the consumed metadata in an ok tuple.

Counterpart of render_front_matter/1.

@callback prompt_concept_description_title(t()) :: binary()

A callback that returns the section title for the concept description of a type of matter in the Magma.Artefact.Prompt.

@callback prompt_matter_description(t()) :: binary() | nil

A callback that can be used to define a general description of some matter which should be included in the Magma.Artefact.Prompt.

This is used for example to include the code of module, in the case of Magma.Matter.Module.

@callback relative_base_path(t()) :: Path.t()

A callback that returns the path segment to be used for different kinds of documents for this type of matter.

This path segment will be incorporated in the path generator functions of the Magma.Document types.

@callback relative_concept_path(t()) :: Path.t()

A callback that returns the path for Magma.Concept documents about this type of matter.

This path is relative to the Magma.Vault.concept_path/0

@callback render_front_matter(t()) :: binary()

A callback that renders the matter-specific fields of this type of matter to YAML frontmatter.

Counterpart of extract_from_metadata/3.