infotexture / dita-bootstrap Goto Github PK

Using the latest dev version of the plugin.

If a topic is located in a subfolder more than one level deep from the output directory, the dark mode toggler doesn't work on the HTML page.

It looks like the path to the .js file is always ../js/dark-mode-toggler.js, and of course that only works for pages that are located one folder deep. I believe the issue is in the relpath variable, but that's where my XSLT skills end in this case.

EDIT:

Actually now I got it working by changing the regex in the replace function: <xsl:value-of select=" replace($FILEDIR,'[^\\]+','..')"/>

But as a result the file path contains both forward and backslashes. Seems to work, however, both on local files and via an http server.

EDIT 2:

I was able to switch the backslashes to forward ones with this monstrosity: <xsl:value-of select="translate( replace($FILEDIR,'[^\\]+','..'), '\', '/' )"/>

In my old DITA-OT version 3.7.0, net.infotexture.dita-bootstrap was used to enable html5-bootstrap

now using dita-ot 4.1,

$ dita --project config/my-site.yaml 
Error: [DOTA001F][FATAL] "html5-bootstrap" is not a recognized transformation type. Supported transformation types are dita, eclipsehelp, html5, htmlhelp, markdown, markdown_gitbook, markdown_github, pdf, pdf2, xhtml.
$ dita install net.infotexture.dita-bootstrap
Error: Plug-in fox.jason.extend.css already installed: /opt/dita-ot-4.1/plugins/fox.jason.extend.css

The plugin is clearly installed, but the transtype "html5-bootstrap" is missing.

$ dita plugins | grep bootstrap
[email protected]
$ dita --transtypes
pdf
xhtml
eclipsehelp
html5
htmlhelp
dita
pdf2
markdown
markdown_github
markdown_gitbook

I reported a similar problem a few years ago as #31

However, the workaround posted in that issue didn't work for 4.1:

$ dita uninstall net.infotexture.dita-bootstrap
Error: Plug-in /opt/dita-ot-4.1/plugins/net.infotexture.dita-bootstrap doesn't exist.
$ dita install net.infotexture.dita-bootstrap
Error: Plug-in fox.jason.extend.css already installed: /opt/dita-ot-4.1/plugins/fox.jason.extend.css
$ dita --project config/my-site.yaml 
Error: [DOTA001F][FATAL] "html5-bootstrap" is not a recognized transformation type. Supported transformation types are dita, eclipsehelp, html5, htmlhelp, markdown, markdown_gitbook, markdown_github, pdf, pdf2, xhtml.

This is a completely new computer with no prior dita installed on it.

$ uname -a
Linux weiwu-21BXCTO1WW 6.2.0-1005-laptop #6-Ubuntu SMP PREEMPT_DYNAMIC Tue Apr 18 16:47:31 UTC 2023 aarch64 aarch64 aarch64 GNU/Linux
$ java --version
openjdk 17.0.7 2023-04-18
OpenJDK Runtime Environment (build 17.0.7+7-Ubuntu-0ubuntu123.04)
OpenJDK 64-Bit Server VM (build 17.0.7+7-Ubuntu-0ubuntu123.04, mixed mode, sharing)

My current suspicion is that the plugin dependency auto-handling code erred, evident by dita install net.infotexture.dita-bootstrap led a message that a different plugin is installed.

Since dita-ot/registry expects plug-ins to follow semantic versioning guidelines, the versions tagged in this repo thus far resemble SerVer conventions, but are actually a bit arbitrary.

Background

When I prepared the first version for initial release a few years ago, I tagged it as 3.1 to reflect the DITA-OT version it was built for, and more or less stuck with that thereafter, with the exception of 3.4.1, which was a true maintenance release to incorporate a bugfix to the prior release.

Along the way, I considered switching the version numbers to reflect the bundled Bootstrap version instead of the supported DITA-OT version, but never actually switched.

Upcoming versions

Two upcoming releases call this strategy into question:

• I'm currently in the process of backporting the initial 3.1 release for compatibility with DITA-OT 2.5.4.

  So far, I'm thinking of tagging this as 3.2 to indicate it's newer than the 3.1 release from which it's derived, yet does not include the Bootstrap 4 changes from plug-in version 3.3. But if I stick to the target toolkit version scheme, I'd need to tag it as 2.5.4.

