Code Chunks

Pandoc attribute syntax

Codebraid uses Pandoc’s existing attribute syntax to make code chunks executable and give them other roles. Pandoc attributes have the general form

{#id .class1 .class2 key1=value1 key2=value2}

That is, attributes are wrapped in curly braces {} and separated by spaces. An optional id attribute is indicated by a leading hash symbol #, while optional classes are indicated by leading periods .. Optional key-value pairs are separated by an equals sign = with no space. Values can be quoted with double quotation marks ", in which case literal quotation marks can be backslash-escaped as \". Line breaks are allowed between attributes within the wrapping curly braces, so a long collection of attributes is not required to be on a single line.

For fenced code blocks, Pandoc attributes are placed after the opening fence, with optional separating whitespace:

```{#id .class1 .class2 key1=value1 key2=value2}
<code>
```

Meanwhile, for inline code, Pandoc attributes are placed immediately after the closing backtick delimiter:

`<code>`{#id .class1 .class2 key1=value1 key2=value2}

Commands (Classes)

A code chunk (block or inline) is made executable or given a special role by adding a Codebraid class to its Pandoc attributes. For example, `code` is executed with Python by adding a language class and a Codebraid class: `code`{.python .cb-run}.

All Codebraid classes are listed below. These all have the form .cb-<command>. Classes with the form .cb.<command> (period rather than hyphen) are supported for Pandoc’s Markdown (--from markdown), but not for CommonMark-based formats like commonmark_x since they have a more restricted class syntax. The forms shown below (.cb-<command>) should be preferred for compatibility across Markdown variants supported by Pandoc.

.cb-code

Display code verbatim, but do not execute it. This is primarily useful when combined with other features like naming and then copying code chunks.

.cb-expr

Evaluate code as an expression and interpret the result as Markdown. Only works with inline code. This is not currently compatible with Jupyter kernels.

.cb-nb

Execute code in notebook mode. For inline code, this is equivalent to .cb-expr with verbatim output unless a Jupyter kernel is used, in which case rich output like plots or LaTeX will be displayed. For code blocks, this inserts the code verbatim, followed by any printed output (stdout) verbatim. If stderr exists, it is also inserted verbatim. When a Jupyter kernel is used, rich output like plots or LaTeX is also displayed.

.cb-paste

Display code and/or output copied from one or more named code chunks. The copy keyword is used to specify chunks to be copied. This does not execute any code. Unless show is specified, display options are inherited from the first copied code chunk.

If content is copied from multiple code chunks that are executed, all code chunks must be in the same session and must be in sequential order without any omitted chunks. This ensures that what is displayed is always consistent with what was executed. If content is copied from another .cb-paste code chunk, only a single code chunk can be copied. This reduces the indirection that is possible when displaying the output of code that has been executed. This restriction may be removed in the future.

.cb-run

Run code and interpret any printed content (stdout) as Markdown. Also insert stderr verbatim if it exists. When a Jupyter kernel is used, rich output like plots or LaTeX is also displayed.

Keyword arguments

The behavior of code chunks with Codebraid classes (commands) is modified with keyword arguments. Pandoc attribute syntax allows keyword arguments of the form key=value, with spaces (not commas) separating subsequent keys. value can be unquoted if it contains only letters and some symbols; otherwise, double quotation marks "value" are required. For example,

{.python key1=value1 key2=value2}

Codebraid adds support for additional keyword arguments beyond those defined by Pandoc. In some cases, multiple keywords can be used for the same option. This is primarily for Pandoc compatibility.

First chunk options

Some keywords are only permitted for the first code chunk in a session (or the first chunk for a language, if a session is not specified and thus the default session is in use). In the future, at least some of these will be able to be specified in the YAML metadata or another more centralized location instead.

executable={string}

Executable to use for running or compiling code, instead of the default. This only applies to Codebraid’s built-in code execution system.

executable_opts={string}

Command-line options passed to executable. This only applies to Codebraid’s built-in code execution system.

args={string}

Command-line arguments passed to code during execution. For example, this could be used to add values to sys.argv for Python. This only applies to Codebraid’s built-in code execution system.

jupyter_kernel={string}

Jupyter kernel to use for executing code instead of Codebraid’s built-in code execution system. Multiple Jupyter kernels can be used within a single document, and multiple sessions are possible per kernel. Except when otherwise specified, Jupyter kernels should be usable just like the built-in code execution system. If code is only executed with Jupyter kernels, setting jupyter: true in the YAML metadata can be a document-wide alternative to setting kernels for each individual session.

jupyter_timeout={int}

Jupyter kernel timeout per code chunk in seconds. The default is 60.

live_output={bool}

Show code output (stdout and stderr) live in the terminal during code execution. For Jupyter kernels, also show errors and a summary of rich output. Output still appears in the document as normal. Showing output can also be enabled via the command-line option --live-output or in the YAML metadata with live_output: true. When live_output=false is set for a session, this setting takes precedence YAML metadata and the command line.

All output is written to stderr, so stdout only contains the document when --output is not specified. With Codebraid’s built-in code execution system, the output for a code chunk may be delayed until all code in the chunk has finished executing, unless code output is line buffered or code manually flushes stdout and stderr. For example, with Python you may want to use print functions like print("text", flush=True). Another option is to use Python in line-buffered mode by setting executable_opts="-u" in the first code chunk of a session. With Jupyter kernels, the output for a code chunk will be delayed until all code in the chunk has finished executing.

Code execution

complete={bool}

By default, code chunks must contain complete units of code (function definitions, loops, expressions, and so forth). With complete=false, this is not required. Any stdout from code chunks with complete=false is accumulated until the next code chunk with complete=true (the default value), or until the end of the session, whichever comes first. Setting complete is incompatible with outside_main=true, since the complete status of code chunks with outside_main=true is inferred automatically.

outside_main={bool}

This allows code chunks to overwrite the Codebraid template code when code is executed with Codebraid’s built-in code execution system. It is primarily useful for languages like Rust, in which code is inserted by default into a main() template. In that case, if a session starts with one or more code chunks with outside_main=true, these are used instead of the beginning of the main() template. Similarly, if a session ends with one or more code chunks with outside_main=true, these are used instead of the end of the main() template. Any code chunks in between with the default outside_main=false will have their stdout collected on a per-chunk basis like normal. Having code chunks with outside_main=false is not required; if there are none, the total accumulated stdout for a session belongs to the last code chunk in the session. outside_main=true is incompatible with explicitly setting complete; the complete status of code chunks with outside_main=true is inferred automatically.

session={identifier-style string}

By default, all code for a given language is executed in a single, shared session so that data and variables persist between code chunks. This option allows code to be separated into multiple independent sessions. Session names must be Python-style identifiers.

For the built-in execution system, using multiple sessions is equivalent to dividing code into multiple source files and executing them separately. For Jupyter, multiple sessions is analogous to dividing code into multiple Jupyter notebook.

Display

first_number/startFrom/start-from/start_from={int or next}

Specify the first line number for code when line numbers are displayed. next means continue from the last code in the current session.

hide={markup, copied_markup, code, stdout, stderr, expr, rich_output, all}

Hide some or all of the elements that are displayed by default. Elements can be combined. For example, hide=stdout+stderr. Note that expr only applies to .cb-expr or .cb-nb with inline code using Codebraid’s built-in code execution system, since only these evaluate an expression. rich_output is currently only relevant for Jupyter kernels.

hide_markup_keys={key(s)}

Hide the specified code chunk attribute key(s) in the Markdown source displayed via markup or copied_markup. Multiple keys can be specified via hide_markup_keys=key1+key2. hide_markup_keys only applies to the code chunk in which it is used, to determined the markup for that code chunk. Thus, it only affects copied_markup indirectly.

line_numbers/numberLines/number-lines/number_lines={bool}

Number code lines in code blocks.

show={markup, copied_markup, code, stdout, stderr, expr, rich_output, none}

Override the elements that are displayed by default. expr only applies to .cb-expr and to .cb-nb with inline code using Codebraid’s built-in code execution system, since only these evaluate an expression. Elements can be combined. For example, show=code+stdout.

Each element except rich_output can optionally specify a format from raw, verbatim, or verbatim_or_empty. For example, show=code:verbatim+stdout:raw.

  • raw means interpreted as Markdown.
  • verbatim produces inline code or a code block, depending on context. When output containing newlines is displayed verbatim in an inline context, the newlines are replaced with spaces. Nothing is displayed if there is no content (for example, nothing in stdout).
  • verbatim_or_empty produces inline code containing a single non-breaking space or a code block containing a single empty line in the event that there is no content. It is useful when a placeholder is desired, or a visual confirmation that there is indeed no output.

For rich_output, the format is specified as one or more abbreviations for the mime types of the output to be displayed. For example, rich_output:plain will display text/plain output if it exists, and otherwise nothing. rich_output:png|plain will display a PNG image if it exists, or otherwise will fall back to plain text if available. The following formats are currently supported:

  • latex (corresponds to text/latex)
  • html (text/html)
  • markdown (text/markdown)
  • plain (text/plain)
  • png (image/png)
  • jpg and jpeg (image/jpeg)
  • svg (image/svg+xml)
  • pdf (application/pdf)

For rich_output formats with a text/* mime type (latex, html, markdown, plain), it is possible to specify whether they are displayed raw, verbatim, or verbatim_or_empty. For example, show=rich_output:latex:raw and show=rich_output:latex:verbatim. raw treats latex and html as raw content with those formats embedded within Markdown. raw treats markdown and plain as Markdown. When a display style is not specified, all rich_output formats with a text/* mime type are displayed raw by default, except for plain which is displayed verbatim.

markup displays the Markdown source for the inline code or code block. Because the Markdown source is not available in the Pandoc AST but rather must be recreated from it, the Markdown source displayed with markup may use a different number of backticks, quote attribute values slightly differently, or contain other insignificant differences from the original document.

copied_markup displays the Markdown source for code chunks copied via copy.

expr defaults to raw if a format is not specified. rich_output defaults to latex|markdown|png|jpg|svg|plain. All others default to verbatim.

example={bool}

Insert a code block containing the Markdown source of the code chunk, followed by the rest of the output as normal. This is only valid for inline code if the code is in a paragraph by itself. This option is currently not compatible with --only-code-output and Codebraid Preview. This option is intended primarily for documentation about Codebraid.

Copying

The code or output of a code chunk can be copied by another code chunk. Then the code can be executed or displayed elsewhere in the document, or the output can be displayed elsewhere. A code chunk can copy content from another code chunk that appears after it in a document; code chunk ordering does not affect copying.

copy={chunk name(s)}

Copy one or more named code chunks. When copy is used with a command like .cb-run that executes code, only the code is copied from the designed code chunks, and it is executed as if it had been entered directly. When copy is used with .cb-code, only the code is copied from the designated chunks and nothing is executed. When copy is used with .cb-paste, both code and output are copied from the designated chunks, and nothing is executed. Multiple code chunks may be copied; for example, copy=name1+name2. In that case, the code from all chunks is concatenated, as is any output that is copied. Because copy brings in code from other code chunks, the actual content of a code block or inline code using copy is discarded. As a result, this must be empty, or a space or underscore can be used as a placeholder.

name={identifier-style string}

Name a code chunk so that it can later be copied by name. Names must be Python-style identifiers.

Including external files

include_file={path}

Include the specified file. A leading ~/ or ~<user>/ is expanded to the user’s home directory under all operating systems, including under Windows with both slashes and backslashes.

When include_file is used with a command like .cb-run that executes code, the file is included and executed as part of the current session just as if the file contents had been entered directly. When include_file is used with .cb-code, the file is included and displayed just as if it had been entered directly. Because include_file brings in code from another file, the actual content of a code block or inline code using include_file is discarded. As a result, this must be empty, or a space or underscore can be used as a placeholder.

include_encoding={encoding}

Encoding for included file. The default encoding is UTF-8.

include_lines={lines/line ranges}

Include the specified lines or line ranges. For example, 1-3,5,7-9,11-. Line numbers are one-indexed. Line ranges are inclusive, so 1-3 is 1 up to and including 3. If a range ends with a hyphen, like 11-, then everything is included from the line through the end of the file.

Cannot be combined with other include options that specify what is to be included.

include_regex={regex}

Include the first segment of the file that matches the provided regular expression.

Keep in mind that Pandoc’s key-value attributes evaluate backslash escapes in values whether or not the values are quoted with double quotation marks, so two levels of backslash-escaping are always necessary (one for Pandoc’s strings, one for the regex itself; there are no raw strings). Regular expressions use multiline mode, so ^/$ match the start/end of a line, and \A/\Z can be used to match the start/end of the file. Regular expressions use dotall mode, so . matches anything including the newline \n; use [^\n] when this is not desired.

Cannot be combined with other include options that specify what is to be included.

include_start_string={string}

Include everything from the first occurrence of this string onward.

Can only be combined with other include options that specify the end of what is to be included.

include_start_regex={regex}

Include everything from the first match of this regex onward.

Can only be combined with other include options that specify the end of what is to be included. See include_regex for notes on regex usage.

include_after_string={string}

Include everything after the first occurrence of this string onward.

Can only be combined with other include options that specify the end of what is to be included.

include_after_regex={regex}

Include everything after the first match of this regex onward.

Can only be combined with other include options that specify the end of what is to be included. See include_regex for notes on regex usage.

include_before_string={string}

Include everything before the first occurrence of this string.

Can only be combined with other include options that specify the start of what is to be included. If the start is specified, then the first occurrence after this point is used, rather than the first occurrence in the overall file.

include_before_regex={regex}

Include everything before the first match of this regex.

Can only be combined with other include options that specify the start of what is to be included. If the start is specified, then the first match after this point is used, rather than the first match in the overall file. See include_regex for notes on regex usage.

include_end_string={string}

Include everything through the first occurrence of this string.

Can only be combined with other include options that specify the start of what is to be included. If the start is specified, then the first occurrence after this point is used, rather than the first occurrence in the overall file.

include_end_regex={regex}

Include everything through the first match of this regex.

Can only be combined with other include options that specify the start of what is to be included. If the start is specified, then the first match after this point is used, rather than the first match in the overall file. See include_regex for notes on regex usage.