The content in this repo is shared, or can be shared, between multiple Antora-based documentation repos, such as:

• https://github.com/starknet-io/starknet-docs

• https://github.com/starknet-edu/starknetbook

• Knowledge of Antora and AsciiDoc

• Knowledge of the contribution guidelines for https://docs.starknet.io. See The Starknet docs Contribution guidelines in the Starknet docs repo.

You can only use child files by using the AsciiDoc include directive to include a child file in a parent AsciiDoc file in the parent repo. The child file must be in the partials family directory.

If you directly reference a file in the pages family directory in a nav.adoc file, which defines the left navigation pane, clicking on the file in the pane leads Antora to go to the nav.adoc file of the module that contains the actual AsciiDoc file in the child repo. Because that module by its nature is not synchronized with a parent repo, Antora’s context switches to show the nav.adoc for the child module which means that the left nav pane is empty.

It’s much simpler to just include a file from the child repo with an include directive in a file in the parent repo.

• The parent repo is https://github.com/starknet-io/starknet-docs. (Published output: https://docs.starknet.io)

• The child repo is the repo that you are now viewing, at https://github.com/starknet-io/docs-common-content.

/modules/ROOT/partials/partial_glossary.adoc is a Glossary that I want to include in the parent repo as a standalone page.

To bring the child file into the parent site:

1. Create a parent file in the parent site named glossary.adoc. For example, I created this file as https://github.com/starknet-io/starknet-docs/dev/components/Starknet/modules/ROOT/pages/glossary.adoc. Here’s the entire contents of glossary.adoc:

   include::1.0.0@docs-common-content:ROOT:partial$partial_glossary.adoc[]

2. Include the child repo in the playbook under the sources key. For example:

     sources:
       - url: . (1)
         branches:
           - 'HEAD'
         edit_url: 'https://github.com/starknet-io/starknet-docs/edit/dev/{path}'
         start_paths:
           - components/Starknet
       - url: https://github.com/starknet-io/docs-common-content.git (2)
         branches: 'HEAD'
         edit_url: 'https://github.com/starknet-io/docs-common-content/edit/main/{path}'

   1. This section defines the main repo for the parent.

   2. This section is the child repo.

3. Add the parent file to nav.adoc for the module in which you want to include it. You might have to experiment to place it as desired within the left nav pane.

If you make any changes to a child file, you need to manually regenerate the parent document.