A plug-in for DITA Open Toolkit that extends the default HTML5 output with a basic Bootstrap template.
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
Specify the html5-bootstrap
format when building output with the dita
command:
dita --input=path/to/your.ditamap \
--format=html5-bootstrap
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>
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.
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
The plug-in extends the standard HTML5 table of contents (ToC) navigation parameter --nav-toc
to add styled list groups to the navigation menu. (The navigation is rendered as a sidebar in desktop browsers and above the content on smaller devices.)
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 grouplist-group-partial
– Partial ToC with the current topic, parents, siblings, and children in a list groupnav-pill-full
– Styled full ToC using Bootstrap nav-pillsnav-pill-partial
– Partial ToC with the current topic, parents, siblings, and children using Bootstrap nav-pillscollapsible
– 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
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 linksbootstrap.css.accessibility.nav
– Common Bootstrap utility classes for accessibility navigationbootstrap.css.accordion
– Common utility classes for Bootstrap accordion componentsbootstrap.css.card
– Common utility classes for Bootstrap card componentsbootstrap.css.carousel
– Common utility classes for Bootstrap carousel componentsbootstrap.css.carousel.caption
– Common utility classes for Bootstrap carousel captionsbootstrap.css.carousel.indicators
– Common utility classes for Bootstrap carousel indicatorsbootstrap.css.codeblock
– Common Bootstrap utility classes for DITA<codeblock>
elementsbootstrap.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>
elementsbootstrap.css.dl
– Common utility classes for DITA<dl>
elementsbootstrap.css.dt
– Common utility classes for DITA<dt>
elementsbootstrap.css.figure
– Common utility classes for DITA<fig>
elementsbootstrap.css.figure.caption
– Common utility classes for DITA figure titlesbootstrap.css.figure.image
– Common utility classes for images within DITA<fig>
elementsbootstrap.css.footer
– Common utility classes for the HTML<footer>
elementbootstrap.css.nav.parent
– Common utility classes for ancestors of active nav-pill elementsbootstrap.css.pagination
– Common utility classes for Bootstrap pagination componentsbootstrap.css.section.title
– Common Bootstrap utility classes for DITA<section>
titlesbootstrap.css.shortdesc
– Common Bootstrap utility classes for DITA<shortdesc>
elementsbootstrap.css.table
– Common utility classes for DITA<table>
elementsbootstrap.css.tabs
– Common utility classes for Bootstrap horizontal tab componentsbootstrap.css.tabs.vertical
– Common utility classes for Bootstrap vertical tabsbootstrap.css.thead
– Common utility classes for DITA<thead>
elementsbootstrap.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.
The default Bootstrap icons used for DITA <note>
elements can be overridden using additional command line parameters:
bootstrap.icon.note
– Icon for standard notesbootstrap.icon.attention
– Icon for attention notesbootstrap.icon.caution
– Icon for caution notesbootstrap.icon.danger
– Icon for danger notesbootstrap.icon.fastpath
– Icon for fastpath notesbootstrap.icon.important
– Icon for important notesbootstrap.icon.notice
– Icon for notice notesbootstrap.icon.remember
– Icon for remember notesbootstrap.icon.restriction
– Icon for restriction notesbootstrap.icon.tip
– Icon for tipsbootstrap.icon.trouble
– Icon for trouble notesbootstrap.icon.warning
– Icon for warning notes
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 iconspopovers.include
– Enable Bootstrap popover components and tooltip componentsdark.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 componentsmenubar-toc.include
– Add a Bootstrap menubarscrollspy-toc
– Add a Bootstrap scrollspy navigatorbidi.include
– Whether to force included support for RTL languagestoc-spacer.padding
– Vertical padding to add to the side menu
-
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.
Apache 2.0 © 2017–2024 Roger W. Fienhold Sheen
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.