MarkDoc package provides a convenient way to write dynamic document within Stata dofile editor. Before starting, remember that there are a few things that you must absolutely avoid while using MarkDoc.
Use only one markup language. While you are writing with Markdown you may also use HTML tags, but avoid LaTeX in combination of HTML or Markdown.
Only use English letters. Any unsual character (Chinese, French, or special characters) should be avoided.
Please make sure you that you have the permission to write and remove files in your current working directory. Especially if you are a Microsoft Windows user. Ideally, you should be the adminster of your system or at least, you should be able to run Stata as an adminstrator or superuser. Also pay attension to your current working directory.
Writing with Markdown syntax allows you to add text and graphs to smcl logfile and export it to a editable document format. I will demonstrate the process by using the auto.dta dataset.
I will open the dataset, list a few observations, and export a graph. Then I will export the log file to HTML format.
. quietly sysuse auto, clear
. list in 1/5
+-----------------------------------------------------------------+
1. | make | price | mpg | rep78 | headroom | trunk | weight |
| AMC Concord | 4,099 | 22 | 3 | 2.5 | 11 | 2,930 |
|-----------------------------------------------------------------|
| length | turn | displa~t | gear_r~o | foreign |
| 186 | 40 | 121 | 3.58 | Domestic |
+-----------------------------------------------------------------+
+-----------------------------------------------------------------+
2. | make | price | mpg | rep78 | headroom | trunk | weight |
| AMC Pacer | 4,749 | 17 | 3 | 3.0 | 11 | 3,350 |
|-----------------------------------------------------------------|
| length | turn | displa~t | gear_r~o | foreign |
| 173 | 40 | 258 | 2.53 | Domestic |
+-----------------------------------------------------------------+
+-----------------------------------------------------------------+
3. | make | price | mpg | rep78 | headroom | trunk | weight |
| AMC Spirit | 3,799 | 22 | . | 3.0 | 12 | 2,640 |
|-----------------------------------------------------------------|
| length | turn | displa~t | gear_r~o | foreign |
| 168 | 35 | 121 | 3.08 | Domestic |
+-----------------------------------------------------------------+
+-----------------------------------------------------------------+
4. | make | price | mpg | rep78 | headroom | trunk | weight |
| Buick Century | 4,816 | 20 | 3 | 4.5 | 16 | 3,250 |
|-----------------------------------------------------------------|
| length | turn | displa~t | gear_r~o | foreign |
| 196 | 40 | 196 | 2.93 | Domestic |
+-----------------------------------------------------------------+
+-----------------------------------------------------------------+
5. | make | price | mpg | rep78 | headroom | trunk | weight |
| Buick Electra | 7,827 | 15 | 4 | 4.0 | 20 | 4,080 |
|-----------------------------------------------------------------|
| length | turn | displa~t | gear_r~o | foreign |
| 222 | 43 | 350 | 2.41 | Domestic |
+-----------------------------------------------------------------+
. histogram price
(bin=8, start=3291, width=1576.875)
. graph export graph.png, replace width(350)
(note: file graph.png not found)
(file graph.png written in PNG format)
In order to add a graph using Markdown, I export the graph in PNG format. You can explain the graph in the brackets and define the file path in parentheses using Markdown syntax. Note that Markdown format cannot resize the figure and it will include it at its full size. Therefore, when you write with Markdown you should resize the graphs. Of course, if you write with LaTeX or HTML you will be able to do anything you wish! But Markdown is convertable to any format and thus is the prefered markup language for writing dynamic documents. In addition, it is a very minimalistic language. And perhaps that's what makes it so good, because it does not include numerous rules and tags to learn, compared to HTML and LaTeX. It's simple, easy to learn, and appealing to use.
The txt command can be used to write dynamic text in MarkDoc. To do so, put the value that you want to print in a Macro and then explain it using the txt command. Or instead, I use the stored values that Stata returns after particular commands by typinc return list.
In the example below, I use the summarize command, and print the r(N), r(mean), r(sd), r(min), and r(max) which are returned after the summarize command.
. summarize price
Variable | Obs Mean Std. Dev. Min Max
-------------+---------------------------------------------------------
price | 74 6165.257 2949.496 3291 15906
. regress price mpg
Source | SS df MS Number of obs = 74
-------------+---------------------------------- F(1, 72) = 20.26
Model | 139449474 1 139449474 Prob > F = 0.0000
Residual | 495615923 72 6883554.48 R-squared = 0.2196
-------------+---------------------------------- Adj R-squared = 0.2087
Total | 635065396 73 8699525.97 Root MSE = 2623.7
------------------------------------------------------------------------------
price | Coef. Std. Err. t P>|t| [95% Conf. Interval]
-------------+----------------------------------------------------------------
mpg | -238.8943 53.07669 -4.50 0.000 -344.7008 -133.0879
_cons | 11253.06 1170.813 9.61 0.000 8919.088 13587.03
------------------------------------------------------------------------------
You will find more information in this regard on my website. You can also Follow The Package Updates On TWITTER!
E. F. Haghish Center for Medical Biometry and Medical Informatics University of Freiburg, Germany haghish@imbi.uni-freiburg.de