Skip to content

A literate programming package for Stata which develops dynamic documents, slides, and help files in various formats

Notifications You must be signed in to change notification settings

haghish/markdoc

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Cite 1: Haghish, E. F. (2016). markdoc: Literate programming in Stata. The Stata Journal, 16(4), 964-988.
Cite 2: Haghish, E. F. (2020). Software documentation with markdoc 5.0. The Stata Journal, 20(2), 336-362.

MarkDoc : a general-purpose literate programming package for Stata

MarkDoc is a general-purpose literate programming package for Stata. MarkDoc is very simple and intuitive to use, yet a powerful software for creating dynamic documents interactively in a variety of formats such as sthlp, pdf, docx, tex, html, odt, epub, and markdown. The software has a considerable focus on making literate programming easy-to-learn and practice for newbies. Therefore, it can be taught to undergraduate students in introductory courses to document code and practice statistical reporting. Continue to MarkDoc documentation...


markdoc has a new option - mini - a light-weight program written completely in Stata that allows Generating HTML, Docx, PDF, Presenattion slides, and Stata Help Files (sthlp) without requiring Pandoc and wkhtmltopdf or any third-party software. It also offers a new GUI for the engine (type db mini). Read more about the mini mode here. The mini engine is updated to be compatible with Stata 16!


Once you learn markdoc, you can take care of all types of documents you may wish to create for Stata, simply using Markdown. If you are using markdoc for data analysis, you can write your documentation with Markdown and generate dynamic documents in docx, pdf, or html, without requiring any third-party software. Similarly, if you are a Stata programmer and you wish to write clean and readable documentation that is easy to write and update, you can write your documentation in Markdown and export sthlp Stata Help Files. You can also generate the package documentation in other formats, for example in Markdown to put them on GitHub, or HTML to host them on your private site. The document convertors are completely written in Stata language!

Resources

Manual (Wiki)

MarkDoc package vignette (PDF)

Journal Article

Examples

Torture tests

Need help? Ask your questions on statalist.org

Need more help? Contact the author to plan a workshop in your department or company

1. Installation

markdoc requires a few other Stata packages. The github package can be used to install markdoc and all of its dependencies automatically. Once github is installed, type the following command to install markdoc:

github install haghish/markdoc, stable

NEWS: MarkDoc v. 4.1.0 introduced the mini option to make MarkDoc independent of third-party software that are mentioned below. If you do not wish to install the binaries, Read more about the mini mode...

MarkDoc - if not executed in mini mode - requires 3 third-party software based on the document format you wish to create. These software are:

The pdfLaTeX is optional, but required for generating PDF slides and typesetting documents written in LaTeX. The wkhtmltopdf is only required for generating stylish PDF documents (you can create PDF documents in the mini mode as well). MarkDoc provides optional automatic installation of pandoc and wkhtmltopdf if the install argument is specified. You can read more about the installation in the manual...

1.1 MarkDoc Mini Mode

As noted earlier, a new engine has been developed for MarkDoc, called mini mode, to make the package independent of Pandoc, wkhtmltopdf, and pdfLaTeX. The mini mode is very enabling and offers a wide variety of document formats.

2. Dialog box

To further facilitate using MarkDoc for beginners, a dialog box was written for Stata, which covers all features and most of the important options of MarkDoc. The dialog box supports all three engines of MarkDoc for creating dynamic document, dynamic presentation slides, and package vignette (e.g. Stata help files, package manual, etc).

To use the dialog box, type:

db markdoc

The dialog box is documented in details in the manual. Stata users that are new to MarkDoc are encouraged to have a look at the dialog box to get an idea of what they can do with MarkDoc.

The dialog box mentioned above is for the fully installed MarkDoc, that generates dynamic documents, presentation slides, and package vignettes in various document formats, which require installation of Pandoc and wkhtmltopdf. However, as said earlier, MarkDoc also has a light weight mini mode that allows generating dynamic documents without requiring third-party software. This mode also has its own GUI that makes learning MarkDoc much easier. To run the GUI, type:

db mini

As you see, the mini mode supports producing most of the formats, yet it is all written within Stata!

3. Built-in syntax highlighter

Wish to develop handouts or presentation slides within Stata? MarkDoc has a built-in syntax highlighter for Stata code in HTML, LaTeX, and PDF formats, including presentation slides! You can also add the syntax highlighter to your blog! Read how...

Much effort was put to develop a syntax highlighter for Stata, which was not available before. This just shows how caring MarkDoc is, when it comes to teaching statistics! MarkDoc was intended to be used in daily routine, as early as introductory statistics courses to help students document their code and read it with more care.

Author

E. F. Haghish, Ph.D.
Department of Medical Psychology and Medical Sociology,
University of Göttingen, Germany

http://www.haghish.com/contact.php
@Haghish

About

A literate programming package for Stata which develops dynamic documents, slides, and help files in various formats

Resources

Stars

Watchers

Forks

Packages

No packages published