• The volume of changes and new features from #4 would justify a significant version bump.

  The supported toolkit version here is likely the same as the current 3.6 release, so that previous versioning scheme would seem to break here. My impulse would be to bump the next version to 5.0 (or 5.0.x) to reflect the bundled Bootstrap version and the fact that it contains many new features when compared to 3.6.

@jason-fox The next released version will contain your changes for Bootstrap 5.0. Any thoughts?

Microsoft Edge DevTools flags our use of <nav role="toc"> as an accessibility issue

Per https://dequeuniversity.com/rules/axe/4.1/aria-roles

ARIA roles used must conform to valid values:
Role must be one of the of the valid ARIA roles: toc

Available roles by type are:

• Landmark: article, banner, complementary, main, navigation, region, search, contentinfo

See dita-ot/dita-ot#3800

When testing #163 & #164 with the current state of the DITA-OT release/4.2 branch (dita-ot/dita-ot@2a2c3f2), the nav ToC sidebar bs-sidebar appears above the page content at desktop breakpoints, rather than in the left column as intended.

The same code in these PRs works fine when built from the DITA-OT master branch (v4.1.2).

Not sure yet if this is a bug in the current state of the DITA-OT release branch, or whether recent changes have rendered the custom XSL code in the DITA Bootstrap plug-in incompatible with the upcoming DITA-OT 4.2 release.

Can't debug further right now, so filing this as a reminder that it's something we'll need to investigate before we package up the new plug-in versions.

At some point, the design for the menubar TOC was changed.

In the previous version, the menubar TOC was part of the main header, and always spanned the full width of the screen.

In the current version, the menubar TOC is in a separate div that has class="container". This means that the menubar is never the full width of the screen, since even at smallest screen sizes there's some margin applied:

And on desktop screen sizes the margin is naturally much larger.

Additionally, since the menubar TOC is in a plain container and the page content is in a container-xxl, the different components do not align at all screen sizes.

POSSIBLE SOLUTION:

Remove the container class from the first wrapping div, and add a new div with container-xxl between the navbar and ul components (meaning that the ul is placed inside that new div).

Or, if this is intentional, please disregard. :)

The new grid layout from Bootstrap 5.3 works well in most cases, but I've noticed a few minor issues we may want to resolve before releasing a new version of the plug-in.

Narrow ToC area

The current grid layout leaves little room for the ToC (even at large desktop resolutions), so long headings often break to several lines. This clipping sometimes also affects the ToC link focus frame, which is cut off on the right edge:

Focus frame

🎗️ That focus frame seems to appear unnecessarily at times (rather than when invoked with TAB) but that's a separate issue.

Empty right column

At desktop resolutions, the current grid layout includes an empty right column, presumably inherited from the Bootstrap docs layout, which uses that space for local “On this page” navigation:

Since we don't generate that local navigation layer by default, it seems odd to reserve the space, particularly when the left ToC sidebar is so constrained.

I'm aware of the need to balance the layout on the page, and keep body content line lengths readable on large screens, but we can probably improve this a bit without breaking anything.

