[
    {
        "role": "user",
        "content": "in%20a%20markdown%20document%2C%20I%27d%20like%20to%20put%20some%20identifying%20metadata%20at%20the%20top%20but%20without%20using%20a%20%23%20heading.%20what%20directives%20or%20best%20practices%20apply%3F"
    },
    {
        "role": "assistant",
        "content": "If you want to include identifying metadata at the top of a Markdown file *without* using a `#` heading, the generally accepted approach is to use **front matter**\u2014a block of structured metadata (usually YAML, TOML, or JSON) placed before the main content. Below are the directives and best practices, including syntax, tools/engines that support this, and tips for structure and consistency.\n\n---\n\n## What\u2019s Front Matter\n\nFront matter (also called \u201cYAML/TOML/JSON metadata\u201d) is a block at the very top of a Markdown file that holds metadata in key-value form. Static site generators like Jekyll, Hugo, Eleventy, Gatsby (MDX), GitHub Docs, and many Markdown-based tools support it. ([markdownliveview.com](https://markdownliveview.com/glossary/what-is-markdown-frontmatter/?utm_source=openai))\n\n---\n\n## Syntax Options\n\nHere are the common syntaxes and how to structure the metadata block:\n\n- **YAML (most common)**  \n  The block starts with `---` on the first line, ends with `---` (or sometimes `...`). Between them are key: value pairs. ([docs.zettlr.com](https://docs.zettlr.com/en/advanced/yaml-frontmatter/?utm_source=openai))  \n  Example:  \n  ```\n  ---\n  title: \"My Document\"\n  author: Jane Doe\n  date: 2026-05-03\n  tags: [metadata, markdown]\n  ---\n  \n  Rest of the Markdown content...\n  ```\n\n- **TOML**  \n  Delimiters often are `+++`.  \n  Example:  \n  ```\n  +++\n  title = \"Another Doc\"\n  date = \"2026-05-03\"\n  draft = false\n  +++\n  \n  Content...\n  ```\n\n- **JSON**  \n  Either between `;;;` or enclosed in `{ ... }` with delimiters. Less common but supported in some systems. ([markdownlang.com](https://www.markdownlang.com/advanced/frontmatter?utm_source=openai))\n\n---\n\n## What Metadata to Include (Common Fields)\n\nTypical fields you might include:\n\n- `title` \u2014 document title  \n- `date` \u2014 creation/publication date (preferably ISO 8601: `2026-05-03`)  \n- `author` or `authors`  \n- `description` or `summary`  \n- `tags`, `categories`, or `keywords`  \n- Versioning, layout/template, locale, etc. (depending on tooling) ([markdownlang.com](https://www.markdownlang.com/advanced/frontmatter?utm_source=openai))\n\n---\n\n## Tool Support & Behavior\n\n- **Markdown engines**: Jekyll, Hugo, Gatsby (\u201cfront matter\u201d is key part of their templating systems) ([markdownliveview.com](https://markdownliveview.com/glossary/what-is-markdown-frontmatter/?utm_source=openai))  \n- **Doc tools / documentation sites**: GitHub Docs, SuperOffice documentation, Growi, Zettlr etc. ([docs.github.com](https://docs.github.com/en/enterprise-server%403.18/contributing/writing-for-github-docs/using-yaml-frontmatter?utm_source=openai))  \n- **Editors/exporters**: Typora supports front matter to influence exported HTML, PDF, etc. ([support.typora.io](https://support.typora.io/YAML/?utm_source=openai))\n\n---\n\n## Best Practices\n\nTo keep the metadata useful, maintainable, and portable:\n\n1. **Place front matter at the very top**: It must start from line 1 of the file. Extra blank lines before the `---` can break parsing. ([stkb.github.io](https://stkb.github.io/Rewrap/specs/content-types/markdown/front-matter/?utm_source=openai))\n\n2. **Use consistent formats** for dates (ISO 8601: `YYYY-MM-DD` or `YYYY-MM-DDThh:mm:ssZ`) and other fields across all files. ([markdownlang.com](https://www.markdownlang.com/advanced/frontmatter?utm_source=openai))\n\n3. **Use quotes** around values that contain special characters, begin with numbers, include colons, or might be misinterpreted. ([docs.realmacsoftware.com](https://docs.realmacsoftware.com/elements-docs/cms/cms/markdown/frontmatter?utm_source=openai))\n\n4. **Avoid using `#` headings for metadata**: front matter is cleaner, not rendered in output (if parser/tool supports it), and doesn\u2019t show up visually as part of content.\n\n5. **Validate schema**: If using many documents (blogs, docs site, etc.), define which fields are required vs optional, and ideally use tooling to validate. ([markdownlang.com](https://www.markdownlang.com/advanced/frontmatter?utm_source=openai))\n\n6. **Keep irrelevant or tool-specific metadata clearly separated from content**: for example, things like version numbers, layout names, or internal identifiers should be in metadata, not in the visible content.\n\n---\n\n## Things to Watch Out For\n\n- Not all Markdown parsers support front matter. If your target tool doesn\u2019t, the front matter will often just render as literal text.  \n- Be careful with indentation (especially in YAML): use spaces, not tabs. YAML is sensitive. ([docs.zettlr.com](https://docs.zettlr.com/en/advanced/yaml-frontmatter/?utm_source=openai))  \n- If multiple syntax options are supported, choose one and stick with it across your documents for consistency.\n\n---\n\nIf you want, I can show you examples tailored to a specific tool you\u2019re using (like Pandoc, Hugo, Obsidian, etc.) so you can adopt best practices in your environment."
    }
]