Updated on 14 July 2014

1. Dyndoc
2. Stata Document
3. Stata Markdown Download
4. Stata 14 Markdown

Quick Tips

1. Dynamic Markdown has been implemented for a number of programming languages, including Stata and R. Within Stata there is a dynamic markdown package called stmd that relies on Stata's dyndoc command, as well as the user-written package markstat. Each has it's strengths and weaknesses.
2. Webdoc is a command to process a do-file that contains Stata commands as well as pieces of HTML or Markdown code. A primary use of webdoc is to produce a HTML document that displays literal Stata output as it is shown in Stata’s Results window. However, webdoc can be seen as a general tool for generating HTML documents that combine text.

Several packages such as MarkDoc, Weaver, and ketchup have been written for Stata to make Markdown codes available for Stata. Markdown provides a simple solution for writing and styling text as well as adding graphs and links to a document. In this document I will introduce you to Markdown and provide several example about how to style text and add graphs using markdown

Introduction

At GitHub, we’re building the text editor we’ve always wanted: hackable to the core, but approachable on the first day without ever touching a config file. We can’t wait to see what you build with it. Markdown is a simple, standardized text-formatting language that you can read about at Wikipedia. You mix Markdown with Stata commands that create the output you want. Think of the file you create as being a do-file on steroids. You then run dyndoc to produce a Word document (.docx) or webpage—an HTML file. May 28, 2020 Markdown. 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.

Markdown is a plain text syntax used for formating text. It was developed in 2004 by John Gruber to simplify HTML writing. In other words, Markdown is a text-to-HTML convertor that converts specific text symbols to XHTML codes. Markdown uses symbols to simplify these tags and as a results, has gained a lot of popularity for writing in blogs, websites, and online forums. In addition, many software have attempt to make use of Markdown codes for writing and styling text.

Writing in HTML format requires using a lot of tags, for example, to write a heading you should place text between <h1> and </h1> below I write a few more examples to give you an idea about writing with HTML codes. In the examples below, the HTML tags are highlighted in blue color and the black color text is the actual text that appear in the document.

Thus, “Markdown” is two things: (1) a plain text formatting syntax; and (2) a software tool, ... that converts the plain text formatting to HTML. The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions. - J. Gruber

But how does Markdown simplify styling text in a plain-text formatted document? Here is an example about writing in HTML format. To give you a taste of writing in HTML format, I will introduce you to introduced the <h1>, <p>, <strong>, and <em> which are used for writing heading 1, paragraph, making the text bold, and italic respectively. Then I will write the same text using markdown codes to make them comparable to one another.

● It is clear that Markdown significantly improve the readability of the document and simplify styling it. If you are interested to learn more about Markdown visit http://daringfireball.net/. You can also practice Markdown syntax in the online Markdown simulator.

Syntax

One reason for popularity of Markdown code is that the syntax codes are only a few which I explain them below. These codes are applicable in Weaver, MarkDoc, and Ketchup packages in Stata.

Phrase Emphasis

Link

In the example above, the 'MyLink' is the hyperlinked text, i.e. the text that appears in the document. The 'optional title' is the title that pops up if you keep your mouse cursor on it for a couple of seconds. Try it by holding your cursor on MyLink for a few seconds.

● Note that there should be no space between the ]( characters.

Dyndoc

Images

Inserting a graph in the document is very similar to creating a link. The difference is that the image begin with !. Similar to the link syntax, there should be no space between the ]( characters. If you don't know the relative source of your graph, you can also use the absolute path to your image. And if you are wondering what do I mean by relative and absolute paths, make sure you read this link carefully!

Also pay attention to the file suffix (in this example, .jpg) that should be specified otherwise, markdown does not recognize the file that you are trying to import. Just to give you an example, I import an image named 'smallheart.jpg' to this page using  because my Stata-Blog website is actually reading Markdown codes. In this example, I have used the absolute path of the file which shows where on the server my graph is. If my graph was in the same folder as my HTML file, then writing  would have been enough. Obviously the relative paths are shorter and easier to write. More importantly, the relative paths are dynamic i.e. if you move the HTML and the image to a different folder (but keep them in the same folder) the graph still appears in your document. If you wish to create this graph yourself, right click and download the graph code here.

Headers and subtitles

The Markdown syntax for adding headings is very simple. Adding the # sign at the beginning of the line creates a heading. The number of hashtags refer to the heading rank which cann vary from 1 to 6. However, each hashtag has to appear at the beginning of the line. Therefore, you cannot write heading 1 and heading 2 on the same line.

Paragraph

Writing a text paragraph is the simplest thing using Markdown because it does not have any syntax. More excitingly, you can always press the enter key and move on to the next line without breaking the paragraph. The enter key does not break the line. To break the line, you should end the line with 2 or more spaces.

Horizontal rules

Adding three or more dashes or asterisks will be converted to a horizontal rule which is defined as <hr /> in HTML.

Exceptions

Adding an indent to a normal Markdown file would be interpreted as a 'code block' in HTML. In Stata, this interpretation has been ignored. Stata packages that can interpret Markdown codes, Ketchup and MarkDoc both ignore this interpretation and remove indents, unless indents are used to style braces, where indents improve readability of the code.

Example

For Stata packages that read Markdown text, the text has to be inserted within comment signs to tell Stata that the text is not meant to be executed. If you want to write only one line of text, the // symbol can be used. For example, you can add a heading 1 text to your document by typing:

However, if you wish to write more thext, the text should be inserted between /* */ signs. Bear in mind that these signs should be placed on separate lines to tell the packages that these are Markdown codes. This is not required by Stata, but the packages. By typing /* and */ on separate lines, Ketchup and MarkDoc make a difference between Markdown codes and comments that are made within Stata codes, using the same symbols. The reason is that these packages automatically remove the /* */ signs, after translating their content to Markdown, which improves the look of the document. However, they preserve and highlight these signs if they appear within the codes and interpret them as comments rather than Markdown codes. Therefore, the correct way of writing is as follows:

Example Template

The example template uses the codes of the graph, 'I Love Stata' and uses both MarkDoc and Ketchup packages to read the codes and export them to docx (for microsoft word) and HTML.

10.1 Introduction

For some Stata documentation, you may want to include portions of Stata's help files.

When I present workshops on Stata programming topics, I often refer to the Help files. I use them constantly myself, and I usually want my audience to learn to do the same.

I can usually just write 'look up command name' or provide a URL. But every once in a while, I want to include something from a Help file in my own writing. Sometimes I want to make a point about how the Help itself is laid out.

10.2 Example - help graph

For example, I recently found myself wanting to discuss some of the many tasks accomplished with Stata's graph command, and it is useful to look at how Stata has grouped these in its own documentation. In Stata, type the command:

What you will see in the Help (below) is that the first group of graph commands draw graphs, that is, they specify how the ink is to go on the page (pixels on the screen), and then carry out that task.

The other graph commands, grouped further down, are utility procedures that mostly manipulate a graph that has been produced. (I have only included part of the Help page here.)

Stata Document

10.3 The R Markdown

There are three steps to this little display:

• a fake call to help graph. This is faked because it is a command Stata would ignore in batch mode.
• a hidden translate command (in Stata). This converts Stata's marked up (SMCL) help into plain text.
• a hidden readLines command (in R). This gives us our 'output' in the document.

Stata Markdown Download

To see the details, see the source.

Stata 14 Markdown

(This page was written using Statamarkdown version 0.5.5.)