<NME> syntax.md
<BEF> # Syntax

This section of the manual describes the syntax used by Documenter to build documentation.
For supported Markdown syntax, see the [documentation for the Markdown standard library in the Julia manual](https://docs.julialang.org/en/v1/stdlib/Markdown/).

Pages = ["syntax.md"]
```

## `{docs}`

Splice one or more docstrings into a document in place of the code block, i.e.

```
    {docs}
    Documenter
    makedocs
    deploydocs
```

This block type is evaluated within the `CurrentModule` module if defined, otherwise within
`current_module()`, and so each object listed in the block should be visible from that
This block type is evaluated within the `CurrentModule` module if defined, otherwise within
`Main`, and so each object listed in the block should be visible from that
module. Undefined objects will raise warnings during documentation generation and cause the
code block to be rendered in the final document unchanged.

Objects may not be listed more than once within the document. When duplicate objects are
detected an error will be raised and the build process will be terminated.

To ensure that all docstrings from a module are included in the final document the `modules`
keyword for [`makedocs`](@ref) can be set to the desired module or modules, i.e.

```julia
makedocs(
    modules = [Documenter],
)
```
called. If `modules` is not defined then no warnings are printed, even if a document has
missing docstrings.

## `{autodocs}`

Automatically splices all docstrings from the provided modules in place of the code block.
This is equivalent to manually adding all the docstrings in a `{docs}` block.

````markdown
```
{autodocs}
Modules = [Foo, Bar]
Order   = [:function, :type]
```
````

The above `{autodocs}` block adds all the docstrings found in modules `Foo` and `Bar` that
refer to functions or types to the document.

Each module is added in order and so all docs from `Foo` will appear before those of `Bar`.
`foo(::Int64)` will match it in an at-docs block (even though `Int64 <: Integer <: Number`).
The only way you can splice that docstring is by listing exactly `foo(::Integer)` in
the at-docs block.


## `@autodocs` block

Automatically splices all docstrings from the provided modules in place of the code block.
This is equivalent to manually adding all the docstrings in a `@docs` block.

````markdown
```@autodocs
Modules = [Foo, Bar, Bar.Baz]

**Note**

When more complex sorting and filtering is needed then use `{docs}` to define it explicitly.

## `{ref}`

Used in markdown links as the URL to tell Documenter to generate a cross-reference
automatically. The text part of the link can be either a docstring or header name.

```markdown
# Syntax

... [`makedocs`]({ref}) ...

# Functions

    {docs}
    makedocs

... [Syntax]({ref}) ...
```

Plain text in the "text" part of a link will cross-reference a header, while text in
backticks will cross-reference a docstring from a `{docs}` block. The text should match the
name of the header exactly.

`{ref}`s may refer to docstrings or headers on different pages as well as the current page
using the same syntax.

Note that depending on what the `CurrentModule` is set to, a docstring `{ref}` may need to
be prefixed by the module which defines it.

**Duplicate Headers**

In some cases a document may contain multiple headers with the same name, but on different
pages or of different levels. To allow `{ref}` to cross-reference a duplicate header it must
be given a name as in the following example

```markdown
# [Header]({ref#my-custom-header-name})

...

## Header

... [Custom Header]({ref#my-custom-header-name}) ...
```

The link that wraps the named header is removed in the final document. The text for a named
`{ref#...}` does not need to match the header that it references. Named `{ref#...}`s may
refer to headers on different pages in the same way as unnamed ones do.

Duplicate docstring references do not occur since splicing the same docstring into a
document more than once is disallowed.

## `{meta}`

This block type is used to define metadata key/value pairs that can be used elsewhere in the
page. Currently `CurrentModule` and `DocTestSetup` are the only recognised keys.

```
    {meta}
    CurrentModule = FooBar
    DocTestSetup  = quote
        using MyPackage
    end
```

Note that `{meta}` blocks are always evaluated with the `current_module()`, which is
typically `Main`.

See [Setup Code](@ref) section of the Doctests page for an explanation of `DocTestSetup`.

## `{index}`

Generates a list of links to docstrings that have been spliced into a document. The only
valid setting is currently `Pages = ...`.

```
    {index}
    Pages = ["foo.md"]
```

When `Pages` is not provided all pages in the document are included.

Note that the `Pages` value can be any valid Julia code and so can be something more complex
that an array literal if a large number of pages must be included, i.e.

```
    {index}
    Pages = map(file -> joinpath("man", file), readdir("man"))
```

It should be noted though that in this case `Pages` may not be sorted in the order that is
expected by the user. Try to stick to array literals for `Pages` as much as possible.

## `{contents}`

Generates a nested list of links to document sections. Valid settings are `Pages` and `Depth`.

```
    {contents}
    Pages = ["foo.md"]
    Depth = 5
```

As with `{index}` if `Pages` is not provided then all pages are included. The default
`Depth` value is `2`.

## `{example}`

Evaluates the code block and inserts the result into the final document along with the
original source code.

```
    {example}
    a = 1
    b = 2
    a + b
```

The above `{example}` block will splice the following into the final document

````markdown
```julia
* [On Something](@ref)
* [The section about something.](@ref "On Something")
```

This can be useful to avoid having to write fully qualified names for references that
are not imported into the current module, or when the text displayed in the link is
used to add additional meaning to the surrounding text, such as

```markdown
Use [`for i = 1:10 ...`](@ref for) to loop over all the numbers from 1 to 10.
```

!!! note

    Named doc `@ref`s should be used sparingly since writing unqualified names may, in some
    cases, make it difficult to tell *which* function is being referred to in a particular
`# hide` comments can be appended to lines that should not be rendered, i.e.

````markdown
```julia
{example}
srand(1) # hide
A = rand(3, 3)
b = [1, 2, 3]
be given a name as in the following example
```
````

Note that appending `# hide` to every line in an `{example}` block will result in the block
being hidden in the rendered document. The results block will still be rendered though.

**`STDOUT` and `STDERR`**

The Julia output streams are redirected to the results block when evaluating `{example}`
blocks in the same way as when running doctest code blocks.

**`nothing` Results**

When the `{example}` block evaluates to `nothing` then the second block is not displayed.
Only the source code block will be shown in the rendered document. Note that if any output
from either `STDOUT` or `STDERR` is captured then the results block will be displayed even
if `nothing` is returned.

**Named `{example}` Blocks**

By default `{example}` blocks are run in their own anonymous `Module`s to avoid side-effects
between blocks. To share the same module between different blocks on a page the `{example}`
can be named with the following syntax

````markdown
```julia
{example 1}
a = 1
```

```julia
{example 1}
println(a)
```
````

The name can be any text, not just integers as in the example above, i.e. `{example foo}`.

Named `{example}` blocks can be useful when generating documentation that requires
intermediate explanation or multimedia such as plots as illustrated in the following example

````markdown
First we define some functions

```julia
{example 1}
using PyPlot # hide
f(x) = sin(2x) + 1
g(x) = cos(x) - x
DocTestFilters = [r"Stacktrace:[\s\S]+"]

and then we plot `f` over the interval from ``-π`` to ``π``

```julia
{example 1}
x = linspace(-π, π)
plot(x, f(x), color = "red")
savefig("f-plot.svg"); nothing # hide

Generates a list of links to docstrings that have been spliced into a document. Valid
settings are `Pages`, `Modules`, and `Order`. For example:

and then we do the same with `g`

```julia
{example 1}
plot(x, g(x), color = "blue")
savefig("g-plot.svg"); nothing # hide
```
````
![](g-plot.svg)
````

Note that `{example}` blocks are evaluated within the directory of `build` where the file
will be rendered . This means than in the above example `savefig` will output the `.svg`
files into that directory. This allows the images to be easily referenced without needing to
worry about relative paths.

`{example}` blocks automatically define `ans` which, as in the Julia REPL, is bound to the
value of the last evaluated expression. This can be useful in situations such as the
following one where where binding the object returned by `plot` to a named variable would
look out of place in the final rendered documentation:

````markdown
```julia
{example}
using Gadfly # hide
plot([sin, x -> 2sin(x) + x], -2π, 2π)
draw(SVG("plot.svg", 6inch, 4inch), ans); nothing # hide
````

![](plot.svg)
````

## `{repl}`

These are similar to `{example}` blocks, but adds a `julia> ` prompt before each toplevel
expression. `;` and `# hide` syntax may be used in `{repl}` blocks in the same way as in the
Julia REPL and `{example}` blocks.

````markdown
```julia
{repl}
a = 1
b = 2
a + b
As with `@index` if `Pages` is not provided then all pages are included. The default
`Depth` value is `2`, i.e. header levels 1 and 2 are included. `Depth` also accepts
`UnitRange`s, to make it possible to configure also the minimum header level to be shown.
`Depth = 2:3` can be used to include only headers with levels 2-3, for example.

## `@example` block

Evaluates the code block and inserts the result of the last expression into the final document along with the
original source code. If the last expression returns `nothing`, the `stdout`
and `stderr` streams of the whole block are inserted instead. A semicolon `;`
at the end of the last line has no effect.

````markdown
```@example
a = 1
```
````

Named `{repl <name>}` blocks behave in the same way as named `{example <name>}` blocks.

## `{eval}`

Evaluates the contents of the block and inserts the resulting value into the final document.

In the following example we use the PyPlot package to generate a plot and display it in the
final document.

```
    {eval}
    using PyPlot

    x = linspace(-π, π)
    y = sin(x)

    plot(x, y, color = "red")
    savefig("plot.svg")

    nothing

![](plot.svg)
```

Note that each `{eval}` block evaluates its contents within a separate module. When
evaluating each block the present working directory, `pwd`, is set to the directory in
`build` where the file will be written to.

````markdown
```@example
import Random # hide

**Note**

In most cases `{example}` is preferred over `{eval}`. Just like in normal Julia code where
`eval` should be only be considered as a last resort, `{eval}` should be treated in the same
way.

Note that appending `# hide` to every line in an `@example` block will result in the block
being hidden in the rendered document. The results block will still be rendered though.
`@setup` blocks are a convenient shorthand for hiding an entire block, including the output.

**Empty Outputs**

When an `@example` block returns `nothing`, the results block will show instead
the `stdout` and `stderr` streams produced by the whole block. If these are
empty, the results block is not displayed at all; only the source code block
will be shown in the rendered document.

**Named `@example` Blocks**

By default `@example` blocks are run in their own anonymous `Module`s to avoid side-effects
between blocks. To share the same module between different blocks on a page the `@example`
can be named with the following syntax

````markdown
```@example 1
a = 1
```

```@example 1
println(a)
```
````

The name can be any text, not just integers as in the example above, i.e. `@example foo`.

Named `@example` blocks can be useful when generating documentation that requires
intermediate explanation or multimedia such as plots as illustrated in the following example

````markdown
First we define some functions

```@example 1
using PyPlot # hide
f(x) = sin(2x) + 1
g(x) = cos(x) - x
```

and then we plot `f` over the interval from ``-π`` to ``π``

```@example 1
x = range(-π, π; length=50)
plot(x, f.(x), color = "red")
savefig("f-plot.svg"); nothing # hide
```

![](f-plot.svg)

and then we do the same with `g`

```@example 1
plot(x, g.(x), color = "blue")
savefig("g-plot.svg"); nothing # hide
```

![](g-plot.svg)
````

Note that `@example` blocks are evaluated within the directory of `build` where the file
will be rendered . This means that in the above example `savefig` will output the `.svg`
files into that directory. This allows the images to be easily referenced without needing to
worry about relative paths.

!!! info
    If you use [Plots.jl](https://github.com/JuliaPlots/Plots.jl) with the default backend
    [GR.jl](https://github.com/jheinen/GR.jl), you will likely see warnings like
    ```
    qt.qpa.xcb: could not connect to display
    qt.qpa.plugin: Could not load the Qt platform plugin "xcb" in "" even though it was found.
    ```
    To fix these, you need to set the environment variable `GKSwstype` to `100`. For example,
    if you use GitHub actions to build your documentation, you can modify the default script to
    ```
    - name: Build and deploy
      env:
        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token
        DOCUMENTER_KEY: ${{ secrets.DOCUMENTER_KEY }} # For authentication with SSH deploy key
        GKSwstype: "100" # https://discourse.julialang.org/t/generation-of-documentation-fails-qt-qpa-xcb-could-not-connect-to-display/60988
      run: julia --project=docs --color=yes docs/make.jl
    ```
    Alternatively, you can set this environment variable directly in Julia using
    ```julia
    ENV["GKSwstype"] = "100"
    ```

`@example` blocks automatically define `ans` which, as in the Julia REPL, is bound to the
value of the last evaluated expression. This can be useful in situations such as the
following one where binding the object returned by `plot` to a named variable would
look out of place in the final rendered documentation:

````markdown
```@example
using Gadfly # hide
plot([sin, x -> 2sin(x) + x], -2π, 2π)
draw(SVG("plot.svg", 6inch, 4inch), ans); nothing # hide
```

![](plot.svg)
````

**Color output**

`@example` blocks support colored text output by mapping [ANSI escape codes]
(https://en.wikipedia.org/wiki/ANSI_escape_code) to HTML. For example, this block:
````markdown
```@example
printstyled("Here are some colors:\n"; color=:red, bold=true)
for color in 0:15
    print("\e[38;5;$(color);48;5;$(color)m  ")
    print("\e[49m", lpad(color, 3), " ")
    color % 8 == 7 && println()
end
print("\e[m")
```
````
results in the following input and output blocks:
```@example
printstyled("Here are some colors:\n"; color=:red, bold=true)
for color in 0:15
    print("\e[38;5;$(color);48;5;$(color)m  ")
    print("\e[49m", lpad(color, 3), " ")
    color % 8 == 7 && println()
end
print("\e[m")
```

!!! note "Disable color output"
    To disable color output globally, pass `ansicolor=false` to [`Documenter.HTML`](@ref),
    and to disable locally for the block, use `ansicolor=false`, like so:

    ````markdown
    ```@example; ansicolor=false
    printstyled("hello, world"; color=:red, bold=true)
    ```
    ````

**Delayed Execution of `@example` Blocks**

`@example` blocks accept a keyword argument `continued` which can be set to `true` or `false`
(defaults to `false`). When `continued = true` the execution of the code is delayed until the
next `continued = false` `@example`-block. This is needed for example when the expression in
a block is not complete. Example:

````markdown
```@example half-loop; continued = true
for i in 1:3
    j = i^2
```
Some text explaining what we should do with `j`
```@example half-loop
    println(j)
end
```
````

Here the first block is not complete -- the loop is missing the `end`. Thus, by setting
`continued = true` here we delay the evaluation of the first block, until we reach the
second block. A block with `continued = true` does not have any output.

## `@repl` block

These are similar to `@example` blocks, but add a `julia> ` prompt before each toplevel
expression and do not fail upon encountering an error.
The `# hide` syntax may be used in `@repl` blocks in the same way
as in `@example` blocks. Furthermore, a semicolon `;` at the end of a line will
suppress the output as in the Julia REPL.

````markdown
```@repl
a = 1
b = 2
a + b
```
````

will generate

````markdown
```julia
julia> a = 1
1

julia> b = 2
2

julia> a + b
3
```
````

And likewise

````markdown
```@repl
sqrt(-1)
```
````

will generate

````markdown
```julia
julia> sqrt(-1)
ERROR: DomainError with -1.0:
sqrt will only return a complex result if called with a complex argument. Try sqrt(Complex(x)).
```
````

`@repl` blocks support colored output, just like `@example` blocks. The following block
````markdown
```@repl
printstyled("hello, world"; color=:red, bold=true)
```
````
gives
```@repl
printstyled("hello, world"; color=:red, bold=true)
```
!!! note "Disable color output"
    To disable color output globally, pass `ansicolor=false` to [`Documenter.HTML`](@ref),
    and to disable locally for the block, use `ansicolor=false`, like so:

    ````markdown
    ```@repl; ansicolor=false
    printstyled("hello, world"; color=:red, bold=true)
    ```
    ````

Named `@repl <name>` blocks behave in the same way as named `@example <name>` blocks.

!!! note
    The working directory, `pwd`, is set to the directory in `build` where the file
    will be written to, and the paths in `include` calls are interpreted to be relative to
    `pwd`.  This can be customized with the `workdir` keyword of [`makedocs`](@ref).

!!! note "Soft vs hard scope"

    Julia 1.5 changed the REPL to use the _soft scope_ when handling global variables in
    `for` loops etc. When using Documenter with Julia 1.5 or above, Documenter uses the soft
    scope in `@repl`-blocks and REPL-type doctests.

## `@setup <name>` block

These are similar to `@example` blocks, but both the input and output are hidden from the
final document. This can be convenient if there are several lines of setup code that need to be
hidden.

!!! note

    Unlike `@example` and `@repl` blocks, `@setup` requires a `<name>` attribute to associate it
    with downstream `@example <name>` and `@repl <name>` blocks.

````markdown
```@setup abc
using RDatasets
using DataFrames
iris = dataset("datasets", "iris")
```

```@example abc
println(iris)
```
````


## `@eval` block

Evaluates the contents of the block and inserts the resulting value into the final document,
unless the last expression evaluates to `nothing`.

In the following example we use the PyPlot package to generate a plot and display it in the
final document.

````markdown
```@eval
using PyPlot

x = range(-π, π; length=50)
y = sin.(x)

plot(x, y, color = "red")
savefig("plot.svg")

nothing
```

![](plot.svg)
````

Instead of returning `nothing` in the example above we could have returned a new
`Markdown.MD` object through `Markdown.parse`. This can be more appropriate when the
filename is not known until evaluation of the block itself.

Another example is to generate markdown tables from machine readable data formats such as CSV or JSON.

````markdown
```@eval
using CSV
using Latexify
df = CSV.read("table.csv")
mdtable(df,latex=false)
```
````

Which will generate a markdown version of the CSV file table.csv and render it in the output format.

The final expression in an `@eval` block must be either `nothing` or a valid `Markdown.MD`
object. Other objects will generate a warning and will be rendered in text form as a code block,
but this behavior can change and should not be relied upon.

Note that each `@eval` block evaluates its contents within a separate module. When
evaluating each block the present working directory, `pwd`, is set to the directory in
`build` where the file will be written to, and the paths in `include` calls are interpreted
to be relative to `pwd`.

!!! note

    In most cases `@example` is preferred over `@eval`. Just like in normal Julia code where
    `eval` should only be considered as a last resort, `@eval` should be treated in the
    same way.


## `@raw <format>` block

Allows code to be inserted into the final document verbatim. E.g. to insert custom HTML or
LaTeX code into the output.

The `format` argument is mandatory and Documenter uses it to determine whether a particular
block should be copied over to the output or not. Currently supported formats are `html`
and `latex`, used by the respective writers. A `@raw` block whose `format` is not
recognized is usually ignored, so it is possible to have a raw block for each output format
without the blocks being duplicated in the output.

The following example shows how SVG code with custom styling can be included into documents
using the `@raw` block.

````markdown
```@raw html
<svg style="display: block; margin: 0 auto;" width="5em" heigth="5em">
	<circle cx="2.5em" cy="2.5em" r="2em" stroke="black" stroke-width=".1em" fill="red" />
</svg>
```
````

It will show up as follows, with code having been copied over verbatim to the HTML file.

```@raw html
<svg style="display: block; margin: 0 auto;" width="5em" heigth="5em">
	<circle cx="2.5em" cy="2.5em" r="2em" stroke="black" stroke-width=".1em" fill="red" />
    (SVG)
</svg>
```

<MSG> Fix docs to match syntax changes.

<DFF> @@ -6,16 +6,17 @@ This section of the manual describes the syntax used by Documenter to build docu
 Pages = ["syntax.md"]
 ```
 
-## `{docs}`
+## `@docs` block
 
 Splice one or more docstrings into a document in place of the code block, i.e.
 
+````markdown
+```@docs
+Documenter
+makedocs
+deploydocs
 ```
-    {docs}
-    Documenter
-    makedocs
-    deploydocs
-```
+````
 
 This block type is evaluated within the `CurrentModule` module if defined, otherwise within
 `current_module()`, and so each object listed in the block should be visible from that
@@ -38,20 +39,19 @@ which will cause any unlisted docstrings to raise warnings when [`makedocs`](@re
 called. If `modules` is not defined then no warnings are printed, even if a document has
 missing docstrings.
 
-## `{autodocs}`
+## `@autodocs` block
 
 Automatically splices all docstrings from the provided modules in place of the code block.
-This is equivalent to manually adding all the docstrings in a `{docs}` block.
+This is equivalent to manually adding all the docstrings in a `@docs` block.
 
 ````markdown
-```
-{autodocs}
+```@autodocs
 Modules = [Foo, Bar]
 Order   = [:function, :type]
 ```
 ````
 
-The above `{autodocs}` block adds all the docstrings found in modules `Foo` and `Bar` that
+The above `@autodocs` block adds all the docstrings found in modules `Foo` and `Bar` that
 refer to functions or types to the document.
 
 Each module is added in order and so all docs from `Foo` will appear before those of `Bar`.
@@ -71,126 +71,132 @@ filter as well as sorter.
 
 **Note**
 
-When more complex sorting and filtering is needed then use `{docs}` to define it explicitly.
+When more complex sorting and filtering is needed then use `@docs` to define it explicitly.
 
-## `{ref}`
+## `@ref` link
 
 Used in markdown links as the URL to tell Documenter to generate a cross-reference
 automatically. The text part of the link can be either a docstring or header name.
 
-```markdown
+````markdown
 # Syntax
 
-... [`makedocs`]({ref}) ...
+... [`makedocs`](@ref) ...
 
 # Functions
 
-    {docs}
-    makedocs
-
-... [Syntax]({ref}) ...
+```@docs
+makedocs
 ```
 
+... [Syntax](@ref) ...
+````
+
 Plain text in the "text" part of a link will cross-reference a header, while text in
-backticks will cross-reference a docstring from a `{docs}` block. The text should match the
+backticks will cross-reference a docstring from a `@docs` block. The text should match the
 name of the header exactly.
 
-`{ref}`s may refer to docstrings or headers on different pages as well as the current page
+`@ref`s may refer to docstrings or headers on different pages as well as the current page
 using the same syntax.
 
-Note that depending on what the `CurrentModule` is set to, a docstring `{ref}` may need to
+Note that depending on what the `CurrentModule` is set to, a docstring `@ref` may need to
 be prefixed by the module which defines it.
 
 **Duplicate Headers**
 
 In some cases a document may contain multiple headers with the same name, but on different
-pages or of different levels. To allow `{ref}` to cross-reference a duplicate header it must
+pages or of different levels. To allow `@ref` to cross-reference a duplicate header it must
 be given a name as in the following example
 
 ```markdown
-# [Header]({ref#my-custom-header-name})
+# [Header](@id my_custom_header_name)
 
 ...
 
 ## Header
 
-... [Custom Header]({ref#my-custom-header-name}) ...
+... [Custom Header](@ref my_custom_header_name) ...
 ```
 
 The link that wraps the named header is removed in the final document. The text for a named
-`{ref#...}` does not need to match the header that it references. Named `{ref#...}`s may
-refer to headers on different pages in the same way as unnamed ones do.
+`@ref ...` does not need to match the header that it references. Named `@ref ...`s may refer
+to headers on different pages in the same way as unnamed ones do.
 
 Duplicate docstring references do not occur since splicing the same docstring into a
 document more than once is disallowed.
 
-## `{meta}`
+## `@meta` block
 
 This block type is used to define metadata key/value pairs that can be used elsewhere in the
 page. Currently `CurrentModule` and `DocTestSetup` are the only recognised keys.
 
+````markdown
+```@meta
+CurrentModule = FooBar
+DocTestSetup  = quote
+    using MyPackage
+end
 ```
-    {meta}
-    CurrentModule = FooBar
-    DocTestSetup  = quote
-        using MyPackage
-    end
-```
+````
 
-Note that `{meta}` blocks are always evaluated with the `current_module()`, which is
+Note that `@meta` blocks are always evaluated with the `current_module()`, which is
 typically `Main`.
 
 See [Setup Code](@ref) section of the Doctests page for an explanation of `DocTestSetup`.
 
-## `{index}`
+## `@index` block
 
 Generates a list of links to docstrings that have been spliced into a document. The only
 valid setting is currently `Pages = ...`.
 
+````markdown
+```@index
+Pages = ["foo.md"]
 ```
-    {index}
-    Pages = ["foo.md"]
-```
+````
 
 When `Pages` is not provided all pages in the document are included.
 
 Note that the `Pages` value can be any valid Julia code and so can be something more complex
 that an array literal if a large number of pages must be included, i.e.
 
+````markdown
+```@index
+Pages = map(file -> joinpath("man", file), readdir("man"))
 ```
-    {index}
-    Pages = map(file -> joinpath("man", file), readdir("man"))
-```
+````
 
 It should be noted though that in this case `Pages` may not be sorted in the order that is
 expected by the user. Try to stick to array literals for `Pages` as much as possible.
 
-## `{contents}`
+## `@contents` block
 
 Generates a nested list of links to document sections. Valid settings are `Pages` and `Depth`.
 
+````markdown
+```@contents
+Pages = ["foo.md"]
+Depth = 5
 ```
-    {contents}
-    Pages = ["foo.md"]
-    Depth = 5
-```
+````
 
-As with `{index}` if `Pages` is not provided then all pages are included. The default
+As with `@index` if `Pages` is not provided then all pages are included. The default
 `Depth` value is `2`.
 
-## `{example}`
+## `@example` block
 
 Evaluates the code block and inserts the result into the final document along with the
 original source code.
 
+````markdown
+```@example
+a = 1
+b = 2
+a + b
 ```
-    {example}
-    a = 1
-    b = 2
-    a + b
-```
+````
 
-The above `{example}` block will splice the following into the final document
+The above `@example` block will splice the following into the final document
 
 ````markdown
 ```julia
@@ -213,8 +219,7 @@ Code blocks may have some content that does not need to be displayed in the fina
 `# hide` comments can be appended to lines that should not be rendered, i.e.
 
 ````markdown
-```julia
-{example}
+```@example
 srand(1) # hide
 A = rand(3, 3)
 b = [1, 2, 3]
@@ -222,49 +227,46 @@ A \ b
 ```
 ````
 
-Note that appending `# hide` to every line in an `{example}` block will result in the block
+Note that appending `# hide` to every line in an `@example` block will result in the block
 being hidden in the rendered document. The results block will still be rendered though.
 
 **`STDOUT` and `STDERR`**
 
-The Julia output streams are redirected to the results block when evaluating `{example}`
+The Julia output streams are redirected to the results block when evaluating `@example`
 blocks in the same way as when running doctest code blocks.
 
 **`nothing` Results**
 
-When the `{example}` block evaluates to `nothing` then the second block is not displayed.
+When the `@example` block evaluates to `nothing` then the second block is not displayed.
 Only the source code block will be shown in the rendered document. Note that if any output
 from either `STDOUT` or `STDERR` is captured then the results block will be displayed even
 if `nothing` is returned.
 
-**Named `{example}` Blocks**
+**Named `@example` Blocks**
 
-By default `{example}` blocks are run in their own anonymous `Module`s to avoid side-effects
-between blocks. To share the same module between different blocks on a page the `{example}`
+By default `@example` blocks are run in their own anonymous `Module`s to avoid side-effects
+between blocks. To share the same module between different blocks on a page the `@example`
 can be named with the following syntax
 
 ````markdown
-```julia
-{example 1}
+```@example 1
 a = 1
 ```
 
-```julia
-{example 1}
+```@example 1
 println(a)
 ```
 ````
 
-The name can be any text, not just integers as in the example above, i.e. `{example foo}`.
+The name can be any text, not just integers as in the example above, i.e. `@example foo`.
 
-Named `{example}` blocks can be useful when generating documentation that requires
+Named `@example` blocks can be useful when generating documentation that requires
 intermediate explanation or multimedia such as plots as illustrated in the following example
 
 ````markdown
 First we define some functions
 
-```julia
-{example 1}
+```@example 1
 using PyPlot # hide
 f(x) = sin(2x) + 1
 g(x) = cos(x) - x
@@ -272,8 +274,7 @@ g(x) = cos(x) - x
 
 and then we plot `f` over the interval from ``-π`` to ``π``
 
-```julia
-{example 1}
+```@example 1
 x = linspace(-π, π)
 plot(x, f(x), color = "red")
 savefig("f-plot.svg"); nothing # hide
@@ -283,8 +284,7 @@ savefig("f-plot.svg"); nothing # hide
 
 and then we do the same with `g`
 
-```julia
-{example 1}
+```@example 1
 plot(x, g(x), color = "blue")
 savefig("g-plot.svg"); nothing # hide
 ```
@@ -292,19 +292,18 @@ savefig("g-plot.svg"); nothing # hide
 ![](g-plot.svg)
 ````
 
-Note that `{example}` blocks are evaluated within the directory of `build` where the file
+Note that `@example` blocks are evaluated within the directory of `build` where the file
 will be rendered . This means than in the above example `savefig` will output the `.svg`
 files into that directory. This allows the images to be easily referenced without needing to
 worry about relative paths.
 
-`{example}` blocks automatically define `ans` which, as in the Julia REPL, is bound to the
+`@example` blocks automatically define `ans` which, as in the Julia REPL, is bound to the
 value of the last evaluated expression. This can be useful in situations such as the
 following one where where binding the object returned by `plot` to a named variable would
 look out of place in the final rendered documentation:
 
 ````markdown
-```julia
-{example}
+```@example
 using Gadfly # hide
 plot([sin, x -> 2sin(x) + x], -2π, 2π)
 draw(SVG("plot.svg", 6inch, 4inch), ans); nothing # hide
@@ -313,15 +312,14 @@ draw(SVG("plot.svg", 6inch, 4inch), ans); nothing # hide
 ![](plot.svg)
 ````
 
-## `{repl}`
+## `@repl` block
 
-These are similar to `{example}` blocks, but adds a `julia> ` prompt before each toplevel
-expression. `;` and `# hide` syntax may be used in `{repl}` blocks in the same way as in the
-Julia REPL and `{example}` blocks.
+These are similar to `@example` blocks, but adds a `julia> ` prompt before each toplevel
+expression. `;` and `# hide` syntax may be used in `@repl` blocks in the same way as in the
+Julia REPL and `@example` blocks.
 
 ````markdown
-```julia
-{repl}
+```@repl
 a = 1
 b = 2
 a + b
@@ -343,31 +341,32 @@ julia> a + b
 ```
 ````
 
-Named `{repl <name>}` blocks behave in the same way as named `{example <name>}` blocks.
+Named `@repl <name>` blocks behave in the same way as named `@example <name>` blocks.
 
-## `{eval}`
+## `@eval` block
 
 Evaluates the contents of the block and inserts the resulting value into the final document.
 
 In the following example we use the PyPlot package to generate a plot and display it in the
 final document.
 
-```
-    {eval}
-    using PyPlot
+````markdown
+```@eval
+using PyPlot
 
-    x = linspace(-π, π)
-    y = sin(x)
+x = linspace(-π, π)
+y = sin(x)
 
-    plot(x, y, color = "red")
-    savefig("plot.svg")
+plot(x, y, color = "red")
+savefig("plot.svg")
 
-    nothing
+nothing
+```
 
 ![](plot.svg)
-```
+````
 
-Note that each `{eval}` block evaluates its contents within a separate module. When
+Note that each `@eval` block evaluates its contents within a separate module. When
 evaluating each block the present working directory, `pwd`, is set to the directory in
 `build` where the file will be written to.
 
@@ -377,6 +376,6 @@ known until evaluation of the block itself.
 
 **Note**
 
-In most cases `{example}` is preferred over `{eval}`. Just like in normal Julia code where
-`eval` should be only be considered as a last resort, `{eval}` should be treated in the same
+In most cases `@example` is preferred over `@eval`. Just like in normal Julia code where
+`eval` should be only be considered as a last resort, `@eval` should be treated in the same
 way.

Fix docs to match syntax changes.