DITA Bootstrap Lunr Search is a DITA Open Toolkit plug-in that extends the DITA Bootstrap HTML output with a Lunr.js search function.
The DITA Bootstrap Lunr Search plug-in has been tested with DITA-OT 4.x. Use the latest version for best results.
-
Download the latest distribution package from the project website at dita-ot.org/download.
-
Extract the contents of the package to the directory where you want to install DITA-OT.
-
Optional: Add the absolute path for the
bin
directory to the PATH system variable.This defines the necessary environment variable to run the
dita
command from the command line.
See the DITA-OT documentation for detailed installation instructions.
- Run the plug-in installation commands:
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
dita install https://github.com/infotexture/dita-bootstrap.lunr/archive/master.zip
The DITA Bootstrap Lunr Search plug-in uses the Node.js JavaScript runtime to generate the Lunr.js search index. Node.js must therefore be present for the index to be generated successfully.
To download and install a copy, follow the instructions for your operating system on the download page.
To run, use the html5-bootstrap
transformation and add the args.hdr
parameter.
PATH_TO_DITA_OT/bin/dita -f html5-bootstrap -o out -i PATH_TO_DITAMAP \
--args.hdr=path/to/your-header.xml
A sample header file with a search box is provided with the plug-in: includes/hdr.navbar.lunr.xml - the core markup can be seen below.
<li class="nav-item d-flex align-items-center">
<span class="nav-link pe-2">
<i class="bi bi-search"/>
</span>
<form class="search-box position-relative me-auto">
<input type="search" class="form-control" placeholder="Search…" aria-label="Search for…" dir="auto"/>
</form>
</li>
You can use the standard dita-ot-action to run with Lunr Search. Since the transform requires Node.js to function, it is necessary to install it as part of the install
process. Also, when creating documents in languages other than English, please ensure that the appropriate locale
has been set prior to running the transform to ensure that the search index is generated correctly.
name: Create DITA with Lunr Search (DE)
permissions:
contents: write
'on':
workflow_dispatch: null
jobs:
build-dita:
name: Build DITA
runs-on: ubuntu-latest
steps:
- name: Git checkout
uses: actions/checkout@v3
- name: Build HTML5 + Bootstrap
uses: dita-ot/dita-ot-action@4.0.2
with:
install: |
apt-get update -q
export DEBIAN_FRONTEND=noninteractive
apt-get install -qy --no-install-recommends nodejs
nodejs -v
locale-gen de_DE.UTF-8
LANG="de_DE.UTF-8"
LANGUAGE="de_DE:de"
LC_ALL="de_DE.UTF-8"
plugins: |
fox.jason.extend.css
dita-bootstrap
dita-bootstrap.lunr
project: .github/dita-ot/html.xml
- name: 'Deploy Documentation to GitHub Pages'
uses: JamesIves/github-pages-deploy-action@v4.4.3
with:
token: ${{ secrets.GITHUB_TOKEN }}
branch: gh-pages
folder: out
offline.mode
- enables Lunr search to work in conjunction with DITA Bootstrap offline mode - this requires an additional plugin to be installed.
Apache 2.0 © 2023 Jason Fox
The Program includes the following additional software components which were obtained under license:
- lunr.js - https://github.com/olivernn/lunr.js - MIT license
- lunr-languages - https://github.com/MihaiValentin/lunr-languages - Mozilla Public license