*! version 1.0.0 18jan2026

Title

ishere -- Insert markers in log files for report generation

Syntax

Mode 1: Placeholder syntax (for marking flags for markdown generation)

ishere

ishere ```

ishere # heading text

ishere /*

ishere */

ishere tab[other_text]

ishere fig[other_text]

Mode 2: Markdown insertion syntax (for embedding figures and tables)

Insert figure

ishere fig|figure using filename
[, zoom(string) height(string) width(string)]

Insert table

ishere tab|table using filename
[, height(string) width(string)]

Display local or scalar values

ishere display expression

Description

The name ishere draws inspiration from a long-standing convention in academic and technical writing:
the humble placeholder note like "Table 1 goes here" or "Figure inserted here." For decades, researchers
have used such phrases to mark where results should appear in a manuscript—especially when figures and
tables are generated separately from the main text.

In the world of reproducible research with Stata, a similar need arises: how do you tell your analysis
script, "Put the graph right here in the log," so that it can later be cleanly converted into a polished
report? The answer is ishere.

Literally meaning "insert something here, on this line, in this do-file," ishere acts as a dynamic,
executable placeholder. It is a dual-purpose command designed to work with tohtml for generating
formatted HTML reports from Stata log files.

Mode 1: Placeholder mode

In this mode, ishere acts as a passive marker in your log file. When you run it during your Stata session,
it produces no visible output but leaves markers in the log that tohtml later uses to structure your report.
This mode is used for:

- Marking code block boundaries: ishere or ishere ```

- Inserting markdown headings: ishere # Main Title or ishere ## Subtitle

- Marking text blocks: ishere /* ... ishere */

- Specifying inserting a table: ishere tab[other_text]

- Specifying inserting a figure: ishere fig[other_text]

Mode 2: Markdown insertion mode

In this mode, ishere actively generates markdown code that is printed to the log file. This markdown code
will be preserved when tohtml processes the log. This mode is used for:

- Embedding figures: ishere fig using "figure1.png" generates an HTML <img> tag or markdown image syntax

- Embedding HTML tables: ishere tab using "table1.html" generates an HTML <iframe> tag

- Embedding Markdown tables: ishere tab using "table1.md" generates markdown table syntax directly

- Displaying values: ishere display outputs local macros, scalars, or any valid Stata expression to the log

This mode supports various image formats (PNG, JPG, JPEG, SVG, GIF, BMP, WEBP), HTML tables, and Markdown tables.

Options

Options are only available in Mode 2 (markdown insertion syntax)

Figure options

zoom(string) specifies the zoom level for the image, default is 100%. You can specify a percentage
(e.g., "80%" or "80").

height(string) specifies the image height. Can use any valid CSS dimension unit (e.g., "300px", "50%").

width(string) specifies the image width. Can use any valid CSS dimension unit.

Table options

height(string) specifies the iframe height for HTML tables, default is "400px". For Markdown tables, this option is ignored.

width(string) specifies the iframe width for HTML tables, default is "100%". For Markdown tables (.md files), this option is ignored.

Display syntax

The display subcommand has no options. It accepts any valid Stata expression and outputs it to the log.
This is primarily used in combination with text blocks (ishere /* ... ishere */) to insert computed
values into narrative text. The typical workflow is:

1. Run ishere display in your code to output the value

2. Reference it in text blocks using the placeholder syntax {ishere display ...}

3. When tohtml processes the log, it automatically replaces placeholders with actual values

Important: The ishere display command only affects the first textcell (ishere /* ... ishere */)
that appears after the display command in the log file. If you have multiple text blocks, each ishere display
will only replace placeholders in the immediately following text block, not in later ones.

Examples

Mode 1 Examples: Using ishere as placeholder

Mark code block boundaries

. ishere

. sysuse auto, clear

. summarize

. ishere

Insert markdown headings

. ishere # Data Analysis Report

. ishere ## Descriptive Statistics

Mark text blocks for narrative content

. ishere /*

. * This is explanatory text

. * It can span multiple lines

. ishere */

Mode 2 Examples: Inserting markdown code for figures and tables

Insert a figure with default settings

. scatter price mpg

. graph export "figure1.png", replace

. ishere fig using "figure1.png"

Insert a figure with zoom

. ishere fig using "figure1.png", zoom(80%)

Insert a figure with custom dimensions

. ishere figure using "figure1.png", height(400px) width(600px)

Insert an HTML table

. ishere tab using "table1.html"

Insert a table with custom dimensions

. ishere table using "table1.html", height(500px) width(100%)

Insert a Markdown table

. ishere tab using "table1.md"

