Tutorial

julia> using Base.Meta # `nothing` shouldn't be displayed.

julia> Meta
Base.Meta

julia> a = 1
1

julia> b = 2;

julia> a + b
3

a = 1
b = 2
a + b

# output

3

DocTestSetup =
    quote
        using Documenter
        using Random
        Random.seed!(1)
    end

a = 1
b = 2
a / b

# output

0.5

julia> a = 1;

julia> b = 2
2

julia> a / b
0.5

import Markdown
code = string(sprint(Base.banner), "julia>")
Markdown.MD([Markdown.Code(code)])

rand(20, 20)

julia> # First definition.
       function f(x, y)
           x + y
       end
       #
       # Second definition.
       #
       struct T
           x
       end

julia> @isdefined(f), @isdefined(T) # Check for both definitions.
(true, true)

julia> import Base

julia> using Base.Meta

julia> r = isexpr(:(using Base.Meta), :using); # Discarded result.

julia> !r
false

julia> for i = 1:5
           println(i)
       end
1
2
3
4
5

julia> println("Printing with semi-comma ending.");
Printing with semi-comma ending.

julia> div(1, 0)
ERROR: DivideError: integer division error
[...]

julia> println("a"); # Semi-colons *not* on the last expression shouldn't suppress output.
       println(1)    # ...
       2             # ...
a
1
2

julia> println("a"); # Semi-colons *not* on the last expression shouldn't suppress output.
       println(1)    # ...
       2;            # Only those in the last expression.
a
1

a = 1
b = 2; # Semi-colons don't affect script doctests.

# output

2

f(x) = (sleep(x); x)
@time f(0.1);

f(0.01)
div(1, 0)

Make sure that stdout is in the right place (#484):

println("---") === nothing
versioninfo()

1 + 2
nothing

Including images with `MIME`

If show(io, ::MIME, x) is overloaded for a particular type then @example blocks can show the SVG, HTML/JS/CSS, PNG, JPEG, GIF or WebP image as appropriate in the output.

Assuming the following type and method live in the InlineSVG module

struct SVG
    code :: String
end
Base.show(io, ::MIME"image/svg+xml", svg::SVG) = write(io, svg.code)

.. then we we can invoke and show them with an @example block:

module InlineSVG
export SVG
mutable struct SVG
    code :: String
end
Base.show(io, ::MIME"image/svg+xml", svg::SVG) = write(io, svg.code)
end # module

Without xmlns tag:

using .InlineSVG
SVG("""
<svg width="82" height="76">
  <g style="stroke-width: 3">
    <circle cx="20" cy="56" r="16" style="stroke: #cb3c33; fill: #d5635c" />
    <circle cx="41" cy="20" r="16" style="stroke: #389826; fill: #60ad51" />
    <circle cx="62" cy="56" r="16" style="stroke: #9558b2; fill: #aa79c1" />
  </g>
</svg>
""")

With xmlns tag:

using .InlineSVG
SVG("""
<svg width="82" height="76" xmlns="http://www.w3.org/2000/svg">
  <g style="stroke-width: 3">
    <circle cx="20" cy="56" r="16" style="stroke: #cb3c33; fill: #d5635c" />
    <circle cx="41" cy="20" r="16" style="stroke: #389826; fill: #60ad51" />
    <circle cx="62" cy="56" r="16" style="stroke: #9558b2; fill: #aa79c1" />
  </g>
</svg>
""")

With single quotes:

using .InlineSVG
SVG("""
<svg width='82' height='76' xmlns='http://www.w3.org/2000/svg'>
  <g style='stroke-width: 3'>
    <circle cx='20' cy='56' r='16' style='stroke: #cb3c33; fill: #d5635c' />
    <circle cx='41' cy='20' r='16' style='stroke: #389826; fill: #60ad51' />
    <circle cx='62' cy='56' r='16' style='stroke: #9558b2; fill: #aa79c1' />
  </g>
</svg>
""")

With a mixture of single and double quotes:

using .InlineSVG
SVG("""
<svg width='82' height='76' xmlns='http://www.w3.org/2000/svg'>
  <g style='stroke-width: 3'>
    <circle cx='20' cy='56' r='16' style='stroke: #cb3c33; fill: #d5635c' />
    <circle cx="41" cy="20" r="16" style="stroke: #389826; fill: #60ad51" />
    <circle cx='62' cy='56' r='16' style='stroke: #9558b2; fill: #aa79c1' />
  </g>
</svg>
""")

With viewBox and without xmlns, making the svg really large to test that it is resized correctly:

using .InlineSVG
SVG("""
<svg width="8200" height="7600" viewBox="0 0 82 76">
  <g style="stroke-width: 3">
    <circle cx="20" cy="56" r="16" style="stroke: #cb3c33; fill: #d5635c" />
    <circle cx="41" cy="20" r="16" style="stroke: #389826; fill: #60ad51" />
    <circle cx="62" cy="56" r="16" style="stroke: #9558b2; fill: #aa79c1" />
  </g>
</svg>
""")

Without viewBox and without xmlns, making the svg really large to test that it is resized correctly:

using .InlineSVG
SVG("""
<svg width="8200" height="7600">
  <g style="stroke-width: 300">
    <circle cx="2000" cy="5600" r="1600" style="stroke: #cb3c33; fill: #d5635c" />
    <circle cx="4100" cy="2000" r="1600" style="stroke: #389826; fill: #60ad51" />
    <circle cx="6200" cy="5600" r="1600" style="stroke: #9558b2; fill: #aa79c1" />
  </g>
</svg>
""")

Note: we can't define the show method in the @example block due to the world age counter in Julia 0.6 (Documenter's makedocs is not aware of any of the new method definitions happening in evals).

