mini example
To run this example, copy the code block below in a do-file and save it as example.do. When you saved the file, run the command below in Stata:
. markdoc example.do, mini export(docx) replace
If you are not familiar with markdoc syntax, just use the mini GUI. Type:
. db mini
once the GUI is loaded, browse the do-file, select whatever document format you wish to generate, html, docx, pdf, etc, and boom! That's all!
/***
MarkDoc Mini
============
It is just a tradition to begin with __Hello__ _World_!
This is a new text paragraph. I can also use asterisk instead of
underscore to make the text **bold** or *italic*, but the latter
is not supported in Stata help files (supported in html,docx,pdf).
You can separate your document by adding a horizontal line,
which is shown below. The alternative syntax mentioned in
are also covered:
- - -
How about line-breaks without adding a new paragraph?
In Markdown you can do a line break
by adding 2 or more spaces
at the end of the line
to indicate a line-break
without creating a new paragraph! This means you should pay a
careful attention to the spaces you put in the documentation.
They are very meaningful in Markdown syntax!
Hyperlinks
----------
Visit the [Markdown's developer site](https://daringfireball.net/projects/markdown/dingus)
to make yourself familiar with the Markdown syntax. Unfortunately,
Stata's __putdocx__ and __putpdf__ do not yet support
hyperlinks, but the Stata help files generated by MarkDoc
can show hyperlinks.
Adding Indention
----------------
You can also indent your text as well as do nested indention.
Use the ">" sign at the beginning of the line to indent it.
> this is a Markdown indention
> > this is indention level 2
> > > this is indention level 3
Code lines and code blocks
--------------------------
Code is shown in monospace font in the documents. Usually it
is also styled to make it distinct from the text paragraphs.
If you wish to add a line of code, begin the line with 4:
This is a code! Please **DO NOT** *INTERPRET* Markdown code
This is another code line
If you have a code block of several lines, it is easier to
place it in a code block as shown below. You don't have to
indent the code block with 4 spaces, it's all done
automatically. and of course, you can put a single line of
code in it as well!
~~~
This is a code block! Please **DO NOT** *INTERPRET* Markdown code
This is another code line
~~~
There is no limit on how many paragraphs you can write. Just
keep an empty line between paragraphs or the previous styled
text (header, code block, indented code, horizontal lines, etc.
Adding a list
-------------
making a list is easy. Just begin a line with a number, immediately
followed by a dot. or a dash followed by a space.
Stata's __putdocx__ and __putpdf__ do not support lists yet.
I created a workaround to support Markdown lists
But nested lists are not yet implemented because they look
rather ugly without a decent support of lists in the document...
1. This is a list
2. This is list 2
3. This is list 3
- This is unordered list
- This is also unordered list
Limitations
===========
Some of the Markdown syntax is __NOT__ yet supported by Stata's __putdocx__ or
__putpdf__ commands. These limitations are:
1. Hyperlink
2. Nested lists
3. Mathematical notations
Markdown Tables
===============
> __NOTE__: Markdown tables are not supported in Stata Help files
Markdown also supports tables! Currently 2 table flavors are
recognized, but you can cooperate to increase the supported
tables!
### The recommended format
This is the recommended format, that is also used by the
__tbl__ command for generating dynamic tables (see below)
"Column1"|"Column2"|"Column3"
:--------|:--------:|:--------:
Cat|Soccer|Apple
Dog|Basketball|Orange
Ape|baseball|Banana
You can also style a cell:
"Column1"|"Column2"|"Column3"
:--------|:--------:|:--------:
__Cat__|Soccer|Apple
__Dog__|Basketball|Orange
__Ape__|baseball|Banana
### The alternative format (not recommended)
The alternative format requires more work to create and
adjust. You don't really want to do it manually...
| __Animals__ | __Sports__ | __Fruits__ |
|-------------|------------|------------|
| Cat | Soccer | Apple |
| Dog | Basketball | Orange |
| Ape | baseball | Banana |
Adding a figure with caption
----------------------------
Adding a figure with markdown is simple. if we __assume__ that
you have an image file in your current working directory named
__graph.png__, we can easily include it in the document
using the following syntax:
Next, I will introduce you to other commands that can be used
to generate dynamic tables and include figures.
> of course, Stata help files are unable of rendering image files
Adding a figure dynamically
===========================
***/
// load the image into the document automatically
clear
sysuse auto
histogram price
img, title("Figure 1. say something about this figure")
/***
Adding a dynamic table
===========================
***/
sysuse auto, clear
foreach var of varlist weight price mpg {
summarize `var'
local `var'_mean : display %9.2f r(mean)
local `var'_sd : display %9.2f r(sd)
}
tbl ("Variable Name", "Mean", "SD" \ ///
"__weight__", `weight_mean', `weight_sd' \ ///
"__price__", `price_mean', `price_sd' \ ///
"__mpg__", `mpg_mean', `mpg_sd') ///
, title("Table 1. Summary of __weight__, __price__, and __mpg__ variables")
/***
The tbl command is very powerful and it allows you to take
full control of your table. For example, you can format the
text you wish to show in the cells, using exactly the same syntax
as the __display__ comand in Stata!
***/
summarize price
return list
tbl ("Variable", "Observations", "Mean", "SD" \ ///
"__price__", r(N), %9.2f r(mean), %9.2f r(sd))
/***
Dynamic text
===========================
There are two ways to write dynamic text in MarkDoc
(and MarkDoc _mini_). The first is using the __txt__ command.
This is a powerful command that also allows styling the text.
For example, I use the txt command to create a dynamic Markdown
table below (not recommended, only for demonstration)
***/
local l1 Cat
local l2 Dog
local l3 Soccer
local l4 Basketball
local l5 Apple
local l6 Orange
txt ///
"| __Animals__ | __Sports__ | __Fruits__ |" _n ///
"|-------------|------------|------------|" _n ///
"| `l1' | `l3' | `l5' |" _n ///
"| `l2' | `l4' | `l6' |" _n
/***
I can use the __return list__ command to see what macros are returned by the
`summarize` command. These values will be printed:
***/
summarize price
return list
txt "the mean of Price variable is " r(mean)
txt "the minimum value is " r(min) " and the maximum is " r(max)
/***
Alternative procedure for dynamic text
--------------------------------------
There is, however, a smarter way that can be used when you
execute a do-file in Stata:
***/
scalar a = 10.847958758976
matrix A = (1,2\ 3, 4)
scalar b = A[2,1]
local a = 999
sysuse auto, clear
/***
How about <!a!>?
-----------------
For example, we can show the value of the 10th observation
of the __Price__ variable, which is <!price[10]!>
You can also use this syntax to show a value of a
macro <!`a'!> or Scalar <!b!>, even when they are extracted
from a matrix, e.g. <!A[1,1]!> or <!A[2,2]!>!
***/
