GUI
This page is for the MarkDoc's original GUI that requires a full installation of the third-party software (Pandoc, wkhtmltopdf). MarkDoc also includes a GUI for running it independent of Pandoc, called mini. To lunch the mini dialog box, type:
db mini
Click here to read more about MarkDoc mini GUI
MarkDoc includes a dialog box (GUI), which not only makes working with the package easier, but also shows all of the potential of the package for writing dynamic documents, dynamic presentation slides, and Stata help files and package vignette. To begin using the GUI, type:
. db markdoc
The command will open the GUI, which is divided into three main tabs, demonstrating the three separate engines that are included in MarkDoc package. The tabs are Dynamic Document, Presentation SLide, and Package Vignette.
In contrast to most of the Stata GUIs - which include a main tab and several tabs for options - the tabs in MarkDoc GUI are independent (because the engines are also independent). Therefore, if you wish to create a dynamic presentation slide or Stata help files, you should select the source file and options in the specified tab.
The first tab of the GUI is for creating dynamic documents from a source file, which can be a smcl log-file or a do-file. MarkDoc processes these two source files differently. A smcl log-file will simply be converted to a dynamic document, whereas a do-file will be executed in a new workspace (i.e. the currently loaded data will not be available. You should include all of the code in the do-file) and the results are used to generate a dynamic document. When typing db markdoc, the following window appears:
The default markup is Markdown but you can change that to HTML or LaTeX. The GUI also includes tips. By holding your mouse pointer on an object in the GUI, the tip will appear. For example, if you hold your pointer on the "Markup language", the following box will appear:
The second tab is for creating PDF or HTML-based presentation slides.
While generating HTML-based presentation slides can be attractive for some users, most users probably find the PDF presentation slides more useful and portable. The PDF presentation slides require LaTeX, however, they can be written in Markdown, which makes generating slides much easier. Moreover, MarkDoc includes several options for customizing the PDF slides. All of the Beamers' themes, colors, and fonts, as well as options for specifying the font size of Stata output and also the width and height of the slides can be customized.
NOTE that generating dynamic slides is not yet documented in this manual, nor it is mentioned in the journal article. However the torture tests include a directory called Beamer that has several examples for generating dynamic slides with Markdown and LaTeX. Basically, creating slides is not really different for generating documents (despite the options and the engine), however, you should separate the slides from one another. When writing with Markdown, you can separate the slides by:
- Writing heading 1
- Using a line
---which breaks the slide - Creating a new documentation chunk using "/***" and "***/" signs
The package vignette tab uses ado-file or mata-file and extracts the documentation written in the file to generate a dynamic Stata help file (sthlp) or a package vignette, in any of the supported formats. The documentation can be written in smcl or a combination of smcl and Markdown. The package vignette tab is shown below:
It is recommended to write the documentation in combination of Markdown and smcl, which significantly simplifies writing and editing package documentation. This will ensure that your vignette documents will look as good as your Stata files.
