Title

markstat -- Dynamic Documents with Stata and Markdown -- 2.1

Syntax

markstat using filename [, pdf docx
slides beamer mathjax bundle
bibliography strict nodo nor keep]

filename is a required argument specifying the name of the
Stata-Markdown file. It should have extension .stmd, but
this may be omitted when typing the command. The filename must
be enclosed in double quotes if it contains blanks.

Options

pdf is an optional argument used to request generating a
PDF rather than an HTML file.

docx requests generating a Word document instead.

slides generates an HTML slide show using the S5 engine and the
default Blue Spiral theme, and slides(santiago) uses the Santiago
theme. Add a + for incremental mode, typing slides(+) or
slides(santiago+).

beamer generates a PDF slide show via LaTeX using Beamer and the
default theme, and beamer(theme) uses any of the many Beamer themes
available, for example beamer(madrid). Add a + for incremental mode.

mathjax is used to render LaTeX equations in HTML documents,
including S5 slide shows, using the JavaScript library MathJax. Not
needed for PDF or Word documents, where LaTeX equations are rendered natively.

bundle is used to generate self-contained HTML documents, encoding
all images and ancillary CSS and JavaScript files using base64. MathJax
cannot be bundled, but a local link may be used. The option is not
needed for PDF or Word documents, which are always self-contained.

bibliography is used to resolve citations using a BibTeX
database, and add a list of references at the end of the document,
see citations below. Works with all formats.

strict specifies that you are using the strict syntax, as explained in
the Stata Code section below. Code fences are now
detected automatically, so this option can be omitted in most cases.

nodo is used to skip running the Stata do file when you have just
tweaked the narrative. Useful for presentations, where you may change from
S5 to Beamer or try a different theme without rerunning the analysis.
The idea comes from Ben Jann's nodo option in texdoc.

nor skips running the R script when you have just tweaked the narrative,
think of it as the R equivalent of nodo.

keep controls the fate of intermediate files which are now deleted
to avoid cluttering your hard drive. The default is to keep only smcl and
rout log files to enable nodo and nor, in addition of course
to the output files html, pdf and docx. Specify keep(list)
to specify which additional files to keep, for example keep(do tex) to
keep the Stata do and LaTeX tex files, and keep to keep everything.

Description

The basic idea of this command is to prepare an input file that
combines comments and annotations written in Markdown, with Stata
commands that appear in blocks indented one tab or four spaces, as in the
following example:

+
+
| Stata Markdown |
| -------------- |
| |
| Let us read the fuel efficiency data that ships with Stata |
| |
| sysuse auto, clear |
| |
| To study how fuel efficiency depends on weight it is useful to |
| transform the dependent variable from "miles per gallon" to |
| "gallons per 100 miles" |
| |
| gen gphm = 100/mpg |
| |
| We then obtain a fairly linear relationship |
| |
| twoway scatter gphm weight | lfit gphm weight, /// |
| ytitle(Gallons per 100 Miles) legend(off) |
| graph export auto.png, width(500) replace |
| |
| ![Fuel Efficiency by Weight](auto.png) |
| |
| The regression equation estimated by OLS is |
| |
| regress gphm weight |
| |
| Thus, a car that weighs 1,000 pounds more than another requires |
| on average an extra 1.4 gallons to travel 100 miles. |
| |
| That's all for now! |
+
+

Saving this code as auto.stmd and running the command
markstat using auto produces the web page shown at
http://data.princeton.edu/stata/markdown/auto.
Adding the option pdf generates a PDF file,
and docx generates a Word document, all from the same script.
See also presentations below.

Requirements

The command uses an external Markdown processor,
John MacFarlane's pandoc,
which can be downloaded for Linux, Mac or Windows from
http://pandoc.org/installing. Generating Word
documents requires Pandoc 2.0 or higher.

It also requires the Stata command whereis, available from SSC.
This command is used to keep track of ancillary programs and is usually
installed together with markstat.
After downloading pandoc, you save the location of the
executable in the whereis database by running the command
whereis pandoc location.

If you want to generate PDF output you also need LaTeX, specifically
pdflatex, which comes with MiKTeX on Windows, MacTeX
on Macs or Live TeX on Linux. You save the location of the converter
by running the command whereis pdflatex location.
This is also used for Beamer presentations.

To properly render Stata logs in PDF format you also need the
LaTeX package stata.sty available from the Stata Journal.
The Stata command sjlatex will install all journal files, but
we only need this one. I suggest you download if from
http://www.stata-journal.com/production/sjlatex/stata.sty,
copy it in your local textmf folder and update the TeX database.
Note also that stata.sty requires alttt.sty and
pstricks.sty; these packages are available in most TeX distributions.

For server installations these tooling steps are usually completed
by a system administrator.

Markdown Code

Markdown is a lightweight markup language invented by John Gruber.
It is easy to write and, more importantly, it was designed to be
easy to read, without intrusive markings. See Markdown: Basics
at http://daringfireball.net/projects/markdown/basics
for a quick introduction.

Our example uses only two Markdown features: the use of dashes as
underlining to create a heading at level 2, and the construction
![alt-text](source) to create a link to an image given a
title(alt-text) and a source, in our case
![Fuel Efficiency by Weight](auto.png).
You may use italics, bold and monospace fonts, create
numbered and bulleted lists, insert links, and much more.

Pandoc implements several extensions to Markdown, including metadata,
basic tables, and pipe tables. It also lets you incorporate inline and
display mathematical equations using LaTeX notation. See John MacFarlane's
User's Guide at http://pandoc.org/MANUAL.html
for more information.

Stata Code

The simple indentation rule using one tab or four spaces for Stata code
permits clean input, but precludes some advanced Markdown options, including
multi-paragraph and nested lists. An alternative is to use the strict syntax,
where code appears in fenced blocks. This syntax is activated by the strict
option, or set automatically if you use code fences in the first 50 lines of
your script. In strict mode Stata code goes in blocks like this:

```s
// Stata commands go here
```

The opening fence may also be coded as ```{s}, with the s in
braces. The closing fence is always ```.

There is also an option to supress echoing Stata commands in a strict
code block, which is indicated by appending a slash to the s,
so the opening fence is either ```s/ or optionally ```{s/}.
This feature may be useful in producing dynamic documents
where the code itself is of secondary interest.

You may also use inline code to quote Stata results using the syntax

`s [fmt] expression`

where [fmt] is an optional format. For example after a regression you may
retrieve the value of R-squared using `s e(r2)`, or
using `s %5.2f e(r2)` to print the value with just two decimals.

Inline code is intended for short text, and cannot span more than one line.
The markstat command uses Stata's display command to evaluate
the code, and retrieves only one line of output to be spliced with the text.
The expression may contain macro evaluations and/or compound quotes.

Mata Code

Stata code can always use mata: to enter Mata and end to exit,
but markstat also allows coding Mata blocks directly, using an m
instead of an s in the code fence:

```m
// Mata code goes here
```

The fence may include optional braces as before, and the code may be supressed
by appending a slash to the m, although this is rare.

Mata results may also be displayed inline using the syntax

`m [fmt] expression`

which is identical to inline Stata but with an m instead of an s.

R Code

R code can be included in fenced code blocks using an r instead of an s
or m:

```r
# R code goes here
```

The fence may include optional braces as before, and the code may be supressed
by appending a slash to the r. Of course for the code to run you need to
have R installed. You also need to register the location of the R executable
using whereis.

R results may also be displayed inline using the syntax

`r expression`

which is just like inline Stata or Mata but with an r instead of an s
or m and no format (use R's round() instead).

Metadata

A script may include the title, author and date as metadata at the top of the
document in three lines starting with %. Our example could have started

% Markstat 2.0
% Germán Rodríguez
% 31 October 2017

The data field may use inline code `s c(current_date)` to get the date from Stata.
Metadata can also be entered using YAML blocks, as explained in the
website linked at the end.

Presentations

A slide show using S5 or Beamer must start with a metadata block
providing the title, author and date of the presentation, followed by
Stata and Markdown code using the simple or strict syntax. A simple example
may be found in the website listed at the bottom.

In a simple presentation, each heading at level 1 defines a slide and
is followed by contents, usually bullet points, figures and tables,
generated using Stata. In a multipart presentation, level-1 headings define
parts and generate title slides, and level-2 headings define slides.
Pandoc figures out the slide level looking for the highest level heading
followed immediately by contents.

When you create a presentation you include figures using the Markdown syntax
![title](source){width="60%"}. I recommend you always specify
a relative size as shown in this example. If you are using Beamer, add
{.fragile} to the heading of slides that contain Stata
commands or output (or any verbatim content).

Citations

Thanks to the amazing Pandoc, markstat also supports bibliographic
references. In addition to the bibliography option, the document
must include a YAML block with the name of the BibTeX database,
and may optionally include a reference to a citation style to use
instead of the default Chicago author-date format.
For more information and examples, see the website linked below.

Website

For more detailed information, including documentation, examples,
and answers to frequently asked questions, please visit
http://data.princeton.edu/stata/markdown.

Author

Germán Rodríguez <grodri@princeton.edu>
data.princeton.edu.