### Basic Literate.jl Syntax Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/fileformat.md

Demonstrates the basic syntax for Literate.jl files, showing how lines starting with '# ' are interpreted as Markdown and other lines as Julia code. Includes an example of defining and adding rational numbers.

```julia
# # Rational numbers
#
# In julia rational numbers can be constructed with the `//` operator.
# Lets define two rational numbers, `x` and `y`:

## Define variable x and y
x = 1//3
y = 2//5

# When adding `x` and `y` together we obtain a new rational number:

z = x + y

```

--------------------------------

### Documentation Notebook Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

An example of a documentation notebook structure using Literate.jl metadata for titles, setup, introductions, and exercises.

```julia
# %% [markdown] {"name": "title", "tags": ["title"]}
# # Tutorial: Data Analysis
#
# A complete guide to analyzing data

# %% {"name": "setup", "tags": ["hide_input"]}
using Pkg
Pkg.activate(".")

# %% [markdown] {"name": "intro"}
# Introduction paragraph

# %% [markdown] {"tags": ["exercise"]}
# ## Exercise 1
# Try this code
```

--------------------------------

### Complete Example File: Rational Numbers Tutorial

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

A full example file demonstrating Literate.jl usage, including defining rationals, performing arithmetic, and verifying results with tests. It uses specific tags like #nb and #src.

```julia
# # Rational Numbers Tutorial
# 
# This tutorial demonstrates working with Julia's rational numbers.

# ## Defining Rationals
# 
# Rationals are created with the `//` operator:

x = 1 // 3
y = 2 // 5

# ## Arithmetic
# 
# Basic operations work as expected:

z = x + y

# ## Checking the Results
## Verify results (this comment shows in output as '# ')
println("Sum: ", z)  #nb
@test z == 11 // 15  #src
```

--------------------------------

### Presentation Notebook Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

An example of a presentation notebook structure using Literate.jl metadata for slides, speaker notes, and demos.

```julia
# %% [markdown] {"collapsed": false}
# # Slide 1: Title
#
# Main content

# %% [markdown] {"collapsed": false, "tags": ["speaker_notes"]}
# Speaker notes for this slide

# %% {"name": "demo", "tags": ["remove_output"]}
demo_code()
```

--------------------------------

### Markdown Content Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/README.md

Demonstrates how lines starting with '# ' are treated as markdown content and support standard markdown syntax.

```julia
# Lines starting with "# " are markdown
# They support normal markdown syntax

## Double hash for code comments
```

--------------------------------

### Quarto YAML Header Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Shows how to include YAML metadata for Quarto processing by prefixing markdown lines with '# '.

```julia
# ---
# title: "My Report"
# jupyter: julia-1.9
# ---
```

--------------------------------

### Empty Output Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Shows a code block that results in no output, as only an assignment occurs.

```julia
x = 1  # No output, x is assigned
```

--------------------------------

### Filtering Example with Notebook-Specific Content

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

An example showcasing how to include content that is specific to markdown output ('#md') or notebook output ('#nb'), and how to filter code for specific environments ('#jl', '#!jl').

```julia
# # Notebook-Specific Example

#md # This header only appears in markdown output
#nb # This header only appears in notebooks

x = 1  #jl
y = 2  #!jl

#src using Test
#src @test x + y == 3
```

--------------------------------

### Example Flow: Source File Snippet

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

A snippet from a source file showing the beginning of the cell creation pipeline with metadata.

```julia
# %% {"name": "intro"}
```

--------------------------------

### Example Script Content for Script Output

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/outputformats.md

This is an example of the content that would be processed by Literate.script. Lines starting with '# ' are markdown and will be stripped, while other lines are code.

```julia
# This is a comment that will be stripped
println("Hello, world!")
x = 1 + 1
# Another comment
println(x)
```

--------------------------------

### Integration with CI/CD (GitHub Actions)

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/README.md

An example of a GitHub Actions workflow step to generate documentation using Literate.jl.

```yaml
# GitHub Actions example
- name: Generate Documentation
  run: |
    julia -e 'using Literate; Literate.markdown("examples/demo.jl", "docs/src")'
