Source control for a knowledge management repository requires some method to add meta data to a file. It seems that the yaml header is quickly gaining wide adoption for markdown based knowledge management solutions, even though it is unlikely to become an official standard for perfectly valid reasons.

This feature would enable Bitbucket to add new metadata based features that are not possible today. I do not recommend using Bitbucket for a knowledge management repository until a method for adding metadata is supported.

One reason we'd like to see this is because there's no other way of distinguishing between the document Title and top-level Headings. See this Stackoverflow comment and answer.

It feels wrong to use just one `# My Doc` as the document title, because semantically then everything becomes sub-headings of "section 1", when what you really want are multiple top-level (H1) headings within a doc entitled "My Doc".

FWIW, word processors like MS Word allow this distinction out of the box: the default Title style is not included in the set of Heading styles which are included in document section numbering.

We are embedding metadata into our markdown to facilitate our Request for Comment process. This isn't particularly pretty when rendered, but we're living with it for now.

It'd be great if the YAML header was supported out-of-the-box by Bitbucket (and lets face it - it's not exactly hard to do).

any update. I can't seem to get yaml to render in markdown on bitbucket.org.

```yaml

xyz: abc

```

Our team is also looking to utilize metadata in the README.md to provide configuration settings for the build environment and would like to see Bitbucket correctly omit this information from the rendered HTML (as seen in VSCode and others)

The GitHub feature was announced years ago at Viewing YAML Metadata in your Documents - The GitHub Blog, so it is not undocumented.

I wonder if any of these tools support ending the YAML header with three dots (...). From my reading of the YAML 1.0 and 1.2 specs, three dots seem more appropriate than three dashes because another YAML document does not follow. However, all the examples I have seen use three dashes as the closing delimiter, and DocFx 2.34 requires three dashes. If three dots need not be supported, I guess that makes the implementation easier for Atlassian.

Having Bitbucket Server hide the YAML header entirely from rendered output would be fine with me. Users could click the "Raw file" link if they want to see it.

I'd love to see this implemented as these headers are recognized by tooling like Visual Studio Code (which doesn't include it in the rendered output).

We are use this information with some internal tools that we use to publish .md files from our repos to Confluence:

---
title: Confluence Tools
parent_title: Projects
attachment: tool-box-icon.png
---

Confluence Tools
================

![Toolbox Icon](tool-box-icon.png)

This package provides tooling to upload content to a Confluence wiki...

Similar syntax is documented for Pandoc (YAML metadata block) and Jekyll (front matter).

GitHub renders the YAML header as nested tables, but I don't think such complexity is necessary. To me, the most important thing is not rendering it as a bogus setext heading that clutters the view. Perhaps just render it as a code block as if delimited by ```yaml and ```. Optionally, put an HTML5 <details> element around it and set a cookie to indicate whether the user wants the details to open by default.