Choose a Start Page

Each component version needs a start page. This page can either be the default start page or a page identified by the component version descriptor. Visitors land on a component version’s start page when they click on its entry in the component version selector and when they click on its name at the top of the page menu.

The start page for a component version is separate from the start page for a site. The start page for a site is where the visitor is directed when they go to the site’s main URL. To configure your site’s start page, see Site Start Page.

Default start page

By default, Antora looks for a page named index.adoc in the ROOT module of a component version and uses it as the component version’s start page (e.g., https://site-url.org/component-name/version/index.html). If Antora doesn’t find this page, visitors are directed to a 404 page every time they click on the component version from the component version selector or page menu.

If you set the start_page key in the component version’s antora.yml, Antora will use that page as the start page instead of the index.adoc page in the ROOT module. You only have the set the start_page key if you want to use an alternate page than the default as the start page.

start_page key

The start_page key must be set in antora.yml when:

  1. a component version doesn’t have a page named index.adoc in its ROOT module, or

  2. when Antora should use an alternate page (that is, not index.adoc, even if it exists) as the component version’s start page.

The start_page key accepts the resource ID of a page that belongs to the component version the antora.yml file describes. The resource ID must start from the module coordinate (though the ROOT module is implied if not present).

Example 1. antora.yml
name: colorado
title: Colorado ∆
version: '5.6'
start_page: get-started:overview.adoc

In Example 1, the component version’s start page, overview.adoc, is located in the module get-started.

If the start page is located in the ROOT module, the module coordinate can be dropped.

Example 2. antora.yml
name: colorado
title: Colorado ∆
version: '5.6'
start_page: overview.adoc

In Example 2, the component version’s start page, overview.adoc, is found in the ROOT module.