```

--------------------------------

### Jupyter Notebook Structure Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Provides an example of the JSON structure for a Jupyter Notebook file, including metadata and cells.

```json
{
  "nbformat": 4,
  "nbformat_minor": 3,
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": ["# Markdown content"]
    },
    {
      "cell_type": "code",
      "metadata": {},
      "source": ["code_here"],
      "execution_count": null,
      "outputs": []
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Julia 1.9.0",
      "language": "julia",
      "name": "julia-1.9"
    },
    "language_info": {
      "name": "julia",
      "version": "1.9.0",
      "file_extension": ".jl",
      "mimetype": "application/julia"
    }
  }
}

```

--------------------------------

### Jupyter Notebook Stream Output Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Demonstrates the JSON structure for stream output (e.g., from print/println) in a Jupyter Notebook.

```json
{
  "output_type": "stream",
  "name": "stdout",
  "text": ["Result: 3\n"]
}

```

--------------------------------

### Integration with Documenter.jl

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/README.md

Example of how to use Literate.jl to generate Markdown files for Documenter.jl from example scripts.

```julia
# In docs/make.jl
using Literate

# Generate from examples
Literate.markdown(
    "examples/tutorial.jl",
    "docs/src/generated";
    flavor=Literate.DocumenterFlavor()
)
```

--------------------------------

### Research Notebook Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

A practical example of a research notebook structure using Literate.jl metadata for imports, data loading, preprocessing, results, and plots.

```julia
# %% {"name": "imports"}
# # Imports
import DataFrames, Plots

# %% [markdown] {"name": "data", "tags": ["data"]}
# # Loading Data
#
# Load the experimental data

# %% {"name": "preprocessing", "tags": ["preprocessing"]}
df = load_data()
df = preprocess(df)

# %% [markdown] {"name": "results", "tags": ["results", "remove_input"]}
# # Results
#
# Analysis results appear below

# %% {"name": "plots"}
plot(df.x, df.y)
```

--------------------------------

### Notebook Execution Setup

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/parsing.md

Prepares a notebook for execution by generating its structure with execute=false. This function is a precursor to executing all code cells within a notebook.

```julia
using Literate

# Generate notebook (with execute=false first)
notebook_path = Literate.notebook("demo.jl", "output"; execute=false)

```

--------------------------------

### Example: Cell with Name and Tags

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Demonstrates a markdown cell with both a name and an array of tags specified in its metadata.

```julia
# %% [markdown] {"name": "setup", "tags": ["setup", "initialization"]}
# # Setup
#
# Initialize the environment
```

--------------------------------

### Documenter.jl Example Block

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/documenter.md

When `documenter=true` is set for markdown generation, Literate.jl uses Documenter.jl's `@example` block format.

```markdown
```@examples $(name)
# code
```
```

--------------------------------

### Example: Markdown Cell with Name and Type

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Illustrates a markdown cell with both a custom name and its type specified.

```julia
# %% MyCell [markdown]
# Some markdown
```

--------------------------------

### Test Suite Integration

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Shows how to use Literate to generate a script from an example file and then include and test it within a Julia test suite.

```julia
# test/runtests.jl
using Literate
using Test

# Generate script from example
script_path = Literate.script("examples/solution.jl", "test")
include(script_path)