We can also show SVG images with interactivity via the text/html MIME to display output that combines HTML, JS and CSS. Assume the following type and method live in the InlineHTML module

struct HTML
    code::String
end
Base.show(io, ::MIME"text/html", html::HTML) = write(io, read(html.code))

.. then we can invoke and show them with an @example block (try mousing over the circles to see the applied style):

module InlineHTML
mutable struct HTML
    code::String
end
Base.show(io, ::MIME"text/html", html::HTML) = write(io, html.code)
end # module

using .InlineHTML
InlineHTML.HTML("""
<script>
  function showStyle(e) {
    document.querySelector("#inline-html-style").innerHTML = e.getAttribute('style');
  }
</script>
<svg width="100%" height="76">
  <g style="stroke-width: 3">
    <circle cx="20" cy="56" r="16" style="stroke: #cb3c33; fill: #d5635c" onmouseover="showStyle(this)"/>
    <circle cx="41" cy="20" r="16" style="stroke: #389826; fill: #60ad51" onmouseover="showStyle(this)"/>
    <circle cx="62" cy="56" r="16" style="stroke: #9558b2; fill: #aa79c1" onmouseover="showStyle(this)"/>
    <text id="inline-html-style" x="90", y="20"></text>
  </g>
</svg>
""")

The same mechanism also works for PNG files. Assuming again the following type and method live in the InlinePNG module

struct PNG
    filename::String
end
Base.show(io, ::MIME"image/png", png::PNG) = write(io, read(png.filename))

.. then we can invoke and show them with an @example block:

module InlinePNG
export PNG
mutable struct PNG
    filename::String
end
Base.show(io, ::MIME"image/png", png::PNG) = write(io, read(png.filename))
end # module

using Documenter
using .InlinePNG
PNG(joinpath(dirname(pathof(Documenter)), "..", "test", "examples", "images", "logo.png"))

.. and JPEG, GIF and WebP files:

module InlineWEBPGIFJPEG
export WEBP, GIF, JPEG
mutable struct WEBP
    filename :: String
end
Base.show(io, ::MIME"image/webp", image::WEBP) = write(io, read(image.filename))
mutable struct GIF
    filename :: String
end
Base.show(io, ::MIME"image/gif", image::GIF) = write(io, read(image.filename))
mutable struct JPEG
    filename :: String
end
Base.show(io, ::MIME"image/jpeg", image::JPEG) = write(io, read(image.filename))
end # module

using Documenter
using .InlineWEBPGIFJPEG
WEBP(joinpath(dirname(pathof(Documenter)), "..", "test", "examples", "images", "logo.webp"))

GIF(joinpath(dirname(pathof(Documenter)), "..", "test", "examples", "images", "logo.gif"))

JPEG(joinpath(dirname(pathof(Documenter)), "..", "test", "examples", "images", "logo.jpg"))

Interacting with external files

You can also write output files and then refer to them in the document:

