Skip to content

mini

Jump to bottom
E. F. Haghish edited this page Nov 23, 2018 · 27 revisions

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 course in the universities... 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)

Remarks

1- The mini mode assumes that you have written your documentation with Markdown. If you wish to write your documentation with HTML or LaTeX (which most of you don't), read the Installation page and install the full MarkDoc. The mini mode only supports Markdown documentation syntax.

If so, it allows you to create a document in the following formats:

  • 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

However the Stata 15 features yet do not allow taking full benefit of Markdown syntax. Therefore, some of the features are not yet supported. See the table below to see which Markdown syntax is supported in the minimode.

Supported 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, monospace font, hyperlink, line break. However, using grave accents for making the font monospace is not recommended.
  • ordered and un-ordered lists are supported
  • code lines with 4 spaces are supported
  • code blocks using ~~~ syntax are supported
  • 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 horizontal line syntax
  4. putdocx and putpdf do not support Mathematical notations
  5. General Markdown tables are not supported yet. Only Markdown tables generated by the tbl command are recognized. this is were your help is needed! fork the repository and help improving this feature!
  6. If you generate sthlp document, do not use * for making the text bold or italic. Instead use underscore.

MarkDoc logo

Clone this wiki locally