Basic usage: Insert value in text block

. sysuse auto, clear

. local N = _N

. ishere display `N'

. ishere /*

. * The dataset contains {ishere display `N'} observations.

. ishere */

Insert formatted numeric values

. summarize price

. local mean_price = r(mean)

. ishere display %9.2f `mean_price'

. ishere /*

. * The average price is ${ishere display %9.2f `mean_price'}.

. ishere */

Insert multiple values in text

. regress price mpg weight

. local r2 = e(r2)

. local N = e(N)

. ishere display %5.3f `r2'

. ishere display `N'

. ishere /*

. * The model R-squared is {ishere display %5.3f `r2'} based on {ishere display `N'} observations.

. ishere */

Insert regression coefficients

. regress price mpg weight

. local coef = _b[mpg]

. local se = _se[mpg]

. ishere display %6.2f `coef'

. ishere display %6.2f `se'

. ishere /*

. * The coefficient on mpg is {ishere display %6.2f `coef'} (SE = {ishere display %6.2f `se'}).

. ishere */

Using display with multiple text blocks (each needs its own display command)

. regress price mpg weight

. local r2 = e(r2)

. ishere display %5.3f `r2'

. ishere /*

. * First text block: R-squared is {ishere display %5.3f `r2'}.

. ishere */

.

. * To use the same value in a second text block, you need another display command:

. ishere display %5.3f `r2'

. ishere /*

. * Second text block: The model explains {ishere display %5.3f `r2'} of the variance.

. ishere */

Complete workflow example with display

. log using "analysis.smcl", replace

. ishere # Data Analysis Report

.

. ishere ## Data Overview

. sysuse auto, clear

. local N = _N

. ishere display `N'

. ishere /*

. * This analysis uses the automobile dataset containing {ishere display `N'} observations.

. ishere */

.

. ishere ## Summary Statistics

. ishere

. summarize price mpg weight

. local mean_price = r(mean)

. ishere

. ishere display %9.2f `mean_price'

. ishere /*

. * The average price is ${ishere display %9.2f `mean_price'}.

. ishere */

.

. ishere ## Regression Analysis

. ishere

. regress price mpg weight

. local r2 = e(r2)

. local coef_mpg = _b[mpg]

. ishere

. ishere display %5.3f `r2'

. ishere display %6.2f `coef_mpg'

. ishere /*

. * The regression model has an R-squared of {ishere display %5.3f `r2'}.

. * The coefficient on mpg is {ishere display %6.2f `coef_mpg'}.

. ishere */

.

. ishere ## Visualization

. scatter price mpg

. graph export "scatter.png", replace

. ishere fig using "scatter.png", zoom(80%)

.

. log close

. translate analysis.smcl analysis.md, translator(smcl2log) replace

. tohtml analysis.md, html(analysis.html) replace

Remarks

Understanding the two modes:

Mode 1 (placeholder) produces no visible output during your Stata session - it simply leaves markers in the log file
that tohtml interprets later. Mode 2 (markdown insertion) actively prints markdown/HTML code to your log,
which becomes part of the final document.

Using ishere display for narrative text:

The ishere display command is designed to work with text blocks (ishere /* ... ishere */) to create
dynamic narrative text with embedded computed values. The workflow has two steps:

Step 1: In your code section, compute values and output them using ishere display:

local r2 = e(r2)

ishere display %5.3f `r2'

Step 2: In your text block, reference the values using placeholder syntax {ishere display ...}:

ishere /*

* The model R-squared is {ishere display %5.3f `r2'}.

ishere */

When tohtml processes the log file, it automatically matches the placeholder references with the computed values
and inserts them into the text. This ensures your narrative text always reflects the current analysis results without
manual copying or updating.

The display subcommand accepts the same syntax as Stata's regular display command, including format specifiers
like %5.3f for controlling number precision. This allows precise control over how numbers appear in your report text.

Scope limitation: Each ishere display command only affects the first textcell that appears after it in the log file.
If you need to use the same value in multiple text blocks, you must place an ishere display command before each text block.

Cross-platform compatibility:

File paths with backslashes (\) are automatically converted to forward slashes (/) to ensure cross-platform compatibility.

Workflow:

The typical workflow is: (1) run your analysis with ishere markers, (2) translate SMCL to markdown,
(3) use tohtml to process the markdown into a clean HTML report.

Author

Kerry Du

School of Management

Xiamen University

kerrydu@xmu.edu.cn

Huanyu Jia

School of Business

Zhengzhou University

jiahuanyu@zzu.edu.cn

See also

Help: tohtml, markdown, log