Generating AST

Plug-in Overview & Installation

The org.dita-bootstrap.ast plug-in transforms DITA XML source topics into JSON Abstract Syntax Trees (AST). Install the plug-in into your DITA Open Toolkit instance:

# Install plug-ins using the dita command:
dita install fox.jason.extend.css
dita install org.dita-bootstrap.ast

Publishing AST to the Document Store

Publishing a DITA map to JSON AST requires a single DITA-OT execution command using the ast-bootstrap transformation type:

# Publish documentation directly into the data store directory:
dita --input=path/to/document.ditamap \
     --format=ast-bootstrap

The output directory contains a zip file holding the toc.json alongside AST JSON topic files. Once published, data-store automatically discovers the document set and adds it to the catalog.

Customizing Headers & Footers via Build Parameters

Custom navigation headers and footers can be attached at publish time using the --args.hdr and --args.ftr build parameters:

dita --input=path/to/document.ditamap \
     --format=ast-bootstrap \
     --args.hdr=path/to/custom-header.xml \
     --args.ftr=path/to/custom-footer.xml

You can reference the following existing XML include files provided by the plug-in suite as functional examples:

• hdr.navbar.example.xml — Example top navigation bar layout template.
• hdr.sidebar.example.xml — Example sidebar header layout template.
• hdr.topbar.example.xml — Example top bar header layout template.
• ftr.content.example.xml — Example multi-column social and copyright footer layout template.

Detailed Structure of Default Navigation Header (hdr.navbar.default.xml)

The plug-in includes hdr.navbar.default.xml as the default primary header template. Its XML structure demonstrates how Bootstrap components, placeholders, and interactive roles are compiled into AST nodes:

<?xml version="1.0" encoding="UTF-8"?>
<Navbar data-bs-theme="dark" expand="lg" sticky="top" bg="primary" variant="dark">
  <Container fluid="xxl" className="px-4">
    <NavbarToggle aria-controls="bdSidebar" aria-label="Toggle docs navigation" className="p-2 me-2">
      <Icon name="list"/>
    </NavbarToggle>
    <NavbarBrand className="d-flex align-items-center fw-semibold" href="/">
      <favicon/>
      <document-title/>
    </NavbarBrand>
    <NavbarToggle aria-controls="navbarContent" aria-label="Toggle navigation"/>
    <NavbarCollapse id="navbarContent">
      <Nav className="ms-auto align-items-lg-center">
        <Form className="position-relative mx-lg-2 search-box" role="search" data-bs-theme="light">
          <InputGroup>
            <InputGroupText className="bg-primary-subtle">
              <Icon name="search"/>
            </InputGroupText>
            <FormControl placeholder="Search…" aria-label="Search" dir="auto" type="search" value=""/>
          </InputGroup>
        </Form>
        <NavDropdown id="bd-theme" className="nav-item" role="theme-toggle" data-bs-theme="light">
          <NavDropdownItem data-bs-theme-value="light">
            <Icon name="brightness-high-fill" className="me-2"/>
            <span>Light</span>
          </NavDropdownItem>
          <NavDropdownItem data-bs-theme-value="dark">
            <Icon name="moon-stars-fill" className="me-2"/>
            <span>Dark</span>
          </NavDropdownItem>
          <NavDropdownItem data-bs-theme-value="auto">
            <Icon name="circle-half" className="me-2"/>
            <span>Auto</span>
          </NavDropdownItem>
        </NavDropdown>
      </Nav>
    </NavbarCollapse>
  </Container>
</Navbar>

Key structural elements of hdr.navbar.default.xml include:

<Navbar> Root Component

Defines a fixed top Bootstrap navigation bar with dark styling (@data-bs-theme="dark", @bg="primary", @sticky="top").

XML Placeholders

• <document-title/> — XML placeholder element automatically substituted at publish time with the document map title.
• <favicon/> — Placeholder element replaced by the branding favicon icon.

Interactive Role Attributes

• @role="search" — Placed on the search <Form>; compiled into AST and intercepted by the web renderer to mount the live client-side search box.
• @role="theme-toggle" — Placed on the <NavDropdown>; intercepted by the web renderer to mount the interactive Light/Dark theme switcher.