MultiDocumenter

abstract type DropdownComponent

The supertype for any component that can be put in a dropdown column and rendered using MultiDocumenter.render(::YourComponent, thispagepath, dir, prettyurls).

All DropdownComponents go in Columns, which go in MegaDropdownNav.

Any subtype of DropdownComponent must implement that render method.

The main subtype is MultiDocRef, which refers to external documentation and adds it to the search index. However, there are others like Link which is used to link to external sites without making them searchable, and users can implement their own custom components.

Link([text::String], link::String, [isexternal::Bool]) <: DropdownComponent

Represents a link to an external site.

struct MultiDocRef <: DropdownComponent
MultiDocRef(; upstream, name, path, giturl = "", branch = "gh-pages", fix_canonical_url = true)

Represents one set of docs that will get an entry in the MultiDocumenter navigation.

Required arguments:

• upstream: the local directory where the documentation is located. If giturl is passed, MultiDocumenter will clone into this directory.
• name: string used in the MultiDocumenter navigation for this item
• path: the URL path under which the contents of upstream is placed

Optional arguments:

• giturl: URL of the remote Git repository that will be cloned. If this is unset, then upstream must be an existing directory.
• branch: Git branch of giturl where the docs will be pulled from (defaults to gh-pages)
• fix_canonical_url: this can be set to false to disable the canonical URL fixing for this MultiDocRef (see also canonical_domain for make).

SearchConfig(index_versions = ["stable"], engine = MultiDocumenter.PageFind, lowfi = false)

index_versions is a vector of relative paths used for generating the search index. Only the first matching path is considered. engine may be MultiDocumenter.PageFind, MultiDocumenter.FlexSearch, MultiDocumenter.Stork, or a module that conforms to the expected API (which is currently undocumented). lowfi = true will try to minimize search index size. Only relevant for flexsearch.

make(
    outdir,
    docs::Vector{MultiDocRef};
    assets_dir,
    brand_image,
    custom_stylesheets = [],
    custom_scripts = [],
    search_engine = SearchConfig(),
    prettyurls = true,
    rootpath = "/",
    hide_previews = true,
    canonical = nothing,
)

Aggregates multiple Documenter.jl-based documentation pages docs into outdir.

• assets_dir is copied into outdir/assets
• brand_image is a BrandImage(path, imgpath), which is rendered as the leftmost item in the global navigation
• custom_stylesheets is a Vector{String} of relative stylesheet URLs injected into each page.
• custom_scripts is a Vector{Union{String, Docs.HTML}}. Strings can be relative or absolute URLs, while Docs.HTML objects are inserted as the content of inline scripts.
• search_engine inserts a global search bar if not false. See SearchConfig for more details.
• prettyurls removes all index.html suffixes from links in the global navigation.
• rootpath is the path your site ends up being deployed at, e.g. /foo/ if it's hosted at https://bar.com/foo
• hide_previews removes preview builds from the aggregated documentation.
• canonical_domain: determines the the schema and authority (domain) of the (e.g. https://example.org) deployed site. If set, MultiDocumenter will check and, if necessary, update the canonical URL tags for each package site to point to the correct place directory. Similar to the canonical argument of Documenter.HTML constructor, except that it should not contain the path component – that is determined from rootpath.
• sitemap, if enabled, will generate a sitemap.xml file at the root of the output directory. Requires canonical_domain to be set, since the sitemap is determined from canonical URLs.
• sitemap_filename can be used to override the default sitemap filename (sitemap.xml)