DITA Bootstrap

A plug-in for DITA Open Toolkit that extends the default HTML5 output with a basic Bootstrap template.

Installing
Using
Customizing
Feedback
License

Installing

Use the dita command to add this plug-in to your DITA Open Toolkit installation:

DITA-OT 3.5 and newer:

dita install fox.jason.extend.css
dita install net.infotexture.dita-bootstrap

DITA-OT 3.3 and newer:

dita --install fox.jason.extend.css
dita --install net.infotexture.dita-bootstrap

DITA-OT 3.2 and older:

dita --install \
       https://github.com/jason-fox/fox.jason.extend.css/archive/master.zip
dita --install \
       https://github.com/infotexture/dita-bootstrap/archive/master.zip

Using

Specify the html5-bootstrap format when building output with the dita command:

dita --input=path/to/your.ditamap \
     --format=html5-bootstrap

Customizing

Bootswatch themes

Alternate Bootstrap themes can be downloaded directly from Bootswatch.

To override the default appearance with a Bootswatch theme, pass a theme name to the dita command via the --bootstrap.theme parameter:

dita --input=path/to/your.ditamap \
     --format=html5-bootstrap \
     --args.hdr=path/to/your-header.xml \
     --bootstrap.theme=<theme-name>

Custom CSS

To extend the chosen theme, pass a custom CSS file to the dita command via the --args.css parameter.

For a complete override of the theme where the default Bootstrap CSS is no longer required, you can disable it by setting --bootstrap.theme=none:

dita --input=path/to/your.ditamap \
     --format=html5-bootstrap \
     --args.hdr=path/to/your-header.xml \
     --bootstrap.theme=none \
     --args.css=<name-of-css>.css \
     --args.copycss=yes \
     --args.csspath=css \
     --args.cssroot=path/to/your/theme

Note For more extensive customizations with Sass, you may want to install the dita-bootstrap.sass plug-in.

Headers and footers

The plug-in includes a default static navigation menu with a project name and global link placeholders.

The default header file includes/hdr.navbar.default.xml uses the Bootstrap primary (blue) background color for the navbar component. Bootstrap itself offers additional header examples.

To change the color to a dark (black) background, replace the primary background color class bg-primary on the first line with the dark variant bg-dark:

- <nav class="navbar navbar-expand-lg navbar-dark bg-primary">
+ <nav class="navbar navbar-expand-lg navbar-dark bg-dark">

You can edit a copy of this file to adjust the content of the global navigation. To override the global navigation with your own header, pass a custom header file to the dita command via the --args.hdr parameter:

dita --input=path/to/your.ditamap \
     --format=html5-bootstrap \
     --args.hdr=path/to/your-header.xml

The plug-in includes a sample header alternative with a light navbar.

No footer is added by default, but the plug-in also includes a sample footer file and Bootstrap also offers additional examples. To add a footer to the generated output, pass a custom footer file to the dita command via the --args.ftr parameter:

dita --input=path/to/your.ditamap \
     --format=html5-bootstrap \
     --args.ftr=path/to/your-footer.xml

By default, the plug-in uses the partial option to include the current topic in the ToC along with its parents, siblings and children. As with the default HTML5 plug-in, the full option can also be used to generate a complete ToC for the entire map, or none to disable the table of contents entirely.

As of version 5.3.1, the plug-in provides five new options to style the table of contents navigation with either the Bootstrap list group component, nav-pills, or collapsible menus:

list-group-full – Styled full ToC within a Bootstrap list group
list-group-partial – Partial ToC with the current topic, parents, siblings, and children in a list group
nav-pill-full – Styled full ToC using Bootstrap nav-pills
nav-pill-partial – Partial ToC with the current topic, parents, siblings, and children using Bootstrap nav-pills
collapsible – Styled full ToC with collapsible list elements

To use these options, pass the desired value to the dita command via the --nav-toc parameter:

dita --input=path/to/your.ditamap \
     --format=html5-bootstrap \
     --nav-toc=list-group-partial

For an example of collapsible styling, see the output at infotexture.github.io/dita-bootstrap.

Additionally, the first-level navigation menu can be switched to a horizontal Bootstrap menu bar to reduce the depth of the ToC.

To use this option, add the --menubar-toc.include=yes parameter to the dita command:

dita --input=path/to/your.ditamap \
     --format=html5-bootstrap \
     --nav-toc=list-group-partial  \
     --menubar-toc.include=yes

Common Bootstrap utility classes

The HTML output for the following DITA elements can be annotated with common Bootstrap utility classes for borders, background, text, spacing, etc. using additional command line parameters:

bootstrap.css.accessibility.link – Common Bootstrap utility classes for accessibility links
bootstrap.css.accessibility.nav – Common Bootstrap utility classes for accessibility navigation
bootstrap.css.accordion – Common utility classes for Bootstrap accordion components
bootstrap.css.card – Common utility classes for Bootstrap card components
bootstrap.css.carousel – Common utility classes for Bootstrap carousel components
bootstrap.css.carousel.caption – Common utility classes for Bootstrap carousel captions
bootstrap.css.carousel.indicators – Common utility classes for Bootstrap carousel indicators
bootstrap.css.codeblock – Common Bootstrap utility classes for DITA <codeblock> elements
bootstrap.css.container.size – Bootstrap container class for main layout and menubar-TOC. Options: container, container-fluid, container-sm, container-md, container-lg, container-xl, container-xxl (default)
bootstrap.css.dd – Common utility classes for DITA <dd> elements
bootstrap.css.dl – Common utility classes for DITA <dl> elements
bootstrap.css.dt – Common utility classes for DITA <dt> elements
bootstrap.css.figure – Common utility classes for DITA <fig> elements
bootstrap.css.figure.caption – Common utility classes for DITA figure titles
bootstrap.css.figure.image – Common utility classes for images within DITA<fig> elements
bootstrap.css.footer – Common utility classes for the HTML <footer> element
bootstrap.css.nav.parent – Common utility classes for ancestors of active nav-pill elements
bootstrap.css.pagination – Common utility classes for Bootstrap pagination components
bootstrap.css.section.title – Common Bootstrap utility classes for DITA <section> titles
bootstrap.css.shortdesc – Common Bootstrap utility classes for DITA<shortdesc> elements
bootstrap.css.table – Common utility classes for DITA <table> elements
bootstrap.css.tabs – Common utility classes for Bootstrap horizontal tab components
bootstrap.css.tabs.vertical – Common utility classes for Bootstrap vertical tabs
bootstrap.css.thead – Common utility classes for DITA <thead> elements
bootstrap.css.topic.title – Common Bootstrap utility classes for DITA <topic> titles

You can add your own XSLT customizations by creating a new plug-in that extends the DITA Bootstrap XSLT transforms. Just amend args.xsl to point to your own XSLT files. An XSLT template is included within this repository.

Bootstrap icons for DITA notes

The default Bootstrap icons used for DITA <note> elements can be overridden using additional command line parameters:

bootstrap.icon.note – Icon for standard notes
bootstrap.icon.attention – Icon for attention notes
bootstrap.icon.caution – Icon for caution notes
bootstrap.icon.danger – Icon for danger notes
bootstrap.icon.fastpath – Icon for fastpath notes
bootstrap.icon.important – Icon for important notes
bootstrap.icon.notice – Icon for notice notes
bootstrap.icon.remember – Icon for remember notes
bootstrap.icon.restriction – Icon for restriction notes
bootstrap.icon.tip – Icon for tips
bootstrap.icon.trouble – Icon for trouble notes
bootstrap.icon.warning – Icon for warning notes

Optional elements

Bootstrap icons, popovers, tooltips and the dark-mode toggler are enabled by default, but for performance reasons they can be disabled by setting the following command line parameters to no:

icons.include – Enable Bootstrap icons
popovers.include – Enable Bootstrap popover components and tooltip components
dark.mode.include – Whether to include support for a dark mode toggler

Additionally, opt-in breadcrumbs and menu bars and other modifiers can be added using the following parameters

args.breadcrumbs – Add Bootstrap breadcrumb components
menubar-toc.include – Add a Bootstrap menubar
scrollspy-toc – Add a Bootstrap scrollspy navigator
bidi.include – Whether to force included support for RTL languages
toc-spacer.padding – Vertical padding to add to the side menu

Feedback

If you find this useful and build something of your own on top of it, let me know.
If you find a bug or would like to suggest a change, create an issue. (If it’s a bug, provide steps to recreate the issue.)
If you know how to fix it yourself, submit a pull request with the proposed changes.

License

The generated HTML created by this software includes the following additional software components which are obtained under license:

Bootstrap – https://github.com/twbs/bootstrap – MIT license
Bootstrap Icons – https://github.com/twbs/icons – MIT license
Bootswatch Themes – https://github.com/thomaspark/bootswatch – MIT license

Within the sample documentation, where necessary, the texts describing the usage of each component have been copied directly from the official Bootstrap 5.3 documentation, however DITA markup is used throughout the examples describing how to implement these components correctly using outputclass. The text is therefore a derivative of "Bootstrap 5.3 docs" by Twitter, Inc. and the Bootstrap Authors, and used under CC BY 3.0.

infotexture/dita-bootstrap