(I can look into these issues myself at some point, but I need to focus on the docs for DITA-OT 4.1 right now, so might not get to it until after that's released.)

By default, a table row is <tr class="row">, which picks up bootstraps grid layout class which is also named row. This results in tables rendering really poorly.

If I change the table rows' class to table-row, then it renders correctly.

I can't seem to find where in the HTML transform the <tr> picks up it's class. Any pointers to which template I can override be great.

There is no border on the left side in all tables with different frames, and the colsep borders are in different size within one table:

Is it attentionally designed like this?

8bac0bb removed the CSS-related parameters, so the CSS files now litter the root level of the output folder.

The necessary parameters should be restored to ensure that all generated CSS files are written to a subfolder as in previous versions.

The recent changes from #4, #7, #10 & #11 add new features to the plug-in that improve the default output, but introduce a few inconsistencies in code formatting and presentation that should be aligned before the 5.3 release.

For example:

• #14
• #15
• #16
• #17
• #18
  • Review links to external projects like DITA-OT
  • Align CI output with default plug-in output
• #19
• Tweak default styles for neutral presentation & accessible text contrast
• Review documentation & code comments to facilitate customization

We may want to consider removing inactive code at some point, as >75% of the code on develop is currently in the unreferenced css/custom.css file with the alternate theme override.

(According to cloc, the codebase has grown from 183 lines of code in v3.6 to over 3500 on feature/attrs).

while generating html5 output using html5-bootstrap plugin can I call custom pdf plugin and generate 2 outputs in same destination?

if possible, then how can I archive this.

Setting the dark.mode.include parameter to no still creates the link to the .js file and thus enables dark mode.

In the insertParameters.xml file the parameter is called BOOTSTRAP_DARK_MODE_INCLUDE, but in the html5-bootstrap.xsl it's called BOOTSTRAP_DARK_MODE_TOGGLER_INCLUDE.

Naming them similarly fixes the issue.

In my old (dita 3.6) note, I wrote (a year ago) to myself that if net.infotexture.dita-bootstrap is installed, the html5-bootstrap type will be recognised. the same dita project stopped working with my DITA-OT version 3.7.0

$ dita --install net.infotexture.dita-bootstrap
Error: Plug-in net.infotexture.dita-bootstrap already installed: /opt/dita-ot-3.7/plugins/net.infotexture.dita-bootstrap
dita --project config/website.yaml -o out/website
Error: [DOTA001F][FATAL] "html5-bootstrap" is not a recognized transformation type. Supported transformation types are dita, eclipsehelp, html5, htmlhelp, markdown, markdown_gitbook, markdown_github, pdf, pdf2, xhtml.

appreciate any hint!

Hi,

I'm working with the latest develop of the the plugin on DITA-OT 3.7.4 , and noticed this:

Using the chunk="to-content" attribute on a topic causes the default TOC and the breadcrumb component to be missing on the topic. See attached image:

And for reference a topic that is not chunked:

(By the way, thank you so much for developing and maintaining this plugin! I think it's something the DITA community really needs: a good looking open source static site generator.)

I have a map with small topics, so I want to merge them to one single html so that I can read it smothly. Is it possible to be realized in this plugin, please?

• Only one page is really "active"
• Consider highlighting ancestors in alternate color such as bg-light

The code block background in light mode seems much darker than the Bootstrap defaults.

Upon inspection, it looks like common-extended.css is using the darker --prism-background: #2d2d2d; as defined for [data-bs-theme="dark"] instead of the lighter --prism-background: #f5f2f0;.

This may be an issue in the upstream fox.jason.prismjs plug-in, just happened to notice it here.

See https://github.com/jason-fox/fox.jason.prismjs/blob/master/css/default-theme.css#L24.

@jason-fox No need to hold up the 5.3.3 release for this, but something to look into when we have the time.

After setting this parameter in the original html5 plugin:

I found that the breadcrumb cannot be generated (I have made sure that the parameter "BREADCRUMBS" has been asigned with the value "yes"). Should I make some changes in the breadcrumb template? I would be very grateful if you can give some suggestions.

With short topics or empty search results, the footer is halfway up the screen when using mobile screen sizes.

This also happens in desktop screen sizes if using nav-toc=none, since the TOC is "normally" pushing the footer down with the height=calc(100vh - 6rem) defined in the common-extended.css

A quite common solution is to set the body element to have display: flex, flex-direction: column and min-height: 110vh (for example), and the to set the footer to have margin-top: auto. These could also be done with Bootstrap classes (besides the min-height in this case) and should work with both mobile and desktop sizes.

The develop branch includes links to the DITA-OT project in the header and footer files used in the CI output, but these should be updated to prevent the impression that the plug-in is part of DITA-OT itself.

I want to customize the common-extended.css file in the output dir, but I did not find the source file in the plugin fox.jason.extend.css, could you please give me some clue?

Since the navbar classes have changed with recent Bootstrap versions, we need to verify the classes and filenames used to style the global navigation headers.

I want to add the map title from DITA source to the header of the html5 output, but I cannot find where the header has been defined. Could you please give some suggestions? (not replace the text "DITA Boostrap" but dynamically apply the map title)

The initial 3.1 release of this plug-in was designed for use with DITA-OT 3.1, which was the current version at that time, and subsequent versions have been updated to take advantage of improvements in recent toolkit versions, up to 3.6.

Some organizations are stuck on older toolkit versions, but would still like to generate Bootstrap-styled HTML output.

For this use case, a new plug-in version should be released to support DITA-OT 2.x by replacing the DITA-OT 3 ant.import extension with the older dita.conductor.target.relative feature extension supported by older toolkit versions.

This new version will be released as plug-in version 3.2 in keeping with the versioning strategy outlined in #8.

Caveats

• The 3.2 plug-in version will be developed and tagged on a separate release branch that will not be merged to master.
• Like the initial 3.1 release, the 3.2 plug-in version will rely on Bootstrap 3.x
• There are currently no plans to backport later plug-in versions to DITA-OT 2.x
  (for the latest Bootstrap support, use the latest plug-in versions)

Run Prettier to normalize indentation, etc.

Hi, @jason-fox
I have a javascript for the output html5. Can I write it directly in the html? If not, how can I embed it in the output html5 correctly?

Hi Roger --
I installed html5-bootstrap in dita-ot-3.5.2. It successfully installed and successfully built docsrc/samples/hierachy.ditamap, yet the generated output (toc.html) seems to be generic DITA-OT HTML5 output.

Were there some pre-requisites that I missed along the way?

I have attached the generated output.

Thanx,
Stan ([email protected])

out.zip

trying to add Scrollspy in my dita output which are generated using dita-bootstrap plugin but its shows following error in cmd
Error: Unsupported argument: --scrollspy-toc=nav-pill

Some Bootswatch themes define a larger padding for button elements. This causes the collapsible TOC to be somewhat messy, because items are not aligned witch each other:

The messiness is even more evident when more than one level of collapsible items is open.

This CSS would align the collapsible items with the non-collapsible ones:

.bs-sidebar .btn { padding-left: 12px; }

I don't think it would break anything, since it only affects buttons inside the sidebar, and there shouldn't be any others? Of course, there could be a custom class for the TOC buttons, and then use that class in the CSS selector.

The topic.fig template in Customization/XSL/topic.xsl appear to override the default HTML5 processing for <imagemap> elements (which of course are specialized from <fig>. As with the templates exception for <syntaxdiagram> element, I think just adding an exception for the imagemap (by class) seems to resolve the issue.

hey, I'm using the dita-bootstrap plugin .. when I'm generating output it creates one toc.index file in the root folder of the output. so my question is can use a style that toc.index file? I want to add CSS and JS for that toc.index file too. how can I do this?

Hi, @infotexture

I applied @chunk="to-content" to the map in order to generate a single html. However, I found that the collapsible nav-toc did not work. In specific, the nav-toc item of current topic cannot be highlighted.

I have figured it out that this is because the class "active" cannot be added to the current nav item in this kind of transformation, but I have no idea on how to modify it to make the collapsible nav-toc compatible with single html output.

Could you please give me some suggestions?

ISSUE:

Using the collapsible nav-toc parameter, the TOC items are created with the collapsible chevron button even if the topicref only has children that are set as toc="no" in the DITA Map.

In the image, the Product 1 and Product 2 have child topics that are set as toc="no".

So having any child topic will cause the nav item to be a collapsible one, even if there's nothing to collapse.

POSSIBLE SOLUTION:

I tried modifying the children parameter in the corresponding template in nav.xsl, and it seems to work:

<xsl:param name="children" select="*[contains(@class, ' map/topicref ')] [not(@toc = 'no')] [not(@processing-role = 'resource-only')]" as="element()*"/>

Hello,

I founded a displaying issue with topics at level 3 and more :

Used command line:
dita -i "C:\xxx\inputs\flowers\flowers.ditamap" -t "C:\xxx\inputs\flowers\temp" -o "C:\xxx\inputs\flowers\out" -f=html5-bootstrap -v --menubar-toc.include=no --args.breadcrumbs=yes --nav-toc=collapsible

Input and output are here:
flowers.zip

Thanks.

The latest changes apply the Bootstrap List Group component style to the table of contents and embeds the full ToC in each page.

This approach works fine for small doc sets like the plugin's own docs, but doesn't scale well to publications that contain a large number of topics, where partial ToCs and standard unordered list presentation provide a better overview of the top-level items, and the current topic's place within that hierarchy.

We might want to consider adding a parameter that allows users to choose whether they want the ToC styled as a list group, or as a standard unordered list (which they can then style with custom CSS).

Another option might be to apply list group style when nav-toc=full, but default to standard ULs when set to partial.

The menu bar ToC introduced with #23 is aligned to the left margin of the viewport, whereas the main navbar is centered within the parent container.

This looks odd at larger resolutions:

If the container approach is not practical, we might consider centering the ToC menu to at least anchor it to the center of the page.

While updating the nav ToC screenshots in 6ee2717 for #125, I noticed that the ToC text size, padding and margins have changed.

Some of these differences may be caused by upstream changes in recent Bootstrap versions, whereas others are likely related to layout and style changes in recent PRs here, such as those that adjust the layout for the in-page scroll spy navigation area for page ToCs on the right.

• ToC width has decreased and font size increased, so longer headings may wrap less favorably (see #89)
• In the default DITA-OT full and partial modes, there is no longer any gutter between the ToC and the page content, so longer headings touch body text.
• In nav-pill-* modes:
  • additional padding appears between the ToC background and active pill
  • there is no gutter between ToC and page content (ToC box touches body text)
  • increased padding between items means fewer ToC items fit on screen
• In list-group-* modes, the gutter is narrower than before.

(See before/after screenshots in 6ee2717 for examples.)

@jason-fox Like #127, there's probably no need to hold up the 5.3.3 release for this, but I wonder if we should switch the default ToC option to collapsible, since that's what seems to work best now — and it's what we use on the project website.

I want to link/add my custom JavaScript file in the every html file (html files with nested hierarchy). how can I do this without using CDN or without hosting js file somewhere. can't add js code in bootstrap.hdf.xml because code is pretty big also required some dynamic changes after DOMContentLoaded

I have added files using some path logic but it's not working in Heretto environment (is not creating directory path - code is not working)

I want JavaScript path something like(because my output folder has many nested folder and html files) but is not working in Heretto

here is the logic which I have used for generating ../../ path for the js file

 <xsl:variable name="relpath">
        <xsl:choose>
          <xsl:when test="$FILEDIR='.'">
            <xsl:text>.</xsl:text>
          </xsl:when>
          <xsl:otherwise>
            <!-- <xsl:value-of select=" replace($FILEDIR,'[^/]+','..')"/> -->
            <xsl:variable name="numSegments" select="string-length($FILEDIR) - string-length(translate($FILEDIR, '\\', ''))"/>
            <xsl:variable name="editedPath">
              <xsl:for-each select="0 to $numSegments">
              <xsl:value-of select="'../'"/>
              </xsl:for-each>
            </xsl:variable>

            <xsl:value-of select="$editedPath"/>
          </xsl:otherwise>
        </xsl:choose>
      </xsl:variable>


//Use 
 <script language="javascript" src="{$relpath}js/commonJS.js"/> 
 <script language="javascript" src="{$relpath}js/script.js"/> 

I have created an extension to DITA Bootstrap for a search box which incorporates a lunr.js search function. You can see the source code here and examples of the result can be seen here and here

I'm now wondering what to do next. 🤷

Thoughts

Although the generation of the lunr search index is generic, the display of the results is currently very tightly bound to the structure of the HTML created by the DITA Bootstrap plugin, and I'm wondering how to incorporate this in a coherent manner.

1. Lunr.js search shouldn't be part of the main DITA Bootstrap plugin - there are plenty of other sensible options - e.g. Solr, Algolia, Google etc. - this is just one way of doing it.
2. Since Lunr.js search is so tightly bound, the repo would be better placed somewhere under your account - i.e. infotexture/dita-bootstrap.lunr rather mine jason-fox/dita-bootstrap.lunr - it would be more discoverable that way.
3. For Documentation, it would be possible to add in another topic in the DITA Bootstrap docs under Extend like Icons or Dark Mode
4. The CI generated GitHub Action can be altered to add search of course.

Questions

So the question is what should happen next? Would it lie better under your account or mine? Should I cede it over to you and you give me back collaborator access or should I leave it where it is? How should I go about raising a documentation PR?

What are your thoughts?

The sample/ DITA files currently contain various markup errors that cause validation to fail.

Although DITA-OT is lenient enough to accept invalid markup like this in most cases, these errors should be fixed to ensure all examples are valid before 5.3 is released:

• Title must be first element in section
• Section must have only one title
• Missing @othertype attribute
• Missing @format attribute on links