How to Create an HTML Webpage in Stata using Markdown
Stata recently introduced the dyndoc command, which will process a text file and create an HTML file from it. The text file can contain a mixture of Markdown code, Stata commands with dynamic tags, and some HTML tags for more maneuverability. You do not need to know any HTML to use dyndoc, it can be run with just Markdown and Stata commands. However, if you are trying to do something specific and are having difficulty with Markdown it can help to add some HTML tags to your code. If you choose to add HTML tags the dyndoc command will be able to read most of these.
Stata Dynamic Tags
Stata has created special dyndoc tags designed to contain your Stata commands. A brief overview of these special tags is given below.
<<dd_do>> and <</dd_do>>
These tags are designed to contain your Stata analysis. Start with the <<dd_do>> tag, then on the next line start your Stata commands, and the last line once all your commands are finished is <</dd_do>> on its own. When Stata is converting your text file to HTML it will read anything given in-between these two tags as Stata commands. It will then run these commands and embed the output into the HTML file.
These tags can also be given a special attribute, which tells Stata to run the command in a special way. There are four attributes, as follows:
quietly – suppress all output
nocommands – suppress the commands but still show the output
nooutput – supress the output of the command but still show the command that was run
noprompt – suppress the Stata dot prompt
These attributes are given as part of the <<dd_do>> tag. For example, to run some commands but only print the output and not the command itself (usually printed above the output):
<<dd_do: no commands>> **Some Stata commands** <</dd_do>>
This tag is given within another line of regular text and utilises Stata’s display command. You will need to give the command within the tag - <<dd_display: insert command here>>. For example, my text file contains the following line:
Today is <<dd_display: "`c(current_date)'">> and we are going to learn some Stata!
This would add the following line of text to the HTML file:
Today is 26 May and we are going to learn some Stata!
This tag will export a Stata graph and add a link to the graph image file in HTML. Much like the <<dd_do>> tag there are special attributes you can give the <<dd_graph>> tag. For this tag you can give multiple attributes at once. For a list of attributes check out the Stata help file, found using the command help dynamic tags. I have given a couple of examples of commonly used attributes below:
saving(filename) – specify the location you want the graph file exported to
replace – replace the graph file if it already exists
graphname(name) – the name of the graph if you named it when it was created in Stata
png – export the graph as a png file
These attributes are given as part of the <<dd_graph>> tag, which is usually given on its own line. For example:
<<dd_graph: saving(C:\Users\Laura\Desktop\newgraph) replace graphname(hist) png>>
There are a few other dynamic tags which we will not cover here. For more information about the different dynamic tags available, check out the help file with the command help dynamic tags.
Stata reads Markdown syntax to transform your text file into HTML. Markdown is an easy way of formatting text for later processing into HTML. Due to its simplicity there are some limitations, but it works very well for the purpose of processing a text file with Stata code into HTML. A couple of examples of Markdown syntax are shown below:
You denote a heading in Markdown using #. One # is heading 1, two ## is heading 2, etc. For example:
#Heading One ##Heading Two ###Heading Three
Columns of a table are marked by the vertical line |, and each line of text is a row in the table. If you want the first row to be a header row, then the second row needs to have :--: between the vertical lines |. For example:
| Column 1 | Column 2 | Column 3 | |:--------:|:--------:|:--------:| | Row 1 C1 | Row 1 C2 | Row 1 C3 | | Row 2 C1 | Row 2 C2 | Row 2 C3 | |:--------:|:--------:|:--------:|
This should give a table that looks a bit like this:
You will notice that there are no borders or anything applied to this table. This is because I ran this in simple markdown and I did not apply a .css style file, so I only got a very basic table. Note that the column headers are in bold, something that dyndoc applies itself when it converts a table with the second row containing |:---:| sections. These sections mark the row above out as a header row in Markdown.
Any Stata code must be contained within <<dd_do>> and <</dd_do>> tags, however it is also a good idea to add markdown tags to indicate a code block. You do this with four tilde’s in a row ~~~~. Put these on the line above <<dd_do>> and the line below <</dd_do>>. For example:
~~~~ <<dd_do>> sysuse auto, clear describe <</dd_do>> ~~~~
For more information on Markdown syntax check out the Wikipedia page.
Worked Example 1 - A Simple Webpage:
In this example I will use the auto dataset in Stata and create a small HTML page which you should be able to replicate easily in Stata. You can download the text file here:
This example text file contains the following:
#The Auto Dataset Let's have a look at the Stata example dataset auto.dta. It can be loaded using the command **sysuse auto**. ~~~~ <<dd_do: nocommands>> sysuse auto, clear describe summarize list make price mpg in 1/10 histogram rep78, discrete frequency name(hist, replace) <</dd_do>> ~~~~ ##Histogram of Variable rep78 <<dd_graph: graphname(hist) png>> This HTML file was created on <<dd_display: "`c(current_date)'">>.
To run this text file in Stata using dyndoc:
dyndoc "C:\Users\LauraWhiting\Documents\example1.txt", replace
This gives the following output in Stata:
This produces this HTML file (uploaded here as a text file):
If you want to open this as an HTML file, simply re-save and change the extension from .txt to .html, or right-click and select "open with ...", and choose a web browser to open it.
The HTML file is also shown below in screenshots:
Worked Example 2 - A COVID19 Dashboard:
For this example I have created a text file called "coviddoc.txt" which will create a COVID19 Dashboard as an HTML. It uses a markdown .css file called "stmarkdown.css" to format the HTML (make it pretty). There is also an extra text file called "header.txt" which contains the information necessary for the dyndoc command to read the markdown css file. I will link all of these files at the bottom of this example.
All of the information is imported and analysed through the use of Stata dynamic tags in the text file, with the exception of a couple of datasets that need to be saved externally. The break down of COVID19 cases by gender and age-group can be found at the Australian federal government Department of Health, however it has to be copy-pasted into Stata as there is no option to download the data. I have saved this gender/age group as a Stata dataset for my analysis, which is linked below as part of a ZIP file.
I have also saved the map dataset and the accompanying shapefile as I have made some changes to these externally. The map datasets are linked below as part of a ZIP file, however these will need to be set up as spatial dataset with spset before you can use them. If you are having difficulty with the linked files, the original map files can be found at the Australian Bureau of Statistics. Check out our tech tip on choropleth maps for more information on how to set up these map files in Stata.
The coviddoc.txt text file combined with the additional datasets and css/header files linked above, when run through Stata’s dyndoc command, produces the following HTML dashboard (shown as screenshots below):
In the text file I added some HTML select and option tags, so you can click the drop-down menu and select an individual state to look at the charts for. For example, let’s look at NSW:
Below are all the files I used to create this HTML dashboard for COVID19. The "stmarkdown.css" file and the Stata datasets are contained in the "datasets.zip" compressed folder. Extract the .css and .dta files from the ZIP folder, and download the coviddoc and header text files. All these files will need to be placed in the same folder, and you will need to make sure the map dataset (STE_2016_AUST.dta) is spset to the shapefile dataset (STE_2016_AUST_shp.dta).