Stata markdown: can dyndoc create md files instead of html?

[diana gold]

I'm working in a project with many collaborators, all of which have Stata version 15. We use the dyndoc command to generate the documentation of our datasets, but need the documentation to be .md instead of .html (default in dyndoc), so it's all easily displayed and linked in Github, which we use to maintain the project.

Currently, the solution is to call Pandoc after every dyndoc to convert from .html to .md (see mock code). The downside is that it requires that every user installs Pandoc and points it is in Stata, which is not a trivial task for all our collaborators.

* Copy the example files from the official dyndoc documentation to my path
global mypath "C:/Users/JohnDoe/Desktop/dyndoctest"
foreach file in dyndoc_ex.txt header.txt stmarkdown.css {
    copy "http://www.stata-press.com/data/r15/markdown/`file'" "${mypath}/`file'", replace
}

* Generates the same html output as found in http://www.stata-press.com/data/r15/markdown/dyndoc_ex.html
cd "${mypath}"
dyndoc dyndoc_ex.txt, saving(dyndoc_output.html) replace

* What I have been doing is to convert this html into md using pandoc
* but the user must have installed pandoc.exe in his computer for this to work
local  whereispandoc "C:/Users/JohnDoe/Pandoc/pandoc"
local  pandoc_cmd    "`whereispandoc' ${mypath}/dyndoc_output.html -f html -t markdown -s -o ${mypath}/dyndoc_output.md"
shell `pandoc_cmd'

Given that there is a markdown command in Stata 15, I suspect that there must be a better way to do this from within Stata, without having to resort to Pandoc. But looking at the dyndoc and markdown ados in the base folder I could not figure out how... Any suggestions?

Thanks for any advice!

[Hua Peng (StataCorp)]

Yes, you can. dyndoc uses dyntext first to process all dynamic tags, then call markdown to convert the resulted mrakdown document to html. Using dyntext alone will leave you the markdown file.

For example, the following example.txt is a markdown file with dynamic tags

# This is an example

I am going to examine fuel efficiency using **auto.dta**. First, I load the dataset:

~~~~
<<dd_do>>
sysuse auto, clear
<</dd_do>>
~~~~

Now I **summarize** the variable **mpg**.

~~~~
<<dd_do: nocommands>>
summarize mpg
<</dd_do>>
~~~~

The variable **mpg** has minimum value <<dd_display: %4.2f `r(min)'>>
and has maximum value <<dd_display: %4.2f `r(max)'>>.

Use command

dyntext example.txt, saving(example.md) replace

will produce the following markdown file example.md

# This is an example

I am going to examine fuel efficiency using **auto.dta**. First, I load the dataset:

~~~~
. sysuse auto, clear
(1978 Automobile Data)

~~~~

Now I **summarize** the variable **mpg**.

~~~~

    Variable |        Obs        Mean    Std. Dev.       Min        Max
-------------+---------------------------------------------------------
         mpg |         74     21.2973    5.785503         12         41

~~~~

The variable **mpg** has minimum value 12.00
and has maximum value 41.00.

And you can use the command:

markdown example.md, saving(example.html) replace

to get the HTML file example.html.

[diana gold]

Perfect, thank you!