Writers
Documenter.Writers
— Module.A module that provides several renderers for Document
objects. The supported formats are currently:
:markdown
– the default format.:html
– generates a complete HTML site with navigation and search included.:latex
– generates a PDF using LuaLaTeX.
Documenter.Writers.render
— Method.Writes a Documents.Document
object to .user.build
directory in the formats specified in the .user.format
vector.
Adding additional formats requires adding new Selector
definitions as follows:
abstract type CustomFormat <: FormatSelector end
Selectors.order(::Type{CustomFormat}) = 4.0 # or a higher number.
Selectors.matcher(::Type{CustomFormat}, fmt, _) = fmt === :custom
Selectors.runner(::Type{CustomFormat}, _, doc) = CustomWriter.render(doc)
# Definition of `CustomWriter` module below...
Documenter.Writers.MarkdownWriter
— Module.A module for rendering Document
objects to markdown.
Documenter.Writers.HTMLWriter
— Module.A module for rendering Document
objects to HTML.
Keywords
HTMLWriter
uses the following additional keyword arguments that can be passed to Documenter.makedocs
: assets
, sitename
, analytics
, authors
, pages
, version
, html_prettyurls
, html_disable_git
.
sitename
is the site's title displayed in the title bar and at the top of the *navigation menu. This argument is mandatory for HTMLWriter
.
pages
defines the hierarchy of the navigation menu.
assets
can be used to include additional assets (JS, CSS, ICO etc. files). See below for more information.
Experimental keywords
analytics
can be used specify the Google Analytics tracking ID.
version
specifies the version string of the current version which will be the selected option in the version selector. If this is left empty (default) the version selector will be hidden. The special value git-commit
sets the value in the output to git:{commit}
, where {commit}
is the first few characters of the current commit hash.
html_prettyurls
(default true
) – allows disabling the pretty URLs feature, which generates an output directory structre that hides the .html
suffixes from the URLs (e.g. by default src/foo.md
becomes src/foo/index.html
). This does not work when browsing documentation in local files since browsers do not resolve foo/
to foo/index.html
for local files. If html_prettyurls = false
, then Documenter generate src/foo.html
instead and sets up the internal links accordingly, suitable for local documentation builds.
html_disable_git
can be used to disable calls to git
when the document is not in a Git-controlled repository. Without setting this to true
, Documenter will throw an error and exit if any of the Git commands fail. The calls to Git are mainly used to gather information about the current commit hash and file paths, necessary for constructing the links to the remote repository.
html_edit_branch
specifies which branch, tag or commit the "Edit on GitHub" links point to. It defaults to master
. If it set to nothing
, the current commit will be used.
html_canonical
specifies the canonical URL for your documentation. We recommend you set this to the base url of your stable documentation, e.g. https://juliadocs.github.io/Documenter.jl/stable
. This allows search engines to know which version to send their users to. See wikipedia for more information. Default is nothing
, in which case no canonical link is set.
Page outline
The HTMLWriter
makes use of the page outline that is determined by the headings. It is assumed that if the very first block of a page is a level 1 heading, then it is intended as the page title. This has two consequences:
- It is then used to automatically determine the page title in the navigation menu and in the
<title>
tag, unless specified in the.pages
option. - If the first heading is interpreted as being the page title, it is not displayed in the navigation sidebar.
Default and custom assets
Documenter copies all files under the source directory (e.g. /docs/src/
) over to the compiled site. It also copies a set of default assets from /assets/html/
to the site's assets/
directory, unless the user already had a file with the same name, in which case the user's files overrides the Documenter's file. This could, in principle, be used for customizing the site's style and scripting.
The HTML output also links certain custom assets to the generated HTML documents, specfically a logo and additional javascript files. The asset files that should be linked must be placed in assets/
, under the source directory (e.g /docs/src/assets
) and must be on the top level (i.e. files in the subdirectories of assets/
are not linked).
For the logo, Documenter checks for the existence of assets/logo.png
. If that's present, it gets displayed in the navigation bar.
Additional JS, ICO, and CSS assets can be included in the generated pages using the assets
keyword for makedocs
. assets
must be a Vector{String}
and will include each listed asset in the <head>
of every page in the order in which they are listed. The type of the asset (i.e. whether it is going to be included with a <script>
or a <link>
tag) is determined by the file's extension – either .js
, .ico
, or .css
. Adding an ICO asset is primarilly useful for setting a custom favicon
.
Documenter.Writers.HTMLWriter.MDBlockContext
— Constant.MDBlockContext
is a union of all the Markdown nodes whose children should be blocks. It can be used to dispatch on all the block-context nodes at once.
HTMLWriter
-specific globals that are passed to domify
and other recursive functions.
Returns an ordered list of tuples, (toplevel, anchor, text)
, corresponding to level 1 and 2 headings on the page
. Note that if the first header on the page
is a level 1 header then it is not included – it is assumed to be the page title and so does not need to be included in the navigation menu twice.
Documenter.Writers.HTMLWriter.copy_asset
— Method.Copies an asset from Documenters assets/html/
directory to doc.user.build
. Returns the path of the copied asset relative to .build
.
Documenter.Writers.HTMLWriter.domify
— Method.Converts recursively a Documents.Page
, Markdown
or Documenter *Node
objects into HTML DOM.
Documenter.Writers.HTMLWriter.fixlinks!
— Method.Replaces URLs in Markdown.Link
elements (if they point to a local .md
page) with the actual URLs.
Documenter.Writers.HTMLWriter.get_url
— Method.Returns the full path corresponding to a path of a .md
page file. The the input and output paths are assumed to be relative to src/
.
Documenter.Writers.HTMLWriter.get_url
— Method.Returns the full path of a Documents.NavNode
relative to src/
.
Documenter.Writers.HTMLWriter.getpage
— Method.Returns a page (as a Documents.Page
object) using the HTMLContext
.
Documenter.Writers.HTMLWriter.jsescape
— Method.Replaces some of the characters in the string with escape sequences so that the strings would be valid JS string literals, as per the ECMAScript® 2017 standard.
Note that it always escapes both potential "
and '
closing quotes.
Documenter.Writers.HTMLWriter.mdconvert
— Method.Convert a markdown object to a DOM.Node
object.
The parent
argument is passed to allow for context-dependant conversions.
Documenter.Writers.HTMLWriter.navhref
— Method.Get the relative hyperlink between two Documents.NavNode
s. Assumes that both Documents.NavNode
s have an associated Documents.Page
(i.e. .page
is not nothing
).
Documenter.Writers.HTMLWriter.navitem
— Method.Opens the output file of the navnode
in write node. If necessary, the path to the output file is created before opening the file.
Documenter.Writers.HTMLWriter.pagetitle
— Method.Tries to guess the page title by looking at the <h1>
headers and returns the header contents of the first <h1>
on a page (or nothing
if the algorithm was unable to find any <h1>
headers).
Documenter.Writers.HTMLWriter.pretty_url
— Method.If html_prettyurls
is enabled, returns a "pretty" version of the path
which can then be used in links in the resulting HTML file.
Documenter.Writers.HTMLWriter.relhref
— Method.Calculates a relative HTML link from one path to another.
Constructs and writes the page referred to by the navnode
to .build
.
Documenter.Writers.LaTeXWriter
— Module.A module for rendering Document
objects to LaTeX and PDF.
Keywords
LaTeXWriter
uses the following additional keyword arguments that can be passed to Documenter.makedocs
: authors
, sitename
.
sitename
is the site's title displayed in the title bar and at the top of the navigation menu. It goes into the \title
LaTeX command.
authors
can be used to specify the authors of. It goes into the \author
LaTeX command.