Metadata¶

User's guide¶

Metadata in Foliant allows you to assign additional properties to the chapters (Markdown files) and sections (parts of a Markdown file) of your project. These properties will be present in the Markdown sources but won't be directly rendered in the built documents. It is up to extensions to make use of these properties and alter your document in the desired way.

For instance, Confluence backend uses metadata to upload specific parts of your project into separate Confluence articles. AltStructure config extension uses metadata to rearrange the chapters of your project in the final build. TemplateParser preprocessor can access the metadata and generate chunks of text using the properties defined in it.

The foliantcontrib.meta package is required for metadata to work, but you won't need to install it directly. Every extension which uses metadata will install it automatically.

Syntax¶

There are two ways to define metadata:

In a YAML Front Matter — to define metadata for a whole chapter,
Using the <meta></meta> tag to define metadata for a section, as well as for the chapter.

YAML Front Matter

YAML Front Matter (or YFM for short) must be defined at the very beginning of a Markdown file. Properties in the YFM are applied to the whole chapter.

---
author: John Smith
revision_date: 17 August 2021
---

In this example we've defined two properties: author and revision_date for one chapter.

Meta tag

Meta tags may add properties to smaller chunks of a Markdown file, as well as the whole chapter. If the meta tag is specified at the very beginning of the file, it acts similarly to the YAML Front Matter, e.g. is applied to the whole chapter. To add properties to a smaller chunk of a Markdown file, specify the tag under a heading. The metadata will be applied to the text under the heading and all nested headings.

# Specification

<meta author="John Smith" revision_date="17 August 2021"></meta>

Lorem, ipsum dolor sit amet consectetur adipisicing elit. Aliquid neque, in, necessitatibus maxime repudiandae cum.

## Additional notes

Lorem ipsum, dolor, sit amet consectetur adipisicing elit. Incidunt pariatur, vel voluptatum exercitationem quae cupiditate!

In this example both Specification and Additional notes have the author and revision_date properties.

Sections¶

Section is a part of a Markdown file with defined metadata. Section begins with a Markdown heading (## Heading) and ends before the next heading of the same or higher level (## Another heading or # Another heading). A part of a Markdown document is only considered a section if the meta tag is defined in it, with one exception: the main section.

The main section is defined implicitly for every chapter of your project, even if there's no meta tag or YFM in it. In other words, if the Markdown file is specified in the chapters in foliant.yml, it will appear in the meta registry, with or without meta properties.

Here's an illustration of meta sections in a chapter:

Special fields¶

Most meta properties don't mean anything if no extension is using them. The only exception right now is the id property. It is the identifier of a section.

IDs are used to distinguish meta sections in the project. They must me unique inside the project. By default IDs are generated by the Meta engine implicitly, but you may override them by defining the id property in the section's metadata. Just make sure that it is unique.

The Meta registry¶

All extensions that work with metadata have access to the Meta registry. It is a hierarchical mapping of all sections in the project with all meta properties defined for each section.

To take a look at the Meta registry in your project run the meta generate command

$ foliant meta generate
Generating metadata... Done
────────────────────
Result: meta.yml

The registry is saved into the meta.yml file.

Additional info¶

Metadata works only for files, mentioned in the chapters section in foliant.yml. All other files in src dir are ignored and won't appear in the Meta registry.

When using includes, all metadata from the included content is removed.

Developer's guide¶

You can use the powers of metadata in your preprocessors, backends and other extensions. You can define fields with special meaning for your tools and process sections based on the values in these fields.

Getting metadata¶

Typical way to work with metadata is to run the load_meta function from the foliant.meta.generate module.

load_meta(chapters: list, md_root: str or PosixPath = 'src') -> Meta

This function returns the Meta registry in a Meta object, which gives access to all sections and meta-fields in the project.

The required parameter for load_meta is chapters — list of chapters loaded from foliant.yml

>>> from foliant.meta.generate import load_meta
>>> meta = load_meta(['index.md'])

You can also specify the md_root parameter. If your tool is a CLI extension, md_root should point to the project's src dir. But if you are building a preprocessor or a backend, you would probably want to point it to the __folianttmp__ dir with the current state of the sources.

The Meta class¶

Meta class holds all project's metadata and offers few handy methods to work with it.

load_meta_from_file(filename: str or PosixPath)

This method allows you to load meta into the Meta class instance from previously generated yaml-file. Use it only with an empty Meta class:

>>> from foliant.meta.classes import Meta
>>> meta = Meta()
>>> meta.load_meta_from_file('meta.yml')

iter_sections()

This method returns an iterator which yields project's meta-sections (Section objects) in the proper order from the first chapter to the last one.

get_chapter(self, filename: str or PosixPath) -> Chapter

Get chapter (Chapter object) by its path. filename should be path to chapter relative to the Project dir (or an absolute path).

get_by_id(self, id_: str) -> Section

Get section (Section object) by its id.

chapters

This property holds the list of chapters (Chapter objects).

The Chapter class¶

Chapter class represents a project's chapter. It has several important methods which may be useful for working with metadata.

iter_sections()

This method returns an iterator which yields chapter's meta-sections (Section objects) in the proper order from the first chapter to the last one.

get_section_by_offset(offset: int) -> Section:

This method allows you to get section (Section object) by just pointing to a place in text. Pointing is performed by specifying offset from the beginning of the file in offset parameter.

important properties

main_section

A property which holds the main section of the chapter.

name

Chapter's name as stated in foliant.yml (e.g. 'chapter.md').

filename

Chapter's filepath string (e.g. 'src/chapter.md').

The Section class¶

Section represents a meta section.

iter_children()

This method returns an iterator which yields the section's child sections (Section objects) in the proper order.

get_source(self, without_meta=True) -> str

Returns section's source. The section title is also included in the output. If without_meta is True, all meta tags are cut out from the text.

is_main(self) -> bool

Determine whether the section is a main section or not.

important properties

id

Holds section's ID.

title

Section's title.

chapter

Holds a reference to the section's Chapter object.

parent

Holds a reference to the section's parent section (Section object). Main sections have None in this property.

children

Holds list of section's children (Section objects) in proper order.

data

Holds a dictionary with meta properties and their values, defined in the <meta> tag (or the YAML front matter if it is a main section).

level

Section's level. Main section has level 0, section, defined inside the ### heading will have the level 3.

start and end

Section's offsets from the beginning of the Markdown file.

filename

Holds a reference to section's chapter's filename for easy access.