Update qhelp style guide for markdown format

[owen-mc]

We now support query help files formatted as markdown, but this was not documented. I have tried to update the documentation (with a lot of help from copilot). I am not particularly familiar with markdown query help files, so I may have got some things wrong.

[Copilot]

Pull Request Overview

This PR updates the Query Help Style Guide to document support for Markdown-formatted query help files alongside the existing XML format.

• Introduces a new section detailing the structure and requirements for Markdown .md query help files.
• Harmonizes references to section-level elements across both Markdown and XML formats.
• Adds a combined Markdown and XML query help example for Java.

Comments suppressed due to low confidence (2)

docs/query-help-style-guide.md:77

• The term “description section” is ambiguous in the Markdown context (we only define Overview, Recommendation, Example, etc.). Consider replacing “description section” with “overview section” or clarifying when each section should contain examples.

* Put the code example after the recommendation section where possible. Only include an example in the description section if absolutely necessary.

docs/query-help-style-guide.md:144

• Suggest clarifying that authors should not commit generated HTML (not Markdown) when writing native Markdown query help; the current wording may confuse manual vs. generated files.

Please include the query help files (and any associated code snippets) in your pull request, but do not commit the generated Markdown.

[owen-mc]

I based the updated guidance on a few java qhelp files, like this. I see there are also qhelp files for actions, like this, which have some small differences. We should decide which we way we want to go and standardize. In both cases the java ones are closer to the custom XML format.

• The first section in the java ones is ##Overview, and in the actions ones it is ##Description.
• The java ones have ##Recommendation and the actions ones have ##Recommendations.
• The actions ones have a title briefly summarising the query.

[owen-mc]

Having looked into the differences between the two, I have decided to stick with the format from the java .md files, because it is closer to the custom XML format. If you look at a code-scanning alert for an actions query, like this one, you will see two things:

• The title from the Markdown query help file is never shown. So there is no point in having one.
• The Description header is shown (but only after clicking "show more"). This is in contract to the custom XML format, where the corresponding Overview heading is never shown. It seems likely that if we instead use Overview for markdown then we will stop getting this unwanted header.

[adityasharad]

Looks great, thank you for updating this. Minor suggestions only.

[adityasharad]

One more difference: only Markdown is supported for custom queries / query packs.

[owen-mc]

Interesting. Do you know why that is?

[adityasharad]

Deliberate choice to reduce the risk from processing untrusted XML. Our XML processing has protections against entity expansion, but the includes mechanism isn't completely robust to untrusted XML help. Markdown help does not have this problem. For this reason we only support XML help we've written ourselves, and require Markdown help for custom query packs.

[adityasharad]

Minor suggestion: consider just making this a fenced code block with the five headings filled in, and gaps in between. Then it can be copied and used directly.