stlhp : markdoc : use # for title instead of ===== in md hlp file

[kbjarkefur]

Use:

# Title

Instead of:

Title
=======

Also test using pandoc

[kbjarkefur]

This works. Tested in d2453f21bd0bd7135fdcd82806f76b3856141600

This see output markdown-source-markdoc-mdsyntax.sthlp created in this run file.

I have updated my recommendations to use # syntax over ======.

##, ### etc. works the same as # when converted to sthlp by markdoc.

[arthur-shaw]

Great news that both ways of specifying headings in Markdown work equally well with MarkDoc!

As a precaution, I'll confirm that adodown doesn't require a certain heading format to construct pages. On quick scan of the code, I believe the code only really looks for YAML boundaries. But it's worth making sure.

Separately, you note that #, ##, ###, etc all yield {title:} in .sthlp. Does SMCL have any (rough) equivalent of H2, H3, etc headings? If so, would there be any value making a PR to MarkDoc to capitalize on this sematic mapping?

[kbjarkefur]

There is no close match the H2, H3 etc. in smcl. There are the titles (title:} and there something called {dlgtab:}" that a kind of section header. See code and snippet below.

{title:This is a title}

{dlgtab :This is a dlgtab}

{dlgtab 10:You can indent a dlgtab}

I wonder if writing our own tool is easier than contributing to markdoc. I am all for contributing to open source tools, but markdoc does so many things. And since Stata packages are big programs rather that many functions/methods it is hard to contribute to the corner of markdoc that we want to contribute to without having to learn everything else that the command is doing. Another reason is that there is no established way in Stata to rely on other community contributed commands. There are ways to do that, but they are always a bit hacky. We can talk more about this later.