open("julia.svg", "w") do io
    write(io, """
    <svg width="82" height="76" xmlns="http://www.w3.org/2000/svg">
      <g style="stroke-width: 3">
        <circle cx="20" cy="56" r="16" style="stroke: #cb3c33; fill: #d5635c" />
        <circle cx="41" cy="20" r="16" style="stroke: #389826; fill: #60ad51" />
        <circle cx="62" cy="56" r="16" style="stroke: #9558b2; fill: #aa79c1" />
      </g>
    </svg>
    """)
end

Download data.csv.

Links in headers

... are dropped in the navigation links.

Embedding raw HTML

Below is a nicely rendered version of ^D:

<kbd>Ctrl</kbd> + <kbd>D</kbd>

Tables

object	implemented	value
`A`	✓	10.00
`BB`	✓	1000000.00

With explicit alignment.

object	implemented	value
`A`	✓	10.00
`BB`	✓	1000000.00

Customizing assets

The following example only works on the deploy build where

mathengine = MathJax2(Dict(
    :TeX => Dict(
        :equationNumbers => Dict(:autoNumber => "AMS"),
        :Macros => Dict(
            :ket => ["|#1\\rangle", 1],
            :bra => ["\\langle#1|", 1],
            :pdv => ["\\frac{\\partial^{#1} #2}{\\partial #3^{#1}}", 3, ""],
        ),
    ),
)),

or on MathJax v3, the physics package can be loaded:

mathengine = MathJax3(Dict(
    :loader => Dict("load" => ["[tex]/physics"]),
    :tex => Dict(
        "inlineMath" => [["\$","\$"], ["\\(","\\)"]],
        "tags" => "ams",
        "packages" => ["base", "ams", "autoload", "physics"],
    ),
)),

$$\bra{x}\ket{y} \pdv[n]{f}{x}$$

The following at-raw block only renders correctly on the deploy build, where

assets = [
  asset("https://fonts.googleapis.com/css?family=Nanum+Brush+Script&display=swap", class=:css),
  ...
]

<div style="font-family: 'Nanum Brush Script'; text-align: center; font-size: xx-large;">
Hello World!
<br />
Written in <a href="https://fonts.google.com/specimen/Nanum+Brush+Script">Nanum Brush Script.</a>
</div>

Handling of `text/latex`

You can define a type that has a Base.show method for the text/latex MIME:

struct LaTeXEquation
    code :: String
end
Base.show(io, ::MIME"text/latex", latex::LaTeXEquation) = write(io, latex.code)
nothing # hide

In an @example or @eval block, it renders as an equation:

LaTeXEquation(raw"Foo $x^2$ bar.")

Documenter also supports having the LaTeX text being already wrapped in \[ ... \]:

LaTeXEquation(raw"\[\left[ \begin{array}{rr}x&2 x\end{array}\right]\]")

or wrapped in $$ ... $$:

LaTeXEquation(raw"$$\begin{bmatrix} 1 & 2 \\ 3 & 4 \end{bmatrix}$$")

Extra tests for handling multi-line equations (#1518):

LaTeXEquation(raw"""
\[
    \left[
        \begin{array}{rr}
            x & 2x
        \end{array}
    \right]
\]
""")

LaTeXEquation(raw"""$$
\begin{bmatrix}
    1 & 2 \\
    3 & 4
\end{bmatrix}
$$""")

Without raw"" strings we have to double-escape our \ and $:

LaTeXEquation("\\[\\left[\\begin{array}{rr} x & 2x \\\\ \n y & y \\end{array}\\right]\\]")

LaTeXEquation("\$\$\\begin{bmatrix} 1 & 2 \\\\ \n 3 & 4 \\end{bmatrix}\$\$")

Inline-ish text/latex bytes:

LaTeXEquation("\$ x_{1} + x_{2} \$")

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

tutorial.md

tutorial.md

Tutorial

Including images with `MIME`

Interacting with external files

Links in headers

Embedding raw HTML

Tables

Customizing assets

Handling of `text/latex`

Videos

Files

tutorial.md

Latest commit

History

tutorial.md

File metadata and controls

Tutorial

Including images with MIME

Interacting with external files

Links in headers

Embedding raw HTML

Tables

Customizing assets

Handling of text/latex

Videos

Including images with `MIME`

Handling of `text/latex`