<<dd_version: 2>>
<<dd_include: header.txt >>

# An introduction to using Markdown in Stata

Lauren Samuels, lauren.samuels@vumc.org

26 May 2020

________________________

## Things to include at the top of every file

In general, I would recommend having these things be the first two lines of your file.

### First, specify the minimum required version of dyndoc.

<!---
* The two lines with the <--- etc. indicate the beginning and end of a
*     Markdown comment.
* You don't need to use asterisks once you're inside a comment block,
*	but the Stata do-file editor doesn't recognize the html comment signifiers,
*	so I'm using asterisks inside the comment block to help with highlighting.
* There may be other ways to do this.
--->

<!---
* Following this comment block, the lines with the tildes mean 
*     "print the enclosed text in monospace font."
* The phrases inside the double <>'s are instructions to Stata's markdown
*     processing system (dyndoc).
* We have already run the "dd version command" (see top of file),
*     so I used the "dd_ignore" tags to indicate that I just want to print
*     text showing that line (not actually run it).
--->

~~~~
<<dd_ignore>>
<<dd_version: 2>>
<</dd_ignore>>
~~~~

From the Stata Reporting manual: 

> The **dd version** tag specifies the minimum version required to convert the source file. The version number is independent of Stata's version command... The current version, and the default, is 2, and it is introduced as of the release of Stata 16. The current version number is also stored in c(dyndoc version).

### Then, specify any overall stylistic elements for the report.

~~~~
<<dd_ignore>>
<<dd_include: header.txt >>
<</dd_ignore>>
~~~~

If there are stylistic elements you want to use in all your reports, you might want
to store them in a header file that you can use across projects.

Stata's standard header file can be found at 
http://www.stata-press.com/data/r16/reporting/header.txt.

The header file specifies a particular css (cascading style sheet).

+ Stata's standard css can be found at 
http://www.stata-press.com/data/r16/reporting/stmarkdown.css.

+ If you don't like that one, you can modify it, or you can look for other css's on the web.
There are a lot out there. Here's one website you can try: https://markdowncss.github.io.


________________________

## Now you can continue with the rest of your file

Markdown is designed to be easy to learn and use.
You can find a "cheat sheet" at [Markdown Cheat Sheet](https://www.markdownguide.org/cheat-sheet/), and a more detailed description of the basic syntax and best practices at 
[Basic Syntax](https://www.markdownguide.org/basic-syntax/).

Note that there are several "flavors" of Markdown out there, so if you try something from the Markdown Guide and it doesn't work in Stata, don't give up.
Many of the differences in "flavors" have to do with spaces surrounding symbols and/or blank lines preceding or following text, so fiddling with those things can be helpful if you're having problems.