help webdocJump to: Syntax, Description, Options, Examples, Remarks, Stored results
Also see: http://repec.sowi.unibe.ch/stata/webdoc

Title

webdoc -- Create a HTML or Markdown document including Stata output

Syntax

Process a do-file containing webdoc commands

webdoc do filename [arguments] [, do_options ]

Commands to be used within the do-file

webdoc init [docname] [, init_options] initialize
the HTML or Markdown output document; (re)set default behavior

/*** ... ***/ add a block of text

webdoc substitute [from to ...] [, add] substitutions to be applied within /*** ***/ blocks

webdoc write ... write a line of text (excluding new-line character)

webdoc put ... write a line of text (including new-line character)

webdoc append filename [, append_opts] add the contents of a file

webdoc toc [levels] [offset] [, ...] add
a table of contents

webdoc stlog [name] [, stlog_options] start
a Stata log

webdoc stlog oom cmdline suppress output of cmdline and insert an output-omitted tag

webdoc stlog quietly cmdline suppress output without inserting an output-omitted tag

webdoc stlog cnp insert a page break in the Stata log

webdoc stlog close stop the Stata log

webdoc stlog [name] using dofile [, ...] include a log from the commands in dofile

webdoc stlog [name] [, ...] : command include the output from command

webdoc local name definition define and backup a local macro

webdoc graph [name] [, graph_options] include a graph

webdoc close close the output document

// webdoc exit let webdoc do exit the do-file

Advanced: change HTML tag settings

webdoc set [setname [definition]]]

Remove all webdoc commands from a do-file

webdoc strip filename newname [, replace append ]

do_options Description

[no]init[(docname)] initialize the
HTML or Markdown output document

init_options options to be passed through
to webdoc init

nostop do not stop execution on error (not recommended)

cd process the do-file within its home directory

init_options Description

Main
replace allow overwriting an existing output document

append append output to an existing output document

md use .md instead of .html as default suffix for the
output document

header[(header_opts)] create
a standalone HTML document including a header and a footer

Log and graph options
[no]logall whether to log all Stata output;
the default is nologall

stlog_options options to be passed
through to webdoc stlog

gropts(graph_options) options
to be passed through to webdoc graph

Filenames/paths
[no]logdir[(path)] where to store the
Stata log files

grdir(path) where to store the graph files

dodir(path) where to store the optional do-files

[no]prefix[(prefix)] prefix for the automatic
names

[no]stpath[(path)] include-path to be used
in the output document

header_options Description

Main
width(width) set maximum width of the page

nofooter omit the footer

Meta data
title(str) provide a title for the meta data; default is the
name of the document

athor(str) provide author information for the meta data

date(str) provide a date for the meta data

description(str) provide a description for the meta data

keywords(str) provide a (comma separated) list of keywords for
the meta data

language(str) specify the language of the document; default is
en

charset(str) specify the character encoding of the document;
default is utf-8

Stylesheets
bstheme[(spec)] include
a theme from bootswatch.com

include(filename) include the contents of filename in the
header

stscheme(stscheme_opts) specify
the look of Stata output

stscheme_options Description

Stata scheme
standard use scheme "Standard"

studio use scheme "Studio"

classic use scheme "Classic"

desert use scheme "Desert"

mountain use scheme "Mountain"

ocean use scheme "Ocean"

simple use scheme "Simple"

Manual settings
bg(color) specify background color

fg(color) specify foreground color (standard text)

rfg(color) specify color for results

cfg(color) specify color for input (commands)

rbf use bold font for results

cbf use bold font for input (commands)

lcom italicize/shade comments in Stata output

append_options Description

substitute(subst) apply substitutions; subst is from to [from to ...]

drop(numlist) omit the specified lines

toc_options Description

numbered add section numbers

md also look for Markdown headings

stlog_options Description

