mini

The mini option is meant to make MarkDoc package easier to use on computers that have restrictions with running binaries downloaded from the web. Many laptops provided by universities have this restrictions and I have had a lot of trouble whenever I was teaching MarkDoc in a university course... But this problem is solved now! The mini option makes MarkDoc independent of any third-party software, such as Pandoc, wkhtmltopdf, or LaTeX. It is called mini, because, it is rather a minimal version of MarkDoc. Yet, It can do amazing things which are not available in any Stata package elsewhere.

MarkDoc runs on Stata 12 forth. However, the mini mode requires Stata 15 or higher. Other users who wish to generate dynamic documents with MarkDoc on lower versions of Stata can still use the package with the installed binaries (read the Installation page in the manual or the manuscript published at Stata Journal for more information)

MarkDoc Mini GUI

To make working in Mini mode easier, I created a GUI that can be executed by typing:

db mini

That simple! Just upon installing the Stata package, and without any further installation of any software, you can generate documents in various formats.

Syntax

The mini mode is just an option that you should add to markdoc command. For example, if you would like to execute a do-file, test its reproducibility, and generate a dynamic document accordingly within the mini mode, just add the mini as an option. For example, if you are generating a Microsoft Word docx file, type:

markdoc filename, mini export(docx) 

The supported document formats in mini mode are:

• md (plain text Markdown)
• html document along with all features that were supported before (Complete Syntax highlighter, document layout, etc)
• docx document along with basic syntax highlighter, separating Stata commands from output results
• pdf document along with basic syntax highlighter, separating Stata commands from output results
• sthlp which is the Stata Help file format. Programmers can make use of MarkDoc to write their program documentation with Markdown and export sthlp help files within MarkDoc package

Supported source files

MarkDoc is a general purpose software:

1. It produces dynamic documents in various formats from Stata do-files and examines their reproducibility. this is the recommended way for generating dynamic analysis documents with MarkDoc, although smcl-log files can also be used to create documents in various formats
2. Translates smcl log-file into any of the supported documents (docx, pdf, html, md, ...)
3. It includes a Markdown to SMCL translator that converts Markdown documentation to Stata help-files. Therefore, programmers can write the documentation of their programs in Markdown and generate Stata help-files easily
4. It produces presentation slides

The mini mode supports all of these functionalities apart from the presentation slides, which requires a LaTeX distribution on the machine. In other words, most of the functionalities of the original package is covered in the new lightweight mode.

Remarks

Stata 15 introduced two commands, putdocx and putpdf for creating Microsoft Word and PDF documents within Stata. That was very exciting news but as I started working with them, I realized that these commands are not well-developed yet, particularly the putpdf that only supports a subset of putdocx's syntax. Yet, it is a major step ahead and I am sure we will see much improvement in the next versions of Stata for these commands. Long story short, if you wish to get a full advantage of MarkDoc styling capabilities, install the required software. But if you are happy with working with a light-weight format and do not wish to heavily style your documents, you're good to go with the mini mode.

Markdown Syntax

There are so many flavors of Markdown available. In the MarkDoc Mini mode, I stick with the original syntax of Markdown that is interpenetrate in all flavors. You can read about Markdown project on its developer's website.... Almost all of the original syntax is covered. Those which are not covered are mentioned below:

Supported Syntax

• Markdown Headers
• paragraph indention and nested intentions
• Markdown basic text styles such as:
  • bold
  • italic
  • bold & italic
  • hyperlink
  • line break.
• ordered and un-ordered lists are supported
• code lines with 4 spaces are supported
• code blocks using ~~~ syntax are supported
• markdown tables
• adding dynamic text with the txt command is fully supported
• adding an image with Markdown syntax is supported. The img command is fully supported
• adding a dynamic table with the tbl command is fully supported

Unsupported Syntax

1. Stata 15 does not support hyperlink in putdocx and putpdf commands... However hyperlinks are supported in sthlp format
2. nested lists (2 level or more) are not yet supported because putdocx and putpdf in Stata 15 are not supporting nested lists.
3. putdocx and putpdf do not support Mathematical notations

Example

The supported syntax as well as all the fun things you can do in the mini mode is shown in this example. The easiest way to run the example is using the mini GUI, just type db mini and begin using MarkDoc!