Skip to content

Define a publication with a bookmap

List chapters in a bookmap, name it under publications, and preview the PDF as each reader.

  1. Write the bookmap.
    <bookmap>
      <booktitle>
        <mainbooktitle>OpenD Administrator Guide</mainbooktitle>
      </booktitle>
      <mapref href="keys.ditamap"/>
      <chapter href="../topics/hosting/architecture.dita"/>
      <chapter navtitle="Self-hosting" product="core">
        <topicref href="../topics/hosting/docker-compose.dita"/>
        <topicref href="../topics/hosting/railway.dita"/>
      </chapter>
      <chapter href="../topics/hosting/admin-api.dita"/>
    </bookmap>
    • A chapter with an href is a topic; nested topicrefs follow it. A chapter with only a navtitle becomes a heading for what is under it. part and appendix work the same way.
    • The bookmap resolves keys in its own keyspace. Pull in the same key map as the site map, or topics only the bookmap uses will report unresolved-key.
    • A topic the bookmap includes does not have to be in the site map. If it is not, links to it from the site are plain text and validation warns.
  2. Add it to opend.config.yaml.
    publications:
      - maps/admin-guide.bookmap

    The file name is the URL: admin-guide.bookmap is served at /pdf/admin-guide.pdf. File names must be unique across publications (duplicate-publication).

  3. Preview it. Start the previewer, choose a reader, and open /_opend/publications.

    Each publication shows a PDF link and a print HTML link, or "nothing visible to this reader". The print HTML, at /pdf/admin-guide.html, shows the layout without starting a browser; the PDF needs Chromium (see PDF rendering and limits).

On the next published build, readers who can see at least one topic of the publication get a link to it in the page header.