Main
linesize(#) set the line width to be used in the output log
(number of characters)

[no]do whether to run the Stata commands; default is do

[no]log whether to create a log and include it in the
output document; default is log

[no]cmdlog whether to display the code
instead of an output log; default is nocmdlog

[no]dosave whether to store a copy of the commands
in a do-file; default is nodosave

Contents
[no]output whether to suppress output; default is
output

[no]matastrip whether to strip Mata opening and ending
commands; default is nomatastrip

[no]cmdstrip whether to strip command lines; default
is nocmdstrip

[no]lbstrip whether to strip line break
comments; default is nolbstrip

[no]gtstrip whether to strip continuation
symbols; default is nogtstrip

[no]ltrim whether to remove indentation; default is ltrim

Highlighting
mark(strlist) apply <mark> tag to specified strings

tag(matchlist) apply custom tags to specified strings

Technical
[no]plain whether to omit markup; default is noplain

[no]raw whether to omit markup and character
substitutions; default is noraw

[no]custom whether to use custom code to include the log
file; default is nocustom

[no]keep whether to erase the external log file;
default is keep

[no]certify whether to compare results against previous
version; default is nocertify

[no]sthlp[(spec)] (webdoc stlog using
only) whether to treat as a Stata help file

nostop (webdoc stlog using only) do not stop execution on error

graph_options Description

Main
as(fileformats) output format(s); default is as(png)

name(name) name of graph window to be exported

override_options override conversion defaults; see help
graph export

Attributes
alt(string) provide an alternative text for the image; default is
the graph name

title(string) provide a "tooltip" title for the image

attributes(args) further attributes to be passed through to the
<img> tag

Environment
[no]link[(fileformat)] whether to add a link to the
graph file; default is link (unless hardcode is specified)

[no]figure[(id)] whether to use the
figure tag; default is figure

caption(string) provide a caption for the figure

cabove or cbelow where to place the caption; default is
cbelow

Technical
[no]hardcode whether to embed the graph in the output
document (PNG, GIF, JPEG, and SVG only); default is nohardcode

[no]keep whether to erase the external graph file
if hardcode is specified; default is keep

[no]custom whether to use custom code to include the
graph; default is nocustom

Description

webdoc provides tools to create a HTML or Markdown document from
within Stata in a weaving fashion (also see
Jann 2015). The
basic procedure is to write a do-file including Stata commands and sections
of HTML or Markdown code and then process the do-file by webdoc do.
webdoc do will create the output document, possibly including graphs
and sections of Stata output. webdoc do is similar to the regular
do command; arguments, if specified, will be passed to the do-file
as local macros; see [R] do.

Within the do-file, use webdoc init docname to
initialize the output document, where docname is the name
document (possibly including a path; depending on option md,
default suffix ".html" or ".md" will be added to docname if no suffix
is specified). Alternatively, if the do-file does
not contain a webdoc init docname command, webdoc do will
automatically initialize the document in the folder of the do-file
using basename.html or basename.md as name for the
document, where basename is the name of the do-file without
suffix. Furthermore, webdoc init without docname can
be used within the do-file to change settings after the document has been
initialized.

Thereafter, use the /*** ***/ delimiter structure to include blocks
of HTML or Markdown text. A block may span multiple lines. The opening tag
(/***) must be at the beginning of a line (save white space); the
closing tag (***/) must be at the end of a line (save white space).
Macros in the text provided within /*** ***/ will not be expanded.
You can, however, use the webdoc substitute command to define text
substitutions that will be applied (see
webdoc substitute under
Remarks below; furthermore, also see the remark
on webdoc local).

A single line of HTML/Markdown can also be provided by the
webdoc write command or the webdoc put command.
webdoc put includes a new-line character at the end of the line;
webdoc write omits the new-line character, so that more text can be
added to the same line later on. Stata macros in the provided text will be
expanded before writing the line to the output document. Furthermore, to
copy text from an external file into the output document, you can use the
webdoc append command.

The webdoc toc command creates a table of contents (TOC)
from the HTML or Markdown headings in the document. The TOC will be inserted
at the position where webdoc toc appears; only headings provided in
subsequent /*** ***/ blocks will be included in the TOC. Argument levels
specifies the desired number of levels to be considered. For example
webdoc toc 3 will create a table of contents with three levels from <h1>
to <h3>. Furthermore, the offset argument shifts the highest level
to be taken into account. For example, webdoc toc 3 1 will
use <h2>, <h3>, and <h4> or webdoc toc 2 4 will use
<h5> and <h6>. offset must be an integer between 0 and 5;
the default is 0. levels must be an integer between 1 and 6-offset;
the default is 3. To add section numbers to the headings specify the
numbered option; to look for Markdown headings (lines starting with
#, ##, etc.) in addition to HTML headings, specify the md
option. In HTML headings, an id can be provided using the id
attribute, as in <h3 id="myid">. webdoc toc will then
use myid to refer to the heading. If no id is specified, webdoc toc
makes up an own id.

To create a section containing Stata output, use the webdoc stlog
command. webdoc stlog writes the Stata output to a
log file and then copies the contents of the log file to the
output document. webdoc stlog creates an automatic name for the
output file, but you can also specify a custom name typing
webdoc stlog name (possibly including a relative
path).

Within a Stata output section
webdoc stlog oom cmdline can be used to suppress the
output of a specific command and add an output-omitted note in the
Stata output file. Alternatively, to suppress output without
adding an output-omitted tag, type
webdoc stlog quietly cmdline . Furthermore,
webdoc stlog cnp can be used to insert a page break within a Stata
output section.

webdoc stlog close marks the end of a Stata output section. To
include the Stata output from an external do-file, use
webdoc stlog using filename
where filename is the name of the do-file. Furthermore, to include
just the output of a single command (without input), you can type
webdoc stlog : command. webdoc stlog close is not needed
after the using-form or the colon-form of webdoc stlog.

Instead of selecting the Stata output to be included in the document
using webdoc stlog, you can also specify the logall option with
webdoc do or webdoc init. In this case, all Stata output will be
included in the document.

webdoc local can be used within or after a Stata output section to define a local
macro that will be backed up on disk. This is useful if you want include
specific results in your text and want to ensure that the results will be available
in later runs when suppressing the Stata commands using the nodo
option. The syntax of webdoc local is the same as the syntax of
Stata's regular local command. Local macros defined by
webdoc local will be expanded in subsequent /*** ***/
blocks (up until the next webdoc stlog command). For further
information, see webdoc local under
Remarks below.

webdoc graph exports the current graph and includes
appropriate code in the output document to display graph. webdoc graph
can be specified within a webdoc stlog section or directly after
webdoc stlog close. If webdoc graph is specified within a
webdoc stlog section, the graph is included in the document
before the Stata output; if webdoc graph is specified after
webdoc stlog close, the graph is included after the Stata output
(furthermore, if webdoc graph is used outside a webdoc stlog
section while logall is on, the graph will be placed at the
position in the output where the webdoc graph command occurs). Unless
a custom name is specified, the name of the webdoc stlog section is used
to name the graph (possibly suffixed by a counter if the webdoc stlog
section contains more than one webdoc graph command).

webdoc close closes the HTML/Markdown document. This is not
strictly needed as webdoc do closes the document automatically
if the do-file does not contain a webdoc close command. Furthermore,
to exit a do-file before the end of the file, add a line
containing // webdoc exit (without anything else on the same line).
webdoc do will only read the do-file up to this line.

webdoc uses a specific set of HTML tags to include and format the
Stata outputs and graphs. The definitions of these tags can be changed
within the do-file by the webdoc set command. For details,
see Changing the HTML settings under
Remarks below. Specifying webdoc set
without argument restores the default settings.

webdoc strip removes all webdoc commands and all
/*** ***/ blocks from a do-file.

Options

Options for webdoc do
Options for webdoc init
Options for webdoc append
Options for webdoc toc
Options for webdoc stlog
Options for webdoc graph
Options for webdoc strip

Options for webdoc do

[no]init[(docname)] specifies whether and how
to initialize the output document. If the processed do-file contains an
initialization command (i.e. if the do-file contains
webdoc init docname) or if the document is already open
(e.g. in a nested application of webdoc do), the default for
webdoc do is not to initialize the document. Otherwise,
webdoc do will automatically initialize the output document in the
folder of the do-file using name basename.html (or, if option md
is specified, basename.md), where basename is the
name of the do-file without suffix. Use the init option to override
these defaults: noinit will
deactivate automatic initialization; init will enforce automatic
initialization; init(docname) will enforce initialization
using docname as name for the document (docname may include
an absolute or relative path; the base folder is the current working
directory or the folder of the do-file, depending on whether option
cd is specified).

init_options are options to specify defaults
to be passed through to webdoc init. See below.

nostop allows continuing execution even if an error occurs. Use the
nostop option if you want to make sure that webdoc do runs the
do-file all the way to the end even if some of the commands return error.
Usage of this option is not recommended. Use the nostop option with
webdoc stlog using if you want to log output from a command that
returns error.

cd changes the working directory to the directory of the specified
do-file for processing the do-file and restores the current working directory
after termination. The default is not to change the working directory.

Options for webdoc init

Main

replace allows overwriting an existing output document.

append appends results to an existing output document.

md specifies that ".md" instead of ".html" is to be used as default
suffix for the output document.

header[(header_opts)] causes a HTML header (and a footer)
to be added to the output document. header_opts are as follows.

width(width) sets the maximum width of the HTML page, where width
is a width specification in
CSS units,
such as 800px or 50em. If you use the bstheme() option,
an alternative approach is to include the body of your page in a container,
e.g. type <div class="container-fluid" style="max-width:800px"> on
the first line and </div> on the last line.

nofooter omits the footer. This is useful if you want to append
more material to the same document later on.

title(str) provides a title for the meta data of the page. The default is to
use the name of the document as title.

author(str), date(str), description(str), and
keywords(str) provide author information, a date, a description and a
(comma separated) list of keywords to be included in the meta data of the page.

language(str) specifies the language of the document, where str
is a
HTML language
specification. The default is language(en).

charset(str) specifies the character encoding of the document, where
str is a HTML charset
specification. The default depends on the Stata version. If you use Stata 13 or
older, the default is charset(iso-8859-1) (Windows, Unix) or
charset(mac) (MacOSX). If you use Stata 14 or newer, the default is
charset(utf-8).

bstheme[(spec)] includes a
Bootstrap CSS file in the
header. spec is

[theme] [, jscript selfcontained ]

where theme is either equal to default (for the default
Bootstrap CSS) or equal to the name (in lowercase letters) of a
Bootswatch theme (such as cerulean,
cosmo, simplex, united, etc.; see
bootswatch.com or
www.bootstrapcdn.com/bootswatch
for the list of available themes). If theme is omitted, the default
Bootstrap CSS is used. In addition to the Bootstrap CSS, webdoc will
append a few additional CSS definitions to sightly modify the display of
images and code. Furthermore, if you use the bstheme() option, you
should consider specifying a maximum page width using the width()
option or including the body of your page in a container, e.g. typing
<div class="container-fluid" style="max-width:800px"> on the first
line and </div> on the last line. In general, for more information on
Bootstrap, see getbootstrap.com.

By default, webdoc does not load Bootstrap's JavaScript plugins.
Specify suboption jscript if you want to use Bootstrap elements that
require JavaScript. webdoc will then add code at the end of the
document to load the relevant plugins (also see
getbootstrap.com/getting-started/#template).

Unless suboption selfcontained is specified, webdoc includes
the Bootstrap CSS and JavaScript plugins using links pointing to the minified
files at bootstrapcdn.com. Specify
selfcontained to copy the (non-minified versions of
the) files into you document (this will increase the file size of your
document by about 150 KB or, if jscript is specified, by about
500 KB). For larger projects it may make sense to provide a copy of the CSS
and JavaScript files at your website and include them in your HTML pages
using local links.

If the bstheme option is omitted, a minimum set of CSS definitions
resulting in a plain look will be included in the header of the document.

include(filename) adds the contents of filename the the HTML
header. The contents of filename will be included within the
<head> tag after the definitions requested by the bstheme()
option.

stscheme(stscheme_options) specifies the look of the Stata
output sections. This has only an effect on sections containing
Stata output, but not on sections containing Stata code. That is, sections
created by the cmdlog option (see below) will not be
affected by stscheme(). Note that, currently, webdoc does not
tag errors and links in the Stata logs, so that these elements will appear
as regular output. stscheme_options are as follows.

standard, studio, classic, desert, mountain,
ocean, or simple select one of Stata's built-in color
schemes (see the preferences dialog of Stata's Results window; you can
right-click on the Results window to open the dialog).

bg(color), fg(color), rfg(color), cfg(color), rbf, and
cbf affect the appearance of the different elements in the
Stata output, where color is a
CSS color
specification. These options override the corresponding settings from the built-in
schemes. bg() specifies the background color, fg()
the default foreground color (i.e. the color of standard output),
rfg() the color of results (typically the numbers in the output), and
cfg() the color of input (the commands). Furthermore, use rbf and
cbf to request bold font for results and input/commands, respectively.

lcom italicizes and shades comments in the Stata output.

Log and graph options

[no]logall specifies whether to include the output of all Stata
commands in the output document. The default is nologall, that is, to
include only the output selected by webdoc stlog. Specify
logall if you want to log all output. When logall
is specified, webdoc do will insert appropriate webdoc stlog
and webdoc stlog close commands automatically at each
/*** ***/ block and each webdoc command (but not at
webdoc stlog oom and webdoc stlog cnp). Empty lines (or lines
that only contain white space) at the beginning and end of each
section of commands will be omitted.

stlog_options are options to set the default
behavior of webdoc stlog. See below.

gropts(graph_options)
specifies default options to be passed through to webdoc graph. See
below. Updating gropts() in repeated calls to webdoc init will
replace the option as a whole.

Filenames/paths

[no]logdir[(path)] specifies where to store
the Stata output log files. The default is nologdir, in which case
the log files are stored in the same directory as the output document, using
the name of the output document as a prefix for the names of the log files;
also see the prefix() option. Option logdir without argument
causes the log files to be stored in a subdirectory with the same name as
the output document. Option logdir(path) causes the log files to be
stored in subdirectory path, where path is a relative path starting
from the folder of the output document.

grdir(path) specifies an alternative subdirectory to be used by
webdoc graph for storing the graph files, where path is a relative
path starting from the folder of the output document. The default is to
store the graphs in the same directory as the log files.

dodir(path) specifies an alternative subdirectory to be used by
webdoc stlog for storing the do-files requested by the dosave
option (see below), where path is a relative path starting from the
folder of the output document. The default is to store the do-files
in the same directory as the log files.

[no]prefix[(prefix)] specifies a prefix for
the automatic names of the Stata output log files and graphs. The names are
constructed as "prefix#", where # is a counter (i.e., 1,
2, 3, etc.). Option noprefix omits the prefix; option
prefix without argument causes "basename_" to be used as
prefix, where basename is the name of the output document (without
path); option prefix(prefix) causes prefix to be used as prefix.
The default prefix is empty if logdir or logdir(path) is
specified; otherwise the default prefix is equal to "basename_"
(note that reinitializing logdir may reset the prefix).
Furthermore, the prefix will be ignored if a custom name is provided
when calling webdoc stlog. The suffix of the physical log files on
disk is always ".log".

[no]stpath[(path)] specifies how the path for
linking files in the output document is to be constructed
(stpath() has no effect on where the log files and graphs are stored
in the file system). If stpath is specified without argument, then
the path of the output document (to be precise, the path specified
in docname when initializing the output document) is added to
the include-path. Alternatively, specify stpath(path) to add a custom
path. The default is nostpath.

Options for webdoc append

substitute(subst) causes the specified substitutions to be applied
before copying the file into the output document, where subst is

from to [from to ...]

All occurrences of from will be replaced by to. Include from
and to in double quotes if they contain spaces. For example, to
replace "@title" by "My Title" and "@author" by
"My Name", you could type
substitute(@title "My Title" @author "My Name").

drop(numlist) causes the specified lines to be omitted when
copying the file.

Options for webdoc toc

numbered causes section numbers be added to the headings and
the entries in table of contents. The numbers added to the headings will
be tagged by <span class="heading-secnum">; the numbers in the
table of contents will be tagged by <span class="toc-secnum">.

md specifies that Markdown headings are to be taken into account. By
default, only HTML headings, that is, lines starting with <h1> to
<h6>, are collected. If md is specified, lines starting with
# to ###### are also treated as headings. In any case, a
heading will only be detected if the heading tag is at the beginning of the
line (save white space in case of HTML tags). To construct the entry in the
table of contents, only the text that follows on the same line will be used.

Options for webdoc stlog

Main

linesize(#) sets the line width (number of characters) to be used
in the output log. # must be an integer between between 40 and 255. The
default is to use the current set linesize setting.

[no]do specifies whether to run the Stata commands. The
default is do, i.e. to run the commands. Type nodo to skip
the commands and not write a new log file. nodo is useful if the
Stata commands have been run before and did not change. For example, specify
nodo if all Stata output sections are complete and you want to work
on the text without having to re-run the Stata commands. Note that the
automatic names of Stata output sections change
if the order of Stata output sections changes. That is, nodo should only be
used as long as the order did not change or if fixed names were assigned
to the Stata output sections. An exception is if nodo is used together with
the cmdlog option (see below). In this case the log file
will always be recreated (as running the commands is not necessary to
recreate the log file).

[no]log specifies whether the Stata output is to be logged and
included in the output document. The default is log, i.e. to log and
include the Stata output. If you type nolog, the commands will be run
without logging. nolog does not appear to be particularly useful as
you could simply include the corresponding Stata commands in the do-file
without using webdoc stlog. However, nolog may be helpful in
combination with the nodo option. It provides a way to include
unlogged commands in the do-file that will not be executed if
nodo is specified. Furthermore, nolog can be
used to deselect output if the logall option has been specified.

[no]cmdlog specifies whether to print a plain copy of the Stata
code instead of using a Stata output log. The default is nocmdlog,
i.e. to include a Stata output log. If you type cmdlog then only a
copy of the commands without output will be included (note that the
commands will still be executed; add the nodo option if you want to
skip running the commands). cmdlog is similar to nooutput (see
below). A difference is that nooutput prints ". " at the beginning of
each command, whereas cmdlog displays a plain copy of the commands.
Furthermore, <pre id="id" class="stcmd"><code> will be
used to start a cmdlog section in the HTML file, whereas other Stata
output sections will be started by
<pre id="id" class="stlog"><samp>. Note that
cmdlog can be combined with nodo to include a copy of the
commands without executing the commands. cmdlog is not allowed with
the colon-form of webdoc stlog.

[no]dosave specifies whether to store a copy of the commands
in an external do-file. The default is nodosave, i.e. not to store a
do-file. The name of the Stata output section is used as name for the
do-file (with suffix ".do"). The do-files will be stored in the same location
as the log files, unless an alternative location is specified using the
dodir() option. All webdoc commands will be stripped from
the do-file.

Contents

[no]output specifies whether to suppress command output in the
log. The default is output, i.e. to display the output. If
nooutput is specified, set output inform is applied before
running the commands and, after closing the log, set output proc is
applied to turn output back on (see set output). nooutput has no
effect if cmdlog is specified. Furthermore, nooutput has no
effect if specified with the using-form or the colon-form of webdoc stlog.

[no]matastrip specifies whether to strip Mata opening and ending
commands from the Stata output. The default is nomatastrip,
i.e. to retain the Mata opening and ending commands. If you type
matastrip, the mata or mata: command invoking Mata
and the subsequent end command exiting Mata will be removed
from the log. matastrip only has an effect if the Mata opening
command is on the first line of the output section.

[no]cmdstrip specifies whether to strip command lines (input) from the
Stata output. The default is nocmdstrip, i.e. to retain the
command lines. Specify cmdstrip to delete the command lines. Specifically,
all lines starting with ". " (or ": " in Mata) and subsequent lines
starting with "> " will be removed. cmdstrip has no effect if
cmdlog is specified.

[no]lbstrip specifies whether to strip line break comments
from command lines in the Stata output. The default is
nolbstrip, i.e. not to strip the line break comments. Specify
lbstrip to delete the line break comments. Specifically, " ///..." at the
end of command lines will be removed.

[no]gtstrip specifies whether to strip continuation symbols
from command lines in the Stata output. The default is nogtstrip,
i.e. not to strip the continuation symbols. Specify gtstrip to delete
the continuation symbols. Specifically, "> " at the beginning of
broken command lines will be replaced by white space. gtstrip has
no effect if cmdlog is specified.

[no]ltrim specifies whether to remove indentation of
commands (i.e. whether to remove white space on the left of
commands) before running the commands and creating the log. The default
is ltrim, that is, to remove indentation. The amount of white space
to be removed is determined by the minimum indentation in the block of
commands. ltrim has no effect on commands
called from an external do-file by webdoc stlog using.

Highlighting

mark(strlist) applies the <mark> tag to all occurrences of the
specified strings, where strlist is

string [string ...]

Enclose string in double quotes if it contains blanks; use compound
double quotes if string contains double quotes.

tag(matchlist) applies custom tags to all occurrences of the
specified strings, where matchlist is

strlist = begin end [ strlist = begin end ... ]

and strlist is

string [string ...]

strlist specifies the strings to be tagged, begin specifies the
start tag, end specifies the end tag. Enclose an element in double
quotes if it contains blanks; use compound double quotes if the element
contains double quotes.

Technical

[no]plain specifies whether to omit markup in the log
file. The default is noplain, that is, to annotate the log file with
HTML tags. In particular, input (commands) will be tagged using
<span class="stinp">, results will be tagged using
<span class="stres">, and comments will be tagged using
<span class="stcmt"> (if cmdlog is specified, only
comments will be tagged). Specify plain to omit the HTML tags.

[no]raw specifies whether to omit markup in the log
file and retain special characters. The default is noraw, that is,
to annotate the log file with HTML tags (see the plain option
above) and to replace characters "<", ">", and "&" by their HTML equivalents
"&lt;", "&gt;", and "&amp;". Specify raw to omit the HTML tags and
retain the special characters.

[no]custom specifies whether to use custom code to include the log
file in the output document. The default is nocustom, i.e. to use
standard code to include the log. Specify custom if you want to skip
the standard code and take care of including the log yourself.

[no]keep specifies whether the external log file will be
kept. The default is keep, i.e. to keep the log file so that
nodo can be applied later on. Type nokeep if you want to erase
the external log file.

[no]certify specifies whether to compare the current results
to the previous version of the log file (if a previous version exists). The
default is nocertify. Specify certify if you want to confirm
that the output did not change. In case of a difference, webdoc will
stop execution and display an error message. certify has no effect if
nolog or cmdlog is specified or if a help file is processed
(see the sthlp option below).

[no]sthlp[(spec)] specifies whether to treat
the provided file as a Stata help file. This is only allowed with
webdoc stlog using. By default, files with a .hlp or
.sthlp suffix are treated as help files; all other files are treated
as do-files. Type nosthlp or sthlp to override these
defaults. Files treated as help files are translated by undocumented
log webhtml (or, if plain or raw is specified, by
translate with the smcl2log translator) and are not submitted
to Stata for execution. Unless plain or raw is specified,
text markup and help links are preserved. Internal help links (i.e. links
pointing to the processed help file) will be converted to appropriate
internal links in the output document; other help links will be converted
to links pointing to the corresponding help file at
www.stata.com. In addition, you may provide
a custom list of substitutions in sthlp(spec), where spec is

[from to [from to ...]] [, noid ]

The custom substitutions will be applied before converting the internal links
and the stata.com links (unless plain or raw is specified, in which
case no substitutions will be applied). The help links written by log webhtml are
constructed as <a href="/help.cgi?...">. Hence, you could,
for example, type sthlp(/help.cgi?mycommand mycommand.html) convert
the help links for mycommand to links pointing to the local
page mycommand.html. Suboption noid requests that no log-id
be included in internal links. The default is to include a log-id to prevent
name conflicts.

Options nolog, cmdlog, and dosave are not allowed
in help-file mode. Furthermore, contents options such as nooutput,
cmdstrip, or matastrip will have no effect. However, you may use
nodo to prevent re-processing the help file or custom to use custom
inclusion code. By default, the included help file will be wrapped by
a <pre class="sthlp"> tag.

nostop allows continuing execution even if an error occurs. Use the
nostop option if you want to log output from a command that returns
error. The nostop option is only allowed with webdoc stlog using.

Options for webdoc graph

Main

as(fileformats) sets the output format(s). The default is
as(png). See help graph export for available formats. Multiple
formats may be specified, e.g. as(png pdf), in which case
webdoc graph will create multiple graph files. The first format will
be used for the image in the output document.

name(name) specifies the name of the graph window to be
exported. The default is to export the topmost graph.

override_options are format-dependent options to modify how the
graph is converted. See help graph export for details. For
PNG, TIFF, GIF, and JPG, a default graph width of 500 pixels is used, unless
width() or height() is specified.

Attributes

alt(string) provides an alternative text for the image to be added
to the <img> tag using the alt attribute. The default is to use the
name of the graph as alternative text. The alt() option has no effect
if embedding an SVG using the hardcode option.

title(string) provides a "tooltip" title for the image to be added to
the <img> tag using the title attribute.

attributes(args) provides further attribute definitions to be added
to the <img> tag. For example, to set the display width of the graph to
50%, type attributes(width="50%").

Environment

[no]link[(fileformat)] specifies whether to
add a link to the image pointing to the graph file. Clicking the image in
the browser will then open the graph file. The default is link,
i.e. to add a link, unless hardcode is specified, in which case
nolink is the default. Argument fileformat may be used to select
the file for the link if multiple output formats have been requested by
the at() option. For example, specifying link(pdf) together with
as(svg pdf) will display the SVG image and use the PDF for the
link. The default is to use the first format for both the image and the link.

[no]figure[(id)] specifies whether to enclose
the image in a <figure> environment. The default is figure,
i.e. to use the figure tag. Type nofigure to omit the figure tag. To
add a custom ID to the figure tag, type figure(id). If id
is omitted, webdoc will ad an automatic ID (constructed as fig-name,
where name is the base name of the graph).

caption(string) provides a caption for the figure using the
<figcaption> tag.

cabove or cbelow specify whether the caption is added
above or below the figure. Only one of cabove and cbelow is
allowed. cbelow is the default.

Technical

[no]hardcode specifies whether to embed the graph source in the
output document. This is only supported for PNG, GIF, JPEG, and SVG. In case of
PNG, GIF, and JPEG, the graph file will be embedded using Base64 encoding. In
case of SVG, the SVG code will be copied into the output document. The default is
nohardcode, i.e. to include the graph using a link to the external graph file.

[no]keep specifies whether the external graph file (and its
Base64 variant) will be kept. This is only relevant if hardcode has
been specified. The default is keep, i.e. to keep the graph files so
that nodo can be applied later on. Type nokeep if you want to
erase the external graph files.

[no]custom specifies whether to use custom code to include the
graph in the output document. The default is nocustom, in which case
webdoc graph uses standard code to include the
graph. Specify custom if you want to skip the standard code and take
care of including the graph yourself.

Options for webdoc strip

replace allows overwriting an existing file.

append appends results to an existing file.

Examples

A typical do-file containing webdoc commands might look as follows:

--- example1.do ---
webdoc init example1, replace logall plain
/***
<!DOCTYPE html>
<html><body>
<h1>Exercise 1</h1>
<p>Open the 1978 Automobile Data and summarize price and milage.</p>
***/
sysuse auto
summarize price mpg
/***
<h1>Exercise 2</h1>
<p>Run a regression of price on milage and display the relation in a scatter
plot.</p>
***/
regress price mpg
twoway (scatter price mpg) (lfit price mpg)
webdoc graph
/***
</body></html>
***/
--- end of file ---

In the example, option logall is specified so that all Stata output
is included in the HTML document (in addition, option plain is specified
to omit HTML tags from the Stata output so that the display of the HTML file
below is more readable). To process the file, type

. webdoc do example1.do

This will create the following HTML file:

--- example1.html ---
<!DOCTYPE html>
<html><body>
<h1>Exercise 1</h1>
<p>Open the 1978 Automobile Data and summarize price and milage.</p>
<pre id="stlog-1" class="stlog"><samp>. sysuse auto
(1978 Automobile Data)

. summarize price mpg

Variable | Obs Mean Std. Dev. Min Max
-------------+---------------------------------------------------------
price | 74 6165.257 2949.496 3291 15906
mpg | 74 21.2973 5.785503 12 41
</samp></pre>
<h1>Exercise 2</h1>
<p>Run a regression of price on milage and display the relation in a scatter
plot.</p>
<pre id="stlog-2" class="stlog"><samp>. regress price mpg

Source | SS df MS Number of obs = 74
-------------+---------------------------------- F(1, 72) = 20.26
Model | 139449474 1 139449474 Prob &gt; F = 0.0000
Residual | 495615923 72 6883554.48 R-squared = 0.2196
-------------+---------------------------------- Adj R-squared = 0.2087
Total | 635065396 73 8699525.97 Root MSE = 2623.7

------------------------------------------------------------------------------
price | Coef. Std. Err. t P&gt;|t| [95% Conf. Interval]
-------------+----------------------------------------------------------------
mpg | -238.8943 53.07669 -4.50 0.000 -344.7008 -133.0879
_cons | 11253.06 1170.813 9.61 0.000 8919.088 13587.03
------------------------------------------------------------------------------

. twoway (scatter price mpg) (lfit price mpg)
</samp></pre>
<figure id="fig-2">
<a href="example1_2.png"><img alt="example1_2.png" src="example1_2.png"/></a>
</figure>
</body></html>
--- end of file ---

If you are not familiar with HTML, you can also type your text in
Markdown format. An
example do-file might look as follows:

--- example2.do ---
webdoc init example2, md replace logall plain
/***
# Exercise 1

Open the 1978 Automobile Data and summarize price and milage.

***/
sysuse auto
summarize price mpg
/***

# Exercise 2

Run a regression of price on milage and display the relation in a scatter plot.

***/
regress price mpg
twoway (scatter price mpg) (lfit price mpg)
webdoc graph
--- end of file ---

Typing

. webdoc do example2.do

will create file "example2.md", which can then be converted to HTML using
a Markdown converter. For example, if Pandoc
is installed on your system, you could type

. !pandoc example2.md -s -o example2.html

to create the HTML file. Argument -s (standalone) has been specified
so that a basic header and footer is added to the document.

For further examples see webdoc's website at
http://repec.sowi.unibe.ch/stata/webdoc or the
working paper.

Remarks

webdoc substitute
webdoc local
Changing the HTML settings
Limitations
Global macros

webdoc substitute

After the output document has been initialized, the webdoc substitute
command can be used to define text substitutions that will be applied to
all subsequent /*** ***/ blocks. For example, type

webdoc substitute "some text" "SOME TEXT" "more text" "MORE TEXT"

to replace all instances of "some text" by "SOME TEXT" and
all instances of "more text" by "MORE TEXT". To change the
substitution definitions in a later part of the document, specify
webdoc substitute again with new definitions. To add definitions to the
existing definitions, specify webdoc substitute with the add
option. To deactivate the substitutions, specify webdoc substitute
without arguments.

webdoc local

The webdoc local command can be used to define local macros that will
be backed up on disk. It may only be applied within or after a webdoc stlog
section. The locals will be backed up in a library that has the same name as
the Stata output section (using file suffix ".stloc"). Each output section
has its own library, so that the names of the locals can be reused between
sections. The syntax of webdoc local is the same as the syntax of
Stata's regular local command; see help local.

Use the webdoc local command if you want to include results from an
output section in the text body. webdoc local provides a way to store
the elements you want to include in your text so that they are still
available in later runs when you suppress computations using the nodo
option. The local macros defined by webdoc local will be expanded in
subsequent /*** ***/ blocks up until the next webdoc stlog
command. Alternatively, you may use webdoc write or webdoc put
to write the locals to the output document (there is a slight difference
between the two approaches: expansion in /*** ***/ blocks is based on
the locals as stored in the library file; webdoc write
and webdoc put use the current values of the locals). For example,
to cite the point estimate and standard error of a regression coefficient,
you could type:

webdoc stlog
regress y x1 x2 ...
webdoc stlog close
webdoc local b = strofreal(_b[x1], "%9.3f")
webdoc local se = strofreal(_se[x1], "%9.3f")

/*** <p>As can be seen in the output above, the estimate for the effect
of x1 on y is equal to `b' (with a standard error of `se').</p> ***/

Alternatively, you could also type:

webdoc put <p> As can be seen in the output above, the estimate for
webdoc put the effect of x1 on y is equal to `b' (with a standard
webdoc put error of `se').</p>

Changing the HTML settings

}

Parts of the HTML code written by webdoc can be customized by the
webdoc set command. The syntax of webdoc set is

webdoc set [setname [definition]]

where setname is the name of the element you want to change. To
restore the default settings for all elements, type webdoc set
without argument. webdoc set only has an effect if applied within a
do-file processed by webdoc do. Furthermore, all settings will be removed when
webdoc do terminates. The elements you can modify, and their default
definitions, are as follows.

Description setname Default definition

Stata output section stlog <pre id="\`id'" class="stlog"><samp>

_stlog </samp></pre>

Stata code section stcmd <pre id="\`id'" class="stcmd"><code>

_stcmd </code></pre>

Stata help section sthlp <pre id="\`id'" class="sthlp">

_sthlp </pre>

Stata input tag stinp <span class="stinp">

_stinp </span>

Stata result tag stres <span class="stres">

_stres </span>

Stata comment tag stcmt <span class="stcmt">

_stcmt </span>

Output-omitted tag stoom <span class="stoom">(output omitted)</span>

Cont-on-next-page tag stcnp <span class="stcnp" style="page-break-after:always"><br/>(continued on next page)<br/></span>

Figure tag figure <figure id="\`macval(id)'">

_figure </figure>

Figure caption fcap <figcaption>\`macval(caption)'</figcaption>

Figure link tag flink <a href="\`webname'\`suffix'">

_flink </a>

Image tag img <img alt="\`macval(alt)'"\`macval(title)' src="

_img "\`macval(attributes)'/>

Embedded SVG svg <span\`macval(title)'\`macval(attributes)'>

_svg </span>

Names without underscore refer to opening tags (or opening and closing
tags), names with underscore refer to closing tags. As illustrated by the
default settings, some of the elements make use of local macros, with a
leading backslash for delayed expansion. An interesting additional macro
that can be used in [_]stlog and [_]stcmd
is \`doname', containing the name of the do-file
that is generated if the dosave option has been
specified. For example, to provide a download link for the do-file in the
upper right corner of each output section, you could type

. webdoc set stlog <pre id="\`id'" class="stlog"
style="position:relative;"><a href="\`doname'"
style="position:absolute;top:5px;right:5px">[code]</a><samp>

SVG images embedded in the output document using the hardcode option
will be tagged by [_]svg. For all other graphs,
[_]img will be used.

Limitations

The $ character is used for global macro expansion in Stata. If you
use webdoc write or webdoc put to write text containing
$, type \$ instead of $.

webdoc do only provides limited support for the semicolon command
delimiter (see #delimit). For example, do not use semicolons to
delimit webdoc commands. The semicolon command delimiter
should work as expected as long as it is turned on and off between
/*** ***/ blocks and between webdoc commands.

In general, webdoc commands should always start on a new line with
webdoc being the first (non-comment) word on the line (for example,
do not use quietly webdoc ... or similar).

webdoc stlog cannot be nested. Furthermore, do not use
webdoc do or webdoc init within a webdoc stlog section.

When processing a do-file, webdoc do does not parse the contents
of do-files that may be called from the main do-file using the do
command. As a consequence, for example, /*** ***/ blocks in such a file
will be ignored. Use webdoc do instead of do to include such
do-files.

webdoc tries to create missing subdirectories using Mata's
mkdir() function. Usually, this only works if all
intermediate directories leading to the target subdirectory already
exist. If mkdir() fails, you will need to create the
required directories manually prior to running webdoc.

Global macros

webdoc maintains a number of global macros for communication between
webdoc commands. Do not change or erase these global macros while
working with webdoc.

Global macros maintained by webdoc do (will be cleared when
webdoc do terminates):
WebDoc_dofile, WebDoc_do_snippets, WebDoc_do_replace,
WebDoc_do_append, WebDoc_do_md, WebDoc_do_header,
WebDoc_do_header2, WebDoc_do_logall, WebDoc_do_linesize,
WebDoc_do_nodo, WebDoc_do_nolog, WebDoc_do_cmdlog,
WebDoc_do_dosave, WebDoc_do_plain, WebDoc_do_raw,
WebDoc_do_nooutput, WebDoc_do_matastrip,
WebDoc_do_cmdstrip, WebDoc_do_lbstrip, WebDoc_do_gtstrip,
WebDoc_do_noltrim, WebDoc_do_mark, WebDoc_do_tag,
WebDoc_do_custom, WebDoc_do_nokeep, WebDoc_do_certify,
WebDoc_do_gropts, WebDoc_do_logdir, WebDoc_do_logdir2,
WebDoc_do_grdir, WebDoc_do_dodir, WebDoc_do_noprefix,
WebDoc_do_prefix, WebDoc_do_prefix2, WebDoc_do_stpath,
WebDoc_do_stpath2

Global macros maintained by webdoc set (will be cleared when
webdoc do terminates):
WebDoc_set_stlog, WebDoc_set__stlog, WebDoc_set_stcmd,
WebDoc_set__stcmd, WebDoc_set_sthlp, WebDoc_set__sthlp,
WebDoc_set_stinp, WebDoc_set__stinp, WebDoc_set_stres,
WebDoc_set__stres, WebDoc_set_stcmt, WebDoc_set__stcmt,
WebDoc_set_stoom, WebDoc_set_stcnp, WebDoc_set_figure,
WebDoc_set__figure, WebDoc_set_fcap, WebDoc_set_flink,
WebDoc_set__flink, WebDoc_set_img, WebDoc_set__img,
WebDoc_set_svg, WebDoc_set__svg

Global macros maintained by webdoc init (will be cleared by
webdoc close):
WebDoc_docname, WebDoc_docname_FH, WebDoc_docname0,
WebDoc_basename, WebDoc_path, WebDoc_path0,
WebDoc_stcounter, WebDoc_md, WebDoc_nofooter,
WebDoc_logall, WebDoc_linesize, WebDoc_nodo,
WebDoc_nolog, WebDoc_cmdlog, WebDoc_dosave,
WebDoc_plain, WebDoc_straw, WebDoc_nooutput,
WebDoc_matastrip, WebDoc_cmdstrip, WebDoc_lbstrip,
WebDoc_gtstrip, WebDoc_noltrim, WebDoc_mark,
WebDoc_tag, WebDoc_custom, WebDoc_nokeep,
WebDoc_certify, WebDoc_gropts, WebDoc_logdir,
WebDoc_do_grdir, WebDoc_dodir, WebDoc_prefix,
WebDoc_prefix0, WebDoc_stpath

Global macro maintained by webdoc substitute (will be cleared by
webdoc close): WebDoc_substitute

Global macros maintained by webdoc stlog (will be cleared by
webdoc close):
WebDoc_ststatus, WebDoc_stname, WebDoc_stname0,
WebDoc_stid, WebDoc_stfilename, WebDoc_stfilename0,
WebDoc_stwebname, WebDoc_stwebname0, WebDoc_stgrcounter,
WebDoc_stlinesize, WebDoc_stlinesize0, WebDoc_stnodo,
WebDoc_stnolog, WebDoc_stcmdlog, WebDoc_stdosave,
WebDoc_stplain, WebDoc_straw, WebDoc_stnooutput,
WebDoc_stmatastrip, WebDoc_stcmdstrip, WebDoc_stlbstrip,
WebDoc_stgtstrip, WebDoc_stnoltrim, WebDoc_stmark,
WebDoc_sttag, WebDoc_stcustom, WebDoc_stnokeep,
WebDoc_stcertify

Global macro maintained by webdoc local (will be cleared by
webdoc stlog or webdoc close): WebDoc_stloc

In addition, webdoc do maintains an external Mata global called
WebDoc_do_snippets. Do not modify the contents of this external
global. If the external global is deleted (e.g. because the processed
do-file contains a clear all command), webdoc do automatically
restores it. The external global will be removed when webdoc do
terminates.

Stored results

webdoc close stores the following in s():

Macros

s(docname) name of output document (including absolute path)

s(basename) base name of output document (excluding path)

s(path) (absolute) path of output document

s(md) md or empty

s(logall) logall or empty

s(linesize) specified line width or empty

s(nodo) nodo or empty

s(nolog) nolog or empty

s(cmdlog) cmdlog or empty

s(dosave) dosave or empty

s(plain) plain or empty

s(raw) raw or empty

s(nooutput) nooutput or empty

s(matastrip) matastrip or empty

s(cmdstrip) cmdstrip or empty

s(lbstrip) lbstrip or empty

s(gtstrip) gtstrip or empty

s(noltrim) noltrim or empty

s(mark) contents of mark() option

s(tag) contents of tag() option

s(custom) custom or empty

s(nokeep) nokeep or empty

s(certify) certify or empty

s(gropts) default graph export options

s(logdir) subdirectory used for Stata log files

s(grdir) subdirectory used for graphs (if different from s(logdir))

s(dodir) subdirectory used for do-files (if different from s(logdir))

s(prefix) prefix for automatic names

s(stpath) include-path to be used in the output document

webdoc stlog close stores the following in s():

Macros

s(name) name of the Stata output log, including logdir() path

s(name0) s(name) without logdir() path

s(id) id of the log in the output document

s(filename) name of log file on disk (including absolute path and suffix)

s(filename0) s(filename) without suffix

s(webname) name of log file with include-path for use in output document

s(webname0) s(webname) without suffix

s(doname) name (and include-path) of do-file

s(linesize) line width used for the output log

s(indent) size of indentation

s(nodo) nodo or empty

s(nolog) nolog or empty

s(cmdlog) cmdlog or empty

s(dosave) dosave or empty

s(plain) plain or empty

s(raw) raw or empty

s(nooutput) nooutput or empty

s(matastrip) matastrip or empty

s(cmdstrip) cmdstrip or empty

s(lbstrip) lbstrip or empty

s(gtstrip) gtstrip or empty

s(noltrim) noltrim or empty

s(mark) contents of mark() option

s(tag) contents of tag() option

s(custom) custom or empty

s(nokeep) nokeep or empty

s(certify) certify or empty

webdoc init clears s().

Author

Ben Jann, University of Bern, ben.jann@soz.unibe.ch

Thanks for citing this software in one of the following ways:

Jann, Ben (2016). Creating HTML or Markdown documents from within Stata
using webdoc. University of Bern Social Sciences Working Papers
No. 22. Available from
http://ideas.repec.org/p/bss/wpaper/22.html.

Jann, B. (2016). webdoc: Stata module to create a HTML or Markdown document
including Stata output. Available from
http://ideas.repec.org/c/boc/bocode/s458209.html.

Also see

Online: help for
file,
log,
texdoc (if installed)