Germán Rodríguez
Stata Markdown Princeton University

The Stata Tutorial

In July of 2017 I updated the Stata Tutorial for version 15, and it seemed a good time to convert it to a Stata Markdown script to be processed with markstat. A big advantage of this approach is that I could generate a PDF file via LaTeX from the same script used for the website. The script and the resulting HTML and PDF files are linked below:

Stata/Markdown
HTML
PDF

If you are interested in running the script yourself, note that you need to have the file _gpnupt.ado available in the working directory or your personal ado folder, as it is used in one of the examples. You will also need the file tweaks.tex to match the style used here. The following notes may also be of interest in reproducing the output.

The Input Script

In the source script I used the simple "one tab or four spaces" rule to indent code that should be run through Stata. To list code that is not to be run through Stata, for example to explain the syntax of a while loop, I used code fences as follows:

``` {.stata}
while condition {
    ... do something ...
}
```

The code is rendered in HTML as a preformatted block with class Stata, and in LaTeX as a verbatim environment.

You will also note that I coded graphs using a caption-less figure, as in

![](scatter.png){.img-responsive .center-block}

The website uses the Bootstrap framework, and the two classes, img-responsive and center-block ensure that the figure is centered and displays well in devices of varying sizes. One exception is an image used to highlight version 15, where I used an img tag so it appears only in the HTML version. Another is the screen capture of the Stata interface, which I coded so it would appear in natural size in HTML and using the full page width in LaTeX, by coding

<img src="stata15.png" class="img-responsive center-block"/>
\includegraphics[width=\linewidth]{stata15.png}

This takes advantage of the fact that Pandoc will pass along HTML and LaTeX code to the appropriate target format and ignore it otherwise.

Tweaking LaTeX

I used caption-less figures because they appear nicely centered in the output, but unfortunately LaTeX will add a figure number to the otherwise empty caption. This is easily avoided however, using the LaTeX command \usepackage[labelformat=empty]{caption}, which adds the caption package with an option to supress labels. This is the only required tweak, and is easily added as part of the YAML block, but I decided to add a few more and collect them in a file called tweaks.tex. The YAML block used then reads

---
title: Stata Tutorial 
author: Germán Rodríguez
date: July 2017
header-includes:
  - \input{tweaks.tex}
---

If you list the tweaks.tex file you will see that it uses

These are just aesthetic changes that do not affect the content of the tutorial, but allow you to reproduce exactly the published file by simply typing markstat using tutorial, pdf.

Something else you may toy with when generating a PDF document is page breaks. Having looked at the document, however, I decided that the few cases where code or output was split across pages were alright and decided to let them be.

Note. The Stata Tutorial was first published in 2006 and targeted version 9, which makes the current version the 7th edition.