• 1
    • We collect Bitbucket feedback from various sources, and we evaluate what we've collected when planning our product roadmap. To understand how this piece of feedback will be reviewed, see our Implementation of New Features Policy.

      DocFX Flavored Markdown files can contain a YAML header. I would like Bitbucket Server to recognize this syntax when it renders a Markdown file to which I have navigated in the repository file browser. Currently, Bitbucket Server v5.6.2 renders the first triple-dash line as a horizontal rule and the rest as a setext heading.

      ---
      uid: data-dictionary.md
      title: Data Dictionary
      ---
      

      GitHub also seems to recognize this syntax, as evidenced in https://github.com/dotnet/docs/blob/VS2017/docs/csharp/csharp.md, even though GitHub Flavored Markdown Spec Version 0.28-gfm does not mention it.

      To minimize the compatibility risk, perhaps it would be best to recognize the YAML header only at the top of the file, where users are unlikely to intend a horizontal rule.

          Form Name

            [BSERV-10580] Recognize YAML header in Markdown files

            CAS IT added a comment -

            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.

            CAS IT added a comment - 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.

            ryan.jendoubi added a comment - 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).

            gerry.kessellhaak added a comment - 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

            ```

            Christopher Mortimer added a comment - 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)

            Deleted Account (Inactive) added a comment - 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.

            Kalle Niemitalo added a comment - 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.

            Kalle Niemitalo added a comment - 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.

            Zachary Roadhouse added a comment - - edited

            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...
            

            Zachary Roadhouse added a comment - - edited 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).

            Kalle Niemitalo added a comment - 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.

            Kalle Niemitalo added a comment - 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.

              Unassigned Unassigned
              bce11fd9005e Kalle Niemitalo
              Votes:
              18 Vote for this issue
              Watchers:
              20 Start watching this issue

                Created:
                Updated: