{"id":42212883,"url":"https://github.com/foliant-docs/foliantcontrib.meta","last_synced_at":"2026-01-27T01:06:52.072Z","repository":{"id":57431778,"uuid":"194288387","full_name":"foliant-docs/foliantcontrib.meta","owner":"foliant-docs","description":"Metadata for Foliant","archived":false,"fork":false,"pushed_at":"2021-08-18T09:51:51.000Z","size":798,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-12-02T06:57:29.510Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/foliant-docs.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-06-28T14:37:20.000Z","updated_at":"2021-08-18T09:51:53.000Z","dependencies_parsed_at":"2022-08-28T22:12:36.226Z","dependency_job_id":null,"html_url":"https://github.com/foliant-docs/foliantcontrib.meta","commit_stats":null,"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"purl":"pkg:github/foliant-docs/foliantcontrib.meta","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.meta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.meta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.meta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.meta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/foliant-docs","download_url":"https://codeload.github.com/foliant-docs/foliantcontrib.meta/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/foliant-docs%2Ffoliantcontrib.meta/sbom","scorecard":{"id":406088,"data":{"date":"2025-08-11","repo":{"name":"github.com/foliant-docs/foliantcontrib.meta","commit":"60148521e73c01c3fa6a3a9f8dd7fb1ae40e04a0"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":3,"checks":[{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Code-Review","score":0,"reason":"Found 0/30 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"SAST","score":0,"reason":"no SAST tool detected","details":["Warn: no pull requests merged into dev branch"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"Pinned-Dependencies","score":-1,"reason":"no dependencies found","details":null,"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"Vulnerabilities","score":10,"reason":"0 existing vulnerabilities detected","details":null,"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}}]},"last_synced_at":"2025-08-18T21:17:48.159Z","repository_id":57431778,"created_at":"2025-08-18T21:17:48.159Z","updated_at":"2025-08-18T21:17:48.159Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28794640,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-26T21:49:50.245Z","status":"ssl_error","status_checked_at":"2026-01-26T21:48:29.455Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-27T01:06:51.416Z","updated_at":"2026-01-27T01:06:52.056Z","avatar_url":"https://github.com/foliant-docs.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![](https://img.shields.io/pypi/v/foliantcontrib.meta.svg)](https://pypi.org/project/foliantcontrib.meta/)  [![](https://img.shields.io/github/v/tag/foliant-docs/foliantcontrib.meta.svg?label=GitHub)](https://github.com/foliant-docs/foliantcontrib.meta)\n\n# Metadata for Foliant\n\nThis extension adds metadata support for Foliant. It also allows to add meta commands which use project's metadata and are called like this: `foliant meta \u003ccommand\u003e`. Finally, it adds the `meta generate` command to Foliant, which generates the yaml-file with project metadata.\n\n## Installation\n\n```bash\n$ pip install foliantcontrib.meta\n```\n\n## Specifying metadata\n\nMetadata for the *main section* (more on sections in **User's Guide** below) may be specified in the beginning of a Markdown-file using [YAML Front Matter](http://www.yaml.org/spec/1.2/spec.html#id2760395) format:\n\n```yaml\n---\nid: MAIN_DOC\ntitle: Description of the product\nkey: value\n---\n```\n\nYou may also use regular XML-like format with `meta` tag:\n\n```html\n\u003cmeta\n    id=\"MAIN_DOC\"\n    title=\"Description of the product\"\n    key=\"value\"\u003e\n\u003c/meta\u003e\n```\n\n\u003e If `meta` tag is present, all Metadata from YAML Front Matter is ignored.\n\n# Documentation\n\n## User's guide\n\nMetadata 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.\n\nFor instance, [Confluence](https://foliant-docs.github.io/docs/backends/confluence/) backend uses metadata to upload specific parts of your project into separate Confluence articles. [AltStructure](https://foliant-docs.github.io/docs/config/alt_structure/) config extension uses metadata to rearrange the chapters of your project in the final build. [TemplateParser](https://foliant-docs.github.io/docs/preprocessors/templateparser/) preprocessor can access the metadata and generate chunks of text using the properties defined in it.\n\nThe `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.\n\n### Syntax\n\nThere are two ways to define metadata:\n\n- In a [YAML Front Matter](http://www.yaml.org/spec/1.2/spec.html#id2760395) — to define metadata for a whole chapter,\n- Using the `\u003cmeta\u003e\u003c/meta\u003e` tag to define metadata for a section, as well as for the chapter.\n\n**YAML Front Matter**\n\nYAML 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.\n\n```yaml\n---\nauthor: John Smith\nrevision_date: 17 August 2021\n---\n```\n\nIn this example we've defined two properties: `author` and `revision_date` for one chapter.\n\n**Meta tag**\n\nMeta 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.\n\n```html\n# Specification\n\n\u003cmeta author=\"John Smith\" revision_date=\"17 August 2021\"\u003e\u003c/meta\u003e\n\nLorem, ipsum dolor sit amet consectetur adipisicing elit. Aliquid neque, in, necessitatibus maxime repudiandae cum.\n\n## Additional notes\n\nLorem ipsum, dolor, sit amet consectetur adipisicing elit. Incidunt pariatur, vel voluptatum exercitationem quae cupiditate!\n```\n\nIn this example both `Specification` and `Additional notes` have the `author` and `revision_date` properties.\n\n### Sections\n\n*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*.\n\nThe 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.\n\nHere's an illustration of meta sections in a chapter:\n\n![](https://raw.githubusercontent.com/foliant-docs/foliantcontrib.meta/master/img/pic1.png)\n\n### Special fields\n\nMost 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.\n\nIDs 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.\n\n### The Meta registry\n\nAll 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.\n\nTo take a look at the Meta registry in your project run the `meta generate` command\n\n```bash\n$ foliant meta generate\nGenerating metadata... Done\n────────────────────\nResult: meta.yml\n```\n\nThe registry is saved into the `meta.yml` file.\n\n### Additional info\n\nMetadata 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.\n\nWhen using [includes](https://foliant-docs.github.io/docs/preprocessors/includes/), all metadata from the included content is removed.\n\n## Developer's guide\n\nYou 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.\n\n### Getting metadata\n\nTypical way to work with metadata is to run the `load_meta` function from the `foliant.meta.generate` module.\n\n**load_meta(chapters: list, md_root: str or PosixPath = 'src') -\u003e Meta**\n\nThis function returns the Meta registry in a `Meta` object, which gives access to all sections and meta-fields in the project.\n\nThe required parameter for `load_meta` is `chapters` — list of chapters loaded from foliant.yml\n\n```python\n\u003e\u003e\u003e from foliant.meta.generate import load_meta\n\u003e\u003e\u003e meta = load_meta(['index.md'])\n```\n\nYou 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.\n\n### The Meta class\n\nMeta class holds all project's metadata and offers few handy methods to work with it.\n\n**load_meta_from_file(filename: str or PosixPath)**\n\nThis method allows you to load meta into the Meta class instance from previously generated yaml-file. Use it only with an empty Meta class:\n\n```python\n\u003e\u003e\u003e from foliant.meta.classes import Meta\n\u003e\u003e\u003e meta = Meta()\n\u003e\u003e\u003e meta.load_meta_from_file('meta.yml')\n```\n\n**iter_sections()**\n\nThis method returns an iterator which yields project's meta-sections (`Section` objects) in the proper order from the first chapter to the last one.\n\n**get_chapter(self, filename: str or PosixPath) -\u003e Chapter**\n\nGet chapter (`Chapter` object) by its path. `filename` should be path to chapter relative to the Project dir (or an absolute path).\n\n**get_by_id(self, id_: str) -\u003e Section**\n\nGet section (`Section` object) by its id.\n\n**chapters**\n\nThis property holds the list of chapters (`Chapter` objects).\n\n### The Chapter class\n\n`Chapter` class represents a project's chapter. It has several important methods which may be useful for working with metadata.\n\n**iter_sections()**\n\nThis method returns an iterator which yields chapter's meta-sections (`Section` objects) in the proper order from the first chapter to the last one.\n\n**get_section_by_offset(offset: int) -\u003e Section:**\n\nThis 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.\n\n*important properties*\n\n**main_section**\n\nA property which holds the main section of the chapter.\n\n**name**\n\nChapter's name as stated in foliant.yml (e.g. `'chapter.md'`).\n\n**filename**\n\nChapter's filepath string (e.g. `'src/chapter.md'`).\n\n### The Section class\n\n`Section` represents a meta section.\n\n**iter_children()**\n\nThis method returns an iterator which yields the section's child sections (`Section` objects) in the proper order.\n\n**get_source(self, without_meta=True) -\u003e str**\n\nReturns 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.\n\n**is_main(self) -\u003e bool**\n\nDetermine whether the section is a main section or not.\n\n*important properties*\n\n\n**id**\n\nHolds section's ID.\n\n**title**\n\nSection's title.\n\n**chapter**\n\nHolds a reference to the section's `Chapter` object.\n\n**parent**\n\nHolds a reference to the section's parent section (`Section` object). Main sections have `None` in this property.\n\n**children**\n\nHolds list of section's children (`Section` objects) in proper order.\n\n**data**\n\nHolds a dictionary with meta properties and their values, defined in the `\u003cmeta\u003e` tag (or the YAML front matter if it is a main section).\n\n**level**\n\nSection's level. Main section has level `0`, section, defined inside the `###` heading will have the level `3`.\n\n**start** and **end**\n\nSection's offsets from the beginning of the Markdown file.\n\n**filename**\n\nHolds a reference to section's chapter's filename for easy access.\n\n# Meta Generate command\n\n`meta generate` command collects metadata from the Foliant project and saves it into a YAML-file.\n\n## Usage\n\nTo generate meta file run the `meta generate` command:\n\n```bash\n$ foliant meta generate\n```\n\nMetadata for the document will appear in the `meta.yml` file.\n\n## Config\n\nMeta generate command has just one option right now. It is specified under `meta` section in config:\n\n```yaml\nmeta:\n    filename: meta.yml\n```\n\n`filename`\n:   name of the YAML-file with generated project metadata.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.meta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.meta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffoliant-docs%2Ffoliantcontrib.meta/lists"}