diff --git a/previews/PR159/outputformats/index.html b/previews/PR159/outputformats/index.html index 780bfbb..323efa0 100644 --- a/previews/PR159/outputformats/index.html +++ b/previews/PR159/outputformats/index.html @@ -42,7 +42,7 @@ x = 1//3 ```` ```` 1//3 -````

In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (image/png or image/jpeg), HTML (text/html) or markdown (text/markdown) Literate will include the richest representation of the output.

Note

Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.

See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.

Literate.markdown — Function
Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

Generate a markdown file from inputfile and write the result to the directory outputdir.

See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

source

Markdown flavors

Literate can output markdown in different flavors. The flavor is specified using the flavor keyword argument. The following flavors are currently supported:

4.2. Notebook output

Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.

We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.

See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.

Literate.notebook — Function
Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

Generate a notebook from inputfile and write the result to outputdir.

See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

source

Notebook metadata

Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows

%% optional ignored text [type] {optional metadata JSON}

Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.

The following would create a 3 slide deck with RISE:

#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
+````

In this example the output is just plain text. However, if the resulting value of the code block can be displayed as an image (image/png or image/jpeg), HTML (text/html) or markdown (text/markdown) Literate will include the richest representation of the output.

Note

Since Documenter executes and captures results of @example block it is not necessary to use execute=true for markdown output that is meant to be used as input to Documenter.

See the section about Configuration for more information about how to configure the behavior and resulting output of Literate.markdown.

Literate.markdown — Function
Literate.markdown(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

Generate a markdown file from inputfile and write the result to the directory outputdir.

See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

source

Markdown flavors

Literate can output markdown in different flavors. The flavor is specified using the flavor keyword argument. The following flavors are currently supported:

4.2. Notebook output

Notebook output is generated by Literate.notebook. The (default) notebook output of the source snippet can be seen here: notebook.ipynb.

We note that lines starting with # are placed in markdown cells, and the code lines have been placed in code cells. By default the notebook is also executed and output cells populated. The current working directory is set to the specified output directory the notebook is executed.

See the section about Configuration for how to configure the behavior and resulting output of Literate.notebook.

Literate.notebook — Function
Literate.notebook(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

Generate a notebook from inputfile and write the result to outputdir.

See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

source

Notebook metadata

Jupyter notebook cells (both code cells and markdown cells) can contain metadata. This is enabled in Literate by the %% token, similar to Jupytext. The format is as follows

%% optional ignored text [type] {optional metadata JSON}

Cell metadata can, for example, be used for nbgrader and the reveal.js notebook extension RISE.

The following would create a 3 slide deck with RISE:

#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
 # # Some title
 #
 # We're using `#nb` so the metadata is only included in notebook output
@@ -56,4 +56,4 @@ y = 2//5
 
 y = 2//5
 
-z = x + y

We note that lines starting with # are removed and only the code lines have been kept.

See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

Literate.script — Function
Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

Generate a plain script file from inputfile and write the result to outputdir.

See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

source

4.4. Configuration

The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

Configuration precedence

Individual keyword arguments take precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary take precedence over the default.

Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

Literate.DEFAULT_CONFIGURATION — Constant
DEFAULT_CONFIGURATION

Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. Configuration can be passed as individual keyword arguments or as a dictionary passed with the config keyword argument. See the manual section about Configuration for more information.

Available options:

  • name (default: filename(inputfile)): Name of the output file (excluding the file extension).
  • preprocess (default: identity): Custom preprocessing function mapping a String to a String. See Custom pre- and post-processing.
  • postprocess (default: identity): Custom preprocessing function mapping a String to a String. See Custom pre- and post-processing.
  • credit (default: true): Boolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.
  • keep_comments (default: false): When true, keeps markdown lines as comments in the output script. Only applicable for Literate.script.
  • execute (default: true for notebook, false for markdown): Whether to execute and capture the output. Only applicable for Literate.notebook and Literate.markdown.
  • codefence (default: "````@example $(name)" => "````" for DocumenterFlavor() and "````julia" => "````" otherwise): Pair containing opening and closing code fence for wrapping code blocks.
  • flavor (default: Literate.DocumenterFlavor()) Output flavor for markdown, see Markdown flavors. Only applicable for Literate.markdown.
  • devurl (default: "dev"): URL for "in-development" docs, see Documenter docs. Unused if repo_root_url/ nbviewer_root_url/binder_root_url are set.
  • repo_root_url: URL to the root of the repository. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
  • nbviewer_root_url: URL to the root of the repository as seen on nbviewer. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
  • binder_root_url: URL to the root of the repository as seen on mybinder. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
  • repo_root_path: Filepath to the root of the repository. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
source
+z = x + y

We note that lines starting with # are removed and only the code lines have been kept.

See the section about Configuration for how to configure the behavior and resulting output of Literate.script.

Literate.script — Function
Literate.script(inputfile, outputdir=pwd(); config::Dict=Dict(), kwargs...)

Generate a plain script file from inputfile and write the result to outputdir.

See the manual section on Configuration for documentation of possible configuration with config and other keyword arguments.

source

4.4. Configuration

The behavior of Literate.markdown, Literate.notebook and Literate.script can be configured by keyword arguments. There are two ways to do this; pass config::Dict as a keyword argument, or pass individual keyword arguments.

Configuration precedence

Individual keyword arguments take precedence over the config dictionary, so for e.g. Literate.markdown(...; config = Dict("name" => "hello"), name = "world") the resulting configuration for name will be "world". Both individual keyword arguments and the config dictionary take precedence over the default.

Available configurations with description and default values are given in the reference for Literate.DEFAULT_CONFIGURATION just below.

Literate.DEFAULT_CONFIGURATION — Constant
DEFAULT_CONFIGURATION

Default configuration for Literate.markdown, Literate.notebook and Literate.script which is used for everything not specified by the user. Configuration can be passed as individual keyword arguments or as a dictionary passed with the config keyword argument. See the manual section about Configuration for more information.

Available options:

  • name (default: filename(inputfile)): Name of the output file (excluding the file extension).
  • preprocess (default: identity): Custom preprocessing function mapping a String to a String. See Custom pre- and post-processing.
  • postprocess (default: identity): Custom preprocessing function mapping a String to a String. See Custom pre- and post-processing.
  • credit (default: true): Boolean for controlling the addition of This file was generated with Literate.jl ... to the bottom of the page. If you find Literate.jl useful then feel free to keep this.
  • keep_comments (default: false): When true, keeps markdown lines as comments in the output script. Only applicable for Literate.script.
  • execute (default: true for notebook, false for markdown): Whether to execute and capture the output. Only applicable for Literate.notebook and Literate.markdown.
  • codefence (default: "````@example $(name)" => "````" for DocumenterFlavor() and "````julia" => "````" otherwise): Pair containing opening and closing code fence for wrapping code blocks.
  • flavor (default: Literate.DocumenterFlavor()) Output flavor for markdown, see Markdown flavors. Only applicable for Literate.markdown.
  • devurl (default: "dev"): URL for "in-development" docs, see Documenter docs. Unused if repo_root_url/ nbviewer_root_url/binder_root_url are set.
  • repo_root_url: URL to the root of the repository. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__REPO_ROOT_URL__.
  • nbviewer_root_url: URL to the root of the repository as seen on nbviewer. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__NBVIEWER_ROOT_URL__.
  • binder_root_url: URL to the root of the repository as seen on mybinder. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for @__BINDER_ROOT_URL__.
  • repo_root_path: Filepath to the root of the repository. Determined automatically on Travis CI, GitHub Actions and GitLab CI. Used for computing Documenters EditURL.
source