6

What is the value in adding YAML atop an Azure DevOps Wiki page's markdown, as supported by its markdown syntax: Syntax guidance for Markdown usage in Wiki, YAML tags?

It seems to offer nothing more than an alternative syntax with which to specify tables. Perhaps more elaborate tables but they'll only render atop the page. What am I missing?

ScottWelker
  • 1,701
  • 17
  • 30
  • [Syntax guidance for Markdown usage in Wiki, YAML tags](https://learn.microsoft.com/en-us/azure/devops/project/wiki/wiki-markdown-guidance?view=azure-devops#yaml-tags) no longer mentions Azure DevOps Wiki's YAML feature. Presumably it has been removed. – ScottWelker Apr 05 '22 at 17:52

2 Answers2

3

As the introduction in the document,

Any file that contains a YAML block in a Wiki is processed by a table with one head and one row.

So, I think the value of YAML tags in the Wiki markdown is to convert the abstract YAML statements into a visual table on the Wiki page to increase readability and quick understanding.

Especially for a complex YAML block that may contain multiple items or multiple sub-items, the YAML tags should be very helpful.

[UPDATE]

I find an issue ticket (MicrosoftDocs/azure-devops-docs#9976) reported by another user on the GitHub repository "MicrosoftDocs/azure-devops-docs". This issue has reported a similar question.

And in this issue ticket, you also can see @amitkumariiit has given an explanation:

Yaml tags are used for general search engine optimisation. Our plan was to add the basic support for it first and then ingest this in the azure devops wiki search for optimise search. However we could not prioritise the search side of work.

If you need more detailed explanation, you can follow this issue ticket and add your comments to it.

Bright Ran-MSFT
  • 5,190
  • 1
  • 5
  • 12
  • 1
    Thanks @Bright Ran-MSFT. However the "value" cited seems to be a restatement of what it does. I understand what it does. I don't see how this adds value? If I wanted YAML to appear as a table why would I ONLY want this atop a page? What is the real-world use case? I really can't see how this is used to any positive effect. – ScottWelker Mar 25 '21 at 16:58
  • I accept your **[UPDATE]** as the answer. Thanks. – ScottWelker Oct 11 '21 at 19:29
  • @Bright-Ran-MSFT I tried inserting my YAML file content (Kubernetes manifest or Spring config) and rendering didn't make it more readable. Current implementation does not support deep levels of nested elements. Anything deeper than 3 levels is being wrapped into table cell. Try it yourself. – vbg Dec 14 '21 at 16:33
0

I am going to propose my own answer. It just occurred to me that this is likely intended to replace markdown, not to be used with markdown. That is to say, to support documentation written purely in YAML. That could make some sense, add value for some, and explain why it's ONLY supported atop the page. You use it instead of the markdown, not with the markdown.

The documentation just doesn't make it clear why/how you might want to use this feature.

ScottWelker
  • 1,701
  • 17
  • 30
  • This has perplexed me for quite a long time. My answer makes sense - to me. We'll see if there are other comments. I'll likely accept my answer. – ScottWelker Mar 25 '21 at 17:39
  • Hi @ScottWelker, please go ahead. – Bright Ran-MSFT Mar 26 '21 at 06:26
  • 1
    Hi @ScottWelker, I have update my answer with more information. It may be helpful to you. Please check it. – Bright Ran-MSFT Mar 29 '21 at 08:39
  • @Bright Ran-MSFT: Thanks for your "sleuthing". I accepted your answer as it demonstrates that my speculation was incorrect. The YAML support is apparently just an incomplete part of another feature (search). – ScottWelker Mar 29 '21 at 16:22