# Showcase

This page showcases the various page elements that are supported by Documenter. It should be read side-by-side with its source (docs/src/showcase.md) to see what syntax exactly is used to create the various elements.

A table of contents can be generated with an @contents block. The one for this page renders as

## Basic Markdown

Documenter can render all the Markdown syntax supported by the Julia Markdown parser. You can use all the usual markdown syntax, such as bold text and italic text and print("inline code").

## Code blocks

Code blocks are rendered as follows:

This is an non-highlighted code block.
... Rendered in monospace.

When the language is specified for the block, e.g. by starting the block with julia, the contents gets highlighted appropriately (for the language that are supported by the highlighter).

function foo(x::Integer)
@show x + 1
end

## Mathematics

For mathematics, both inline and display equations are available. Inline equations should be written as LaTeX between two backticks, e.g. A x^2 + B x + C = 0. It will render as $A x^2 + B x + C = 0$.

The LaTeX for display equations must be wrapped in a math code block and will render like

$$$x_{1,2} = \frac{-B \pm \sqrt{B^2 - 4 A C}}{2A}$$$

By default, the HTML output renders equations with KaTeX, but MathJax can optionally be used as well.

Warning

Similar to LaTeX, using $ and $ to escape inline and display equations also works. However, doing so is deprecated and this functionality may be removed in a future release. ## Images Include images using basic Markdown syntax: The path should be relative to the directory of the current file. Alternatively, use ./ to begin a path relative to the src of the documents, e.g., ./assets/logo.png. ## Admonitions Admonitions are colorful boxes used to highlight parts of the documentation. Each admonition begins with three !!!, and then the content is indented underneath with four spaces: !!! note "An optional title" Here is something you should pay attention to. Documenter supports a range of admonition types for different circumstances. ###### Note admonition 'note' admonition Admonitions look like this. This is a !!! note-type admonition. Note that admonitions themselves can contain other block-level elements too, such as code blocks. E.g. f(x) = x^2 However, you can not have at-blocks, docstrings, doctests etc. in an admonition. Headings are OK though: # Heading 1 ## Heading 2 ### Heading 3 #### Heading 4 ##### Heading 5 ###### Heading 6 ###### Info admonition 'info' admonition This is a !!! info-type admonition. This is the same as a !!! note-type. ###### Tip admonition 'tip' admonition This is a !!! tip-type admonition. ###### Warning admonition 'warning' admonition This is a !!! warning-type admonition. ###### Danger admonition 'danger' admonition This is a !!! danger-type admonition. ###### Compat admonition 'compat' admonition This is a !!! compat-type admonition. ###### Unknown admonition class Unknown admonition class Admonition with an unknown admonition class. This is a code example. ## Lists Tight lists look as follows • Lorem ipsum dolor sit amet, consectetur adipiscing elit. • Nulla quis venenatis justo. • In non sodales eros. If the lists contain paragraphs or other block level elements, they look like this: • Morbi et varius nisl, eu semper orci. Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem. • Nulla molestie aliquet metus, a dapibus ligula. Morbi pellentesque sodales sollicitudin. Fusce semper placerat suscipit. Aliquam semper tempus ex, non efficitur erat posuere in. Fusce at orci eu ex sagittis commodo. Fusce tempus scelerisque egestas. Pellentesque varius nulla a varius fringilla. Fusce nec urna eu orci porta blandit. Numbered lists are also supported 1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. 2. Nulla quis venenatis justo. 3. In non sodales eros. As are nested lists • Morbi et varius nisl, eu semper orci. Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem. • Lorem ipsum dolor sit amet, consectetur adipiscing elit. • Nulla quis venenatis justo. • In non sodales eros. • Nulla molestie aliquet metus, a dapibus ligula. 1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. 2. Nulla quis venenatis justo. 3. In non sodales eros. Fusce nec urna eu orci porta blandit. Lists can also be included in other blocks that can contain block level items Bulleted lists in admonitions • Lorem ipsum dolor sit amet, consectetur adipiscing elit. • Nulla quis venenatis justo. • In non sodales eros. Large lists in admonitions • Morbi et varius nisl, eu semper orci. Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem. • Lorem ipsum dolor sit amet, consectetur adipiscing elit. • Nulla quis venenatis justo. • In non sodales eros. • Nulla molestie aliquet metus, a dapibus ligula. 1. Lorem ipsum dolor sit amet, consectetur adipiscing elit. 2. Nulla quis venenatis justo. 3. In non sodales eros. Fusce nec urna eu orci porta blandit. • Morbi et varius nisl, eu semper orci. Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem. • Lorem ipsum dolor sit amet, consectetur adipiscing elit. • Nulla quis venenatis justo. • In non sodales eros. ## Tables objectimplementedvalue A10.00 BB1000000.00 With explicit alignment. objectimplementedvalue A10.00 BB1000000.00 Tables that are too wide should become scrollable. objectimplementedvalue A10.00 BBBBBBBBBBBBBBBBBBBB✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓1000000000000000000000000000000000000000000000000000000.00 ## Footnotes Footnote references can be added with the [^label] syntax.[1] The footnote definitions get collected at the bottom of the page. The footnote label can be an arbitrary string and even consist of block-level elements.[Clarke61] ## Headings Finally, headings render as follows ### Heading level 3 #### Heading level 4 ##### Heading level 5 ###### Heading level 6 To see an example of a level 1 heading see the page title and for level 2 heading, see the one just under this paragraph. Headings in sidebars Level 1 and 2 heading show up in the sidebar, for the current page. ## Docstrings The key feature of Documenter, of course, is the ability to automatically include docstrings from your package in the manual. The following example docstrings come from the demo DocumenterShowcase module, the source of which can be found in docs/DocumenterShowcase.jl. To include a docstrings into a manual page, you needs to use an @docs block @docs DocumenterShowcase  This will include a single docstring and it will look like this DocumenterShowcaseModule This is the DocumenterShowcase, which contains Documenter 0.24 This showcase page is included in Documenter version 0.24.0 and above. Contents Docstrings can contain admonitions and other block-level nodes. Info This admonition is in a docstring. It itself can contain block levels nodes such as code blocks: println("Hello World") ... or block quotes: Lorem ipsum. In fact, while not recommended, you can actually have a matryoshka of admonitions: Danger Warning Tip Note Stack overflow. source You can include the docstrings corresponding to different function signatures one by one. E.g., the DocumenterShowcase.foo function has two signatures – (::Integer) and (::AbstractString). @docs DocumenterShowcase.foo(::Integer)  yielding the following docstring And now, by having DocumenterShowcase.foo(::AbstractString) in the @docs block will give the other docstring However, if you want, you can also combine multiple docstrings into a single docstring block. The DocumenterShowcase.bar function has the same signatures as If we just put DocumenterShowcase.bar in an @docs block, it will combine the docstrings as follows: If you have very many docstrings, you may also want to consider using the @autodocs block which can include a whole set of docstrings automatically based on certain filtering options ### An index of docstrings The @index block can be used to generate a list of all the docstrings on a page (or even across pages) and will look as follows ### Multiple uses of the same symbol Sometimes a symbol has multiple docstrings, for example a type definition, inner and outer constructors. The example below shows how to use specific ones in the documentation. ## Doctesting example Often you want to write code example such as this: julia> f(x) = x^2 f (generic function with 1 method) julia> f(3) 9 If you write them as a jldoctest code block, Documenter can make sure that the doctest has not become outdated. See Doctests for more information. Script-style doctests are supported too: 2 + 2 # output 4 ## Running interactive code @example block run a code snippet and insert the output into the document. E.g. the following Markdown @example 2 + 3  becomes the following code-output block pair 2 + 3 5 If the last element can be rendered as an image or text/html etc. (the corresponding Base.show method for the particular MIME type has to be defined), it will be rendered appropriately. e.g.: using Main: DocumenterShowcase DocumenterShowcase.SVGCircle("000", "aaa") This is handy when combined with the Markdown standard library using Markdown Markdown.parse(""" Markdown.MD objects can be constructed dynamically on the fly and still get rendered "natively". """) Markdown.MD objects can be constructed dynamically on the fly and still get rendered "natively". If the last value in an @example block is a nothing, the standard output from the blocks' evaluation gets displayed instead println("Hello World") Hello World However, do note that if the block prints to standard output, but also has a final non-nothing value, the standard output just gets discarded: println("Hello World") 42 42 ### Color output Output from @repl blocks and @example blocks support colored output, tranforming ANSI color codes to HTML. Julia 1.6 Color output requires Julia 1.6 or higher. To enable color output pass ansicolor=true to Documenter.HTML. #### Colored @example block output Input: @example code_typed(sqrt, (Float64,))  Output: code_typed(sqrt, (Float64,)) 1-element Vector{Any}: CodeInfo( 1 ─ %1 = Base.lt_float(x, 0.0)::Bool └── goto #3 if not %1 2 ─ invoke Base.Math.throw_complex_domainerror(:sqrt::Symbol, x::Float64)::Union{} └── unreachable 3 ─ %5 = Base.Math.sqrt_llvm(x)::Float64 └── return %5 ) => Float64 #### Colored @repl block output Input: @repl printstyled("This should be in bold light cyan.", color=:light_cyan, bold=true)  Output: julia> printstyled("This should be in bold cyan.", color=:cyan, bold=true)This should be in bold cyan. Locally disabled color: @repl; ansicolor=false printstyled("This should be in bold light cyan.", color=:light_cyan, bold=true)  julia> printstyled("This should be in bold light cyan.", color=:light_cyan, bold=true)This should be in bold light cyan. #### Raw ANSI code output Regardless of the color setting, when you print the ANSI escape codes directly, coloring is enabled. for color in 0:15 print("\e[38;5;color;48;5;\$(color)m  ")
color % 8 == 7 && println()
end
print("\e[m")
    0     1     2     3     4     5     6     7
8     9    10    11    12    13    14    15


### REPL-type

@repl block can be used to simulate the REPL evaluation of code blocks. For example, the following block

@repl
using Statistics
xs = collect(1:10)
median(xs)
sum(xs)


It gets expanded into something that looks like as if it was evaluated in the REPL, with the julia> prompt prepended etc.:

julia> using Statisticsjulia> xs = collect(1:10)10-element Vector{Int64}:
1
2
3
4
5
6
7
8
9
10julia> median(xs)5.5julia> sum(xs)55

## Doctest showcase

Currently exists just so that there would be doctests to run in manual pages of Documenter's manual. This page does not show up in navigation.

julia> 2 + 2
4

The following doctests needs doctestsetup:

julia> Documenter.Utilities.splitexpr(:(Foo.Bar.baz))
(:(Foo.Bar), :(:baz))

Let's also try @meta blocks:

julia> f(2)
4
• 1A footnote definition uses the [^label]: ...` syntax in a block scope.
• Clarke61

Any sufficiently advanced technology is indistinguishable from magic.

Arthur C. Clarke, Profiles of the Future (1961): Clarke's Third Law.