On this page, you’ll learn:
How to add a title to the site.
How to configure the site’s base URL.
How to assign a site start page.
How to associate the site with a Google Analytics account.
Use the title key (
title) to add a title to your site.
site: title: Demo Docs Site
The title is displayed wherever the site’s UI calls this key. Antora’s default UI displays the site title in the navigation bar at the top of the site.
The site URL key (
url) defines the optional base URL of the published site.
If set, the URL must either be an absolute URL (e.g., https://docs.example.com) or a pathname (aka root-relative path) (e.g., /docs). The value should not contain a trailing slash. If the the URL is absolute, it may include a pathname segment (e.g., https://example.com/docs).
site: url: https://demo.antora.org
The site URL is only used in the generated site when either an absolute URL is required or a pathname. It also implicitly activates any features that require an absolute URL or a pathname.
Features that require an absolute URL are the sitemap files and the canonical URL property in the UI model (which gets included in the head of each page). In those instances, the component, version, module, and page segments are appended to the site URL to produce the complete URL. For example, https://docs.example.org/component/version/page.html. Features that require a pathname (which can be derived from the absolute URL) are the 404 page and the URL prefix on redirect rules.
You can use a page from a documentation component as the index page for your site. When a start page is specified, visitors are redirected from the site’s index page at the base URL to the URL of the start page.
The start page key (
start_page) accepts a page ID as a value.
If you want the site’s start page to be a specific version of the designated page, include the version in the page ID.
site: title: Demo Docs Site url: https://demo.antora.org start_page: 1.0@component-b::index.adoc
In this example, https://demo.antora.org/index.html will redirect to https://demo.antora.org/component-b/1.0/index.html.
If you want the start page to always point to the last version of the page you designate, don’t include a version in the page ID.
site: title: Demo Docs Site url: https://demo.antora.org start_page: component-b::index.adoc
For this example, let’s say that version 2.0 is the latest version of Component B. In this case, https://demo.antora.org/index.html will redirect to https://demo.antora.org/component-b/2.0/index.html.
Account keys for services can be passed to Antora using the
google_analytics key assigns a Google Analytics account to the site.
site: title: Demo Docs Site url: https://demo.antora.org keys: google_analytics: 'XX-123456'
The account key must be enclosed in single quotation marks (
Antora can generate a robots.txt file (aka robots exclusion standard) for the site to control which paths in the sitemap crawlers can visit.
site.robots key in the playbook is both set and non-empty, and the
site.url is also defined, Antora will generate a robots.txt file at the root of the site.
The allowed values of this key are as follows:
arbitrary, multiline string
The special values
disallow are shorthand for allowing or disallowing all user agents access to all paths.
Let’s assume the site category in playbook is defined as follows:
site: url: https://example.org robots: allow
This will generate a robots.txt file that allows access to all paths.
User-agent: * Allow: /
Similarly, if the site category in playbook is defined as follows:
site: url: https://example.org robots: disallow
This will generate a robots.txt file that disallows access to all paths.
User-agent: * Disallow: /
Any other non-empty value will be used as the contents of the robots.txt file.
For example, let’s assume the
site.robots key is declared as follows:
site: url: https://example.org robots: | User-agent: * Disallow: /private/
This will result in the following robots.txt file being generated.
User-agent: * Disallow: /private/
Use a custom value if the built-in options are insufficient.