# Now test that it works
@test solution_function() == expected_result
```

--------------------------------

### CI Environment Variables for Source Path

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Examples of how source paths are automatically detected on CI systems like Travis CI, GitHub Actions, and GitLab CI.

```markdown
Travis CI: `https://github.com/{TRAVIS_REPO_SLUG}/blob/{edit_commit}`
GitHub Actions: `https://github.com/{GITHUB_REPOSITORY}/blob/{edit_commit}`
GitLab CI: `{CI_PROJECT_URL}/blob/{edit_commit}`
```

--------------------------------

### Special Syntax Examples

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/README.md

Illustrates various special syntax elements used by Literate.jl for controlling markdown and code output.

```julia
# @__NAME__ → output filename
# @__REPO_ROOT_URL__ → repository URL
# @__NBVIEWER_ROOT_URL__ → nbviewer URL
# @__BINDER_ROOT_URL__ → mybinder URL
```

--------------------------------

### Binder Badge Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/fileformat.md

This snippet shows how to embed a Binder badge in the output, linking to a notebook that can be opened with MyBinder.org. The @__BINDER_ROOT_URL__ placeholder is automatically determined on CI platforms.

```markdown
[![Binder](https://mybinder.org/badge_logo.svg)](@__BINDER_ROOT_URL__/path/to/notebook.inpynb)
```

--------------------------------

### Example: Markdown Cell with Name Metadata

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Demonstrates a markdown cell with a specified name using the Jupytext format.

```julia
# %% [markdown] {"name": "Introduction"}
# # Welcome to my notebook
```

--------------------------------

### Integration with Test Suite

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/README.md

Demonstrates how to use Literate.jl within a test suite to ensure examples remain up-to-date.

```julia
# In test/runtests.jl
using Literate

# Verify examples stay up-to-date
script = Literate.script("examples/solution.jl", "test")
include(script)

using Test
# ... your tests ...
```

--------------------------------

### Replace include calls with file content using preprocess

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/customprocessing.md

Employ a `preprocess` function to substitute `include` statements within a source file with the actual content of the included files. This ensures that documentation reflects the latest versions of separate runnable example files.

```julia
# # Replace includes
# This is an example to replace `include` calls with the actual file content.

include("file1.jl")


```

--------------------------------

### Example: Hide Input from Notebook View

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Shows how to use the 'hide_input' tag to hide the code input of a cell in the notebook view.

```julia
# %% {"tags": ["hide_input"]}
# # Results
#
# The following shows the analysis results

# code_cell_follows
```

--------------------------------

### Example: Code Cell with Marker Only

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Shows a code cell marked with '%%' but without any additional metadata.

```julia
# %% [code]
# # No metadata, just code cell marker
```

--------------------------------

### Markdown Output Example (DocumenterFlavor)

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Illustrates the default Markdown output for Documenter.jl, including metadata and code blocks.

```markdown
```@meta
EditURL = "relative/path/to/source.jl"
```

# # Tutorial

Some markdown content.

````@example tutorial
x = 1 + 2
````

3

````@example tutorial
println(x)
````

1

```

--------------------------------

### Jupyter Notebook Display Data Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Illustrates the JSON structure for display data (from explicit display() calls) in a Jupyter Notebook.

```json
{
  "output_type": "display_data",
  "metadata": {},
  "data": {
    "text/plain": ["Plot object"],
    "image/svg+xml": "<svg>...</svg>"
  }
}

```

--------------------------------

### Enable JULIA_DEBUG Before Julia Session

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/tips.md

Start a Julia session with the JULIA_DEBUG environment variable set to "Literate" from the shell.

```sh
$ JULIA_DEBUG=Literate julia
```

--------------------------------

### Source Code for Admonition Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/tips.md

This is the source code that will be processed by custom preprocessors to generate different admonition styles for Markdown and notebooks.

```julia
#note # This is a useful note.
```

--------------------------------

### Organizing Code Blocks

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Example of grouping related code and markdown content for better readability in literate programming files.

```julia
# ## Data Loading

x = load_data("file.csv")

# Preview the data:

head(x)

# ## Analysis

result = analyze(x)
```

--------------------------------

### Example: Multiple Tags for Data Cell

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Illustrates a markdown cell with multiple tags, including 'data', 'external', and 'slow'.

```julia
# %% [markdown] {"name": "data", "tags": ["data", "external", "slow"]}
# # Loading Data
#
# This section loads external data files
```

--------------------------------

### Apply Preprocessing Function with Literate.markdown

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/customprocessing.md

This example shows how to use the custom 'replace_includes' preprocessing function with Literate.markdown. The 'preprocess' argument takes the function, and the output will have 'include' statements replaced by their content.

```julia
Literate.markdown("examples.jl", "path/to/save/markdown";
                  name = "markdown_file_name", preprocess = replace_includes)
```

--------------------------------

### Jupyter Notebook Execute Result Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Shows the JSON structure for an execution result (return value of the last expression) in a Jupyter Notebook.

```json
{
  "output_type": "execute_result",
  "metadata": {},
  "execution_count": 1,
  "data": {
    "text/plain": ["3"],
    "image/png": "iVBORw0KG..."
  }
}

```

--------------------------------

### Example: Complex Metadata for Visualization Cell

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Demonstrates a cell with complex metadata including name, tags, collapsed state, and scrolled state.

```julia
# %% {"name": "plotting", "tags": ["visualization"], "collapsed": false, "scrolled": true}
# # Visualization
#
# Interactive plots follow
```

--------------------------------

### Jupyter Notebook Code Cell Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Shows the JSON structure for a code cell in a Jupyter Notebook, including source and execution details.

```json
{
  "cell_type": "code",
  "metadata": {},
  "source": ["x = 1 + 2"],
  "execution_count": 1,
  "outputs": []
}

```

--------------------------------

### Generate and Include a Julia Script

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/script.md

Generates a runnable Julia script from a source file and then includes it. This ensures that examples remain up-to-date with the script's content.

```julia
script_path = Literate.script("examples/tutorial.jl", "test"; name="tutorial_example")
include(script_path)
```

--------------------------------

### Using Literate.script in a Test Suite

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/script.md

Shows how `Literate.script` can be integrated into a Julia test suite (e.g., `test/runtests.jl`) to ensure that example scripts are generated correctly and remain functional.

```julia
# test/runtests.jl
using Literate

```

--------------------------------

### Generate Jupyter Notebook with Metadata

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/outputformats.md

This example demonstrates how to generate a Jupyter notebook with cell metadata using Literate.jl. The '%%' token is used to define cell type and metadata, enabling features like slide decks with RISE.

```julia
#nb # %% A slide [markdown] {"slideshow": {"slide_type": "slide"}}
# # Some title
#
# We're using `#nb` so the metadata is only included in notebook output

#nb %% A slide [code] {"slideshow": {"slide_type": "fragment"}}
x = 1//3
y = 2//5

#nb # %% A slide [markdown] {"slideshow": {"slide_type": "subslide"}}
# For more information about RISE, see [the docs](https://rise.readthedocs.io/en/stable/usage.html)
```

--------------------------------

### Using Literate Flavors in Configuration

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/flavors.md

Demonstrates how to specify markdown flavors using the `flavor` keyword argument to `Literate.markdown`.

```julia
using Literate
```

--------------------------------

### Configuring Code Fence for Quarto Flavor

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/outputformats.md

Demonstrates how to use the `codefence` argument to specify custom code fences (e.g., 5 backticks) when generating markdown, particularly useful for specific flavors like Quarto.

```julia
Literate.markdown("script.jl", "output.qmd", flavor=Literate.QuartoFlavor(), codefence=( `` `````, ````` ))
```

--------------------------------

### Filtering Syntax - Start of Line Tags

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Tags like '#md', '#nb', '#jl', and '#src' at the start of a line control inclusion in different output formats. The tag and following space are removed from the output.

```julia
#md x = 1  ## This is only in markdown (as a comment)
#nb x = 2  ## This is only in notebook
#jl x = 3  ## This is only in script
#src x = 4  ## This is removed from all outputs
```

--------------------------------

### mybinder URL Placeholder

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Shows how to use the @__BINDER_ROOT_URL__ placeholder for interactive notebooks on mybinder.

```julia
# [![Binder](...)](@__BINDER_ROOT_URL__/example.ipynb)
```

--------------------------------

### Configure Literate with Keyword Arguments

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/configuration.md

Pass configuration options as keyword arguments directly to Literate functions. Keyword arguments take precedence over dictionary values.

```julia
using Literate

Literate.markdown(
    "example.jl", 
    "output";
    flavor=Literate.DocumenterFlavor(),
    execute=true,
    name="my_example"
)
```

--------------------------------

### Hide Cells with nbconvert

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Use nbconvert to hide cells tagged with 'setup' during HTML conversion.

```bash
jupyter nbconvert --to html \
  --TagRemovePreprocessor.remove_cell_tags='["setup"]' \
  notebook.ipynb
```

--------------------------------

### Performance Optimization Tips

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/README.md

Shows different configurations for Literate.jl based on execution speed and error handling requirements.

```julia
# Fast: no execution
Literate.markdown("demo.jl", "output"; execute=false)

# Medium: conditional execution
Literate.markdown("demo.jl", "output"; execute=haskey(ENV, "CI"))

# Slow: execute everything, continue on errors
Literate.markdown("demo.jl", "output"; 
    execute=true, 
    continue_on_error=true
)
```

--------------------------------

### Example: Cell with Metadata Only

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

A cell marked with metadata, including tags, but without an explicit cell type.

```julia
# %% {"tags": ["hide_input"]}
# Just metadata, no cell type
```

--------------------------------

### nbviewer URL Placeholder

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Demonstrates the use of the @__NBVIEWER_ROOT_URL__ placeholder to link to notebooks on nbviewer.

```julia
# [View on nbviewer](@__NBVIEWER_ROOT_URL__/example.ipynb)
```

--------------------------------

### Jupyter Notebook Markdown Cell Example

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Illustrates the JSON structure for a markdown cell within a Jupyter Notebook.

```json
{
  "cell_type": "markdown",
  "metadata": {},
  "source": ["# Title\n", "Content here"]
}

```

--------------------------------

### Execute Notebook with Options

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/parsing.md

Executes a notebook dictionary with specified options. This is useful for running notebook code and capturing its output.

```julia
nb_dict = JSON.parsefile(notebook_path)
sb = Literate.sandbox()
b_dict = Literate.execute_notebook(
    nb_dict;
    inputfile="demo.jl",
    fake_source="demo.ipynb",
    softscope=true,
    continue_on_error=false
)
open(notebook_path, "w") do io
    JSON.print(io, nb_dict, 1)
end
```

--------------------------------

### Literate.DEFAULT_CONFIGURATION Documentation

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/outputformats.md

Displays the default configuration options for Literate.jl, including descriptions and default values. This is useful for understanding available settings.

```julia
Literate.DEFAULT_CONFIGURATION
```

--------------------------------

### Configure Notebook Output

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Shows configuration options specific to generating notebook output, such as enabling execution, soft scoping, and error handling.

```julia
Literate.notebook("demo.jl", "output";
    execute=true,
    softscope=true,
    continue_on_error=false
)
```

--------------------------------

### Markdown-Exclusive Code Block

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/fileformat.md

Lines starting with '#md ' are included only in markdown output. The token and the space are removed during preprocessing.

```julia
#md # ```@docs
#md # Literate.markdown
#md # Literate.notebook
#md # Literate.script
#md # ```
```

--------------------------------

### Configure Markdown Output

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Demonstrates specific configuration options for generating markdown output, including flavor, execution, code fences, and image formats.

```julia
Literate.markdown("demo.jl", "output";
    flavor=Literate.DocumenterFlavor(),
    execute=true,
    codefence="```julia" => "```",
    image_formats=[(MIME("image/svg+xml"), ".svg")]
)
```

--------------------------------

### Generated Markdown Output

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Example of markdown output generated by Literate from a Julia source file, showing filtered code.

```markdown
# Demo

This shows three formats

````julia
y = 3 + 4
println(x)
````
```

--------------------------------

### Configure Notebook Viewer Root URL

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/configuration.md

Use `nbviewer_root_url` to specify the URL to the repository as seen on nbviewer. This is auto-detected on CI.

```julia
Literate.markdown("example.jl", "docs";
    nbviewer_root_url="https://nbviewer.jupyter.org/github/user/repo/blob/gh-pages/dev"
)
```

--------------------------------

### Literate.sandbox

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/parsing.md

Creates a sandbox environment for executing notebook code. This helps isolate the execution context.

```APIDOC
## Function `Literate.sandbox`

### Description
Creates and returns a sandbox environment for executing code.

### Signature
```julia
sandbox()
```

### Returns
- A sandbox object (e.g., a Module) for isolated code execution.
```

--------------------------------

### Configure Script Output

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Illustrates configuration options for generating plain Julia scripts, including comment preservation and naming.

```julia
Literate.script("demo.jl", "output";
    keep_comments=true,
    name="example"
)
```

--------------------------------

### Configure Binder Root URL

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/configuration.md

Set `binder_root_url` to the URL of the repository as seen on mybinder. This is auto-detected on CI.

```julia
Literate.markdown("example.jl", "docs";
    binder_root_url="https://mybinder.org/v2/gh/user/repo/gh-pages?filepath=dev"
)
```

--------------------------------

### Markdown Execution with execute=true

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Demonstrates enabling code execution for Markdown output, with error handling and output capturing.

```julia
Literate.markdown("demo.jl", "docs";
    execute=true,
    continue_on_error=false
)
```

--------------------------------

### Troubleshooting: Metadata Not Appearing (Marker Position)

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Illustrates the correct placement of the metadata marker on the first line of a chunk to ensure it's recognized.

```julia
# Some markdown content

# %% [metadata]  ← Won't work, not first line
```

```julia
# %% [metadata]
# # Title
# Markdown content
```

--------------------------------

### Multiline Comments as Markdown

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/fileformat.md

Shows how Literate.jl handles multiline comments when the start and end tokens are on their own lines. These are rewritten to regular comments.

```julia
#= 
This multiline comment
is treated as markdown.
=#

#=====================
This is also markdown.
=====================#

```

--------------------------------

### Code Lines in Literate.jl

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

All lines not starting with '# ' are treated as executable Julia code. This ensures files remain valid Julia scripts.

```julia
x = 1 + 2
y = x * 3
println(y)
```

--------------------------------

### Markdown Lines in Literate.jl

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Lines starting with '# ' are interpreted as markdown content. This allows for rich text formatting within Julia scripts.

```julia
# # Main Title
#
# This is a paragraph of markdown.
# It can span multiple lines.
#
# Markdown features work normally:
# - **bold text**
# - *italic text*
# - [links](http://example.com)
# - `code snippets`
```

--------------------------------

### Ensuring Module Imports in Code Blocks

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/errors.md

Demonstrates how to include necessary `using` statements at the beginning of code blocks to resolve 'Module not found' errors in generated notebooks.

```julia
# # Example
#
# First, import required modules

using DataFrames, Plots

# Now use them
df = DataFrame(x=1:10)
```

--------------------------------

### Configure Literate with a Dictionary

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/configuration.md

Pass configuration options as a dictionary to Literate functions. This method is useful for setting multiple options at once.

```julia
using Literate

config = Dict(
    "flavor" => Literate.DocumenterFlavor(),
    "execute" => true,
    "name" => "my_example"
)

Literate.markdown("example.jl", "output"; config=config)
```

--------------------------------

### Repository Root URL Replacement with @__REPO_ROOT_URL__

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

The '@__REPO_ROOT_URL__' placeholder is automatically replaced with the repository root URL, useful for generating links in documentation.

```julia
# # Example: @__REPO_ROOT_URL__
```

--------------------------------

### Configure Image Formats for Markdown

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Shows how to configure the preferred image formats (SVG, PNG) for markdown output using `image_formats`.

```julia
Literate.markdown("demo.jl", "output";
    execute=true,
    image_formats=[(MIME("image/png"), ".png")]
)
```

--------------------------------

### Generate Markdown for Documenter.jl

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/README.md

Generates markdown files for use with Documenter.jl. Code execution is disabled as Documenter.jl handles @example blocks separately.

```julia
using Literate

# Generate markdown for Documenter.jl
Literate.markdown(
    "examples/tutorial.jl",
    "docs/src/generated";
    flavor=Literate.DocumenterFlavor(),
    execute=false  # Documenter executes @example blocks
)

```

--------------------------------

### Error Handling: Invalid JSON in Metadata

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook-metadata.md

Example of an invalid JSON format within the metadata section, which would cause a parsing error.

```julia
# %% [markdown] {"key": value}  # ← Missing quotes
# Would cause: JSON.parse error
```

--------------------------------

### Valid Syntax Rules for Literate Files

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Lists the essential syntax rules for creating valid Literate.jl files, including line prefixes, filter tag completeness, and chunk marker usage.

```julia
# 1. All lines start with `# ` for markdown or valid Julia code
# 2. Markdown lines must have space after `#`
# 3. Filter tags must be complete: `#md`, `#!nb`, etc.
# 4. Multiline comment start/end on own lines
# 5. Chunk markers (`#-`, `#+`) on their own lines
```

--------------------------------

### Correct Multiline Comment Syntax in Julia

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/errors.md

Ensures correct formatting for multiline comments in Julia, where start and end tokens must be on their own lines.

```julia
#= 
This is correct
=#
```

--------------------------------

### Create Interactive Jupyter Notebooks

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/00-START-HERE.md

Use Literate.notebook to generate Jupyter notebooks. Set execute=true to run code blocks and softscope=true for notebook-like scoping.

```julia
using Literate
Literate.notebook(
    "examples/analysis.jl",
    "notebooks";
    execute=true,
    softscope=true
)
```

--------------------------------

### Generated Script Output

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Example of a plain Julia script output generated by Literate from a Julia source file, with specific code lines filtered out.

```julia
x = 1 + 2
println(x)
```

--------------------------------

### Configure Quarto Publishing

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/configuration.md

Generate markdown for Quarto publishing using `Literate.markdown` with `QuartoFlavor` and `execute=false`, as Quarto handles execution.

```julia
using Literate

Literate.markdown(
    "report.jl",
    "output";
    flavor=Literate.QuartoFlavor(),
    execute=false  # Quarto handles execution
)

# Then run: quarto render report.qmd
```

--------------------------------

### Continued Code Blocks in Literate.jl

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

The '#+' marker indicates that the subsequent code chunk should be merged with the previous one, useful for Documenter.jl's @example blocks.

```julia
# Some code:
x = 1

#+

y = 2
```

--------------------------------

### Generate Script Output

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/outputformats.md

Generates a plain Julia script output from a Literate.jl source file. Lines starting with '# ' are removed, keeping only the executable code.

```julia
Literate.script("my_script.jl")
```

--------------------------------

### Render Quarto Markdown to HTML

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/outputformats.md

Renders a .qmd file into an HTML document using the Quarto CLI. This is a common step after converting a Literate.jl script to Quarto format.

```bash
quarto render my_script.qmd --to html
```

--------------------------------

### Markdown Output with Plain Text Result

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/outputformats.md

Shows an example where the evaluated code block's result is plain text and is included directly in the markdown output.

```julia
x = 1//3
```

--------------------------------

### Apply Preprocessing with 'preprocess'

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/configuration.md

Define a custom function to preprocess the file content before Literate parses it. Useful for replacing markers or modifying content.

```julia
function my_preprocess(content)
    replace(content, "@custom_macro" => "# Custom content")
end

Literate.markdown("example.jl", "output"; preprocess=my_preprocess)
```

--------------------------------

### Multiline Comment Blocks in Literate.jl

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Blocks enclosed by '#=' and '=#' on separate lines are converted into regular markdown comments. The start and end tokens must be on their own lines.

```julia
#=
This is a multiline comment.
It is treated as markdown
in the conversion.
=#
```

--------------------------------

### Quarto Cell Options with ##|

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/file-format.md

Demonstrates how Quarto cell options are specified using '##|' in Julia code, which are then transformed into '#|' directives for Quarto.

```julia
##| echo: false
##| warning: false
x = 1
```

--------------------------------

### Markdown Generation with Custom Code Fence

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/markdown.md

Specifies custom opening and closing fences for code blocks within the generated markdown. This example uses simple backticks for both.

```julia
using Literate
Literate.markdown(
    "examples/demo.jl", 
    "docs/src";
    codefence = "```julia" => "```"
)
```

--------------------------------

### Default Replacements in Script Output

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/script.md

Illustrates the placeholders that are automatically replaced in the generated script output. These include the script name, repository root URL, nbviewer URL, and mybinder URL.

```julia
# @__NAME__ — replaced with the `name` parameter (output filename)
# @__REPO_ROOT_URL__ — replaced with repository root URL
# @__NBVIEWER_ROOT_URL__ — replaced with nbviewer URL
# @__BINDER_ROOT_URL__ — replaced with mybinder URL
```

--------------------------------

### Soft Scoping Example in For Loop

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/notebook.md

Demonstrates how variable assignments within a for loop modify an outer scope variable when `softscope` is enabled (default for notebooks). No 'global' keyword is needed.

```julia
# This works in softscope mode:
x = 0
for i in 1:10
    x = i  # modifies outer x without 'global x'
end

```

--------------------------------

### Overriding edit_commit for Git Auto-Detection Failures

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/errors.md

Provides a fallback for when Git auto-detection fails (e.g., Git not installed, not in a repo). Use the `edit_commit` parameter to specify the branch name.

```julia
Literate.markdown("demo.jl", "docs"; edit_commit="main")
```

--------------------------------

### Generated Notebook Output

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Example of notebook output (Python syntax shown, but implies Julia code cells) generated by Literate from a Julia source file, showing filtered code.

```python
y = 3 + 4
println(x)
```

--------------------------------

### Creating Output Directory Before Markdown Generation

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/errors.md

Ensures the output directory exists before running Literate.markdown by using `mkpath` to create it if it doesn't.

```julia
using Literate

outputdir = "docs/src/generated"
mkpath(outputdir)
Literate.markdown("example.jl", outputdir)
```

--------------------------------

### Source with Different Outputs

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/output-formats.md

Presents a Julia source file demonstrating how different Literate output formats (markdown, notebook, script) can be generated from the same code, with specific lines filtered out for certain formats.

```julia
# # Demo
#
# This shows three formats

x = 1 + 2  #jl
y = 3 + 4  #!jl

println(x)
```

--------------------------------

### Add current date to documentation content

Source: https://github.com/fredrikekre/literate.jl/blob/master/docs/src/customprocessing.md

Use a `preprocess` function to dynamically insert the current date into your source files by replacing a placeholder. This is useful for including generation timestamps in your examples.

```julia
# # Example
# This example was generated DATEOFTODAY

x = 1 // 3

```

```julia
function update_date(content)
    content = replace(content, "DATEOFTODAY" => Date(now()))
    return content
end
```

```julia
Literate.markdown("input.jl", "outputdir"; preprocess = update_date)
```

--------------------------------

### Basic Literate.jl Source File Structure

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/README.md

Demonstrates the basic structure of a Literate.jl source file, showing how to mix markdown content with Julia code comments and executable code.

```julia
# # My Tutorial
#
# This is markdown content. Regular Julia comments work here.

x = 1 + 2  # This is code

# More markdown

println(x)  ## Double hash for code comments

```

--------------------------------

### Set Code Block Delimiters with 'codefence'

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/configuration.md

Specify the opening and closing delimiters for code blocks in markdown output using a Pair of strings. Defaults vary by flavor.

```julia
Literate.markdown("example.jl", "output"; 
    codefence="```julia" => "```"
)
```

--------------------------------

### Literate.script

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/README.md

Generates plain Julia script (.jl) files from a Julia source file. This function is useful for creating executable examples or standalone scripts. Code execution is not typically used in this context.

```APIDOC
## Literate.script

### Description
Generates plain Julia script (.jl) files from a Julia source file. This function is useful for creating executable examples or standalone scripts. Code execution is not typically used in this context.

### Method
`Literate.script(input_file, output_dir; kwargs...)
`

### Parameters
#### Path Parameters
- **input_file** (string) - Required - Path to the input Julia source file.
- **output_dir** (string) - Required - Directory where the generated script file will be saved.

#### Keyword Arguments
- **kwargs** - Additional keyword arguments passed to the underlying generation functions.

### Request Example
```julia
using Literate

Literate.script("examples/myscript.jl", "scripts")
```

### Response
Generates a plain Julia script file in the specified output directory.
```

--------------------------------

### Generate Markdown for README with CommonMark Flavor

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/configuration.md

Generate markdown for a README file using `Literate.markdown` with `CommonMarkFlavor` and `execute=true`. Set `credit=false` to disable attribution.

```julia
using Literate

Literate.markdown(
    "examples/README.jl",
    ".";
    flavor=Literate.CommonMarkFlavor(),
    execute=true,
    credit=false
)
```

--------------------------------

### Documenter.jl Markdown Flavor

Source: https://github.com/fredrikekre/literate.jl/blob/master/_autodocs/api-reference/flavors.md

Outputs markdown specifically formatted for Documenter.jl. It includes features like `@example` blocks, `@meta` blocks with `EditURL`, and support for `#hide` directives. Use when building documentation with Documenter.jl.

```julia
struct DocumenterFlavor <: AbstractFlavor end
```

```julia
Literate.markdown("example.jl", "output"; flavor=Literate.DocumenterFlavor())
```