hotdoc / hotdoc_bootstrap_theme

This project needs a logo. In the meantime, eyes will get hurt by this horrible illustration of programmer art.

Hotdoc is a documentation micro-framework. It provides an interface for extensions to plug upon, along with some base objects (formatters, ...)

Please check the packages listed at https://github.com/hotdoc to pick the extensions you are interested in.

You can find the documentation for hotdoc, by hotdoc here

Licensing

hotdoc is licensed under the LGPL version 2.1 (or, at your option, any later version). See COPYING for more details.

hotdoc_bootstrap_theme's Issues

Sidenav entry cut even if it is scrolled as low as possible

When on http://developer.pitivi.org/Praise.html#on-twitter-in-all-languages, in the sidenav, the 'attic' section is cute even if we scroll the sidenav as low as possible.

A screenful of empty space at end of pages

Hi there!

I was reading the Meson documentation and noticed a systematic bug: when I press the End key to scroll to the last text part of each page I'm left with a screen of empty space instead of the expected text.

However, after some digging I found out that (if I understand correctly) it seems to be intentional: 8db0883. 🙂 I've never before encountered a site that behaves this way. Would you be interested in considering reverting this to not add empty space at the page end? If yes, I would be happy to submit a PR if you like.

Navigation sidebar scrolling scales with its size

Note: I'm using GStreamer docs as an example here, but I believe this problem occurs in all hotdoc users since they all source the navigation scrolling from here. GStreamer docs also have the longest navigation sidebar I could find.

On the GStreamer Application Development Manual, the navigation sidebar is initially short enough to not have a scrollbar on my display.

I then open the Tutorials section, and every tutorial subsection, so that I have a scrollbar on the navigation sidebar. With my mouse hovering over the first element (Installing GStreamer), I scroll one notch and end up between Basic tutorial 2 and 3, which is 4.5 elements down.

If I then open the Plugins section at the bottom (which adds several elements), start at the top, and scroll one notch, I end up between Android Tutorials and Android tutorial 1, which is 28.5 elements down.

That should not happen. Scrolling should always be by the configured number of lines in the browser. Or if that can't be queried from JavaScript, then it should at least be a consistent height.

This test was done Firefox 98. In Chromium, a similar thing occurs, though the size of increase is a bit smaller, going from 2 elements to 12.5 elements.

Use webpack

This way we can avoid using bower and just use npm, bundle all the assets into a single file, and minify them

Extra `1` at end of header IDs

bootstrap toc will generate unic IDs for headers and avoiding clashes with their container ID, it adds 1 at the end of the id which looks bad.

StyleSwitcher performance/compatibility issues

The current implementation of style switching is kind of a janky mess, to be honest. It also relies on switching active styles via an esoteric "alternate" stylesheet feature only officially supported in Firefox, and even then it isn't being used entirely correctly (emphasis in original document):

Any stylesheet in a document falls into one of the following categories:

• Persistent (has rel="stylesheet", no title=""): always applies to the document.
• Preferred (has rel="stylesheet", with title="…" specified): applied by default, but disabled if an alternate stylesheet is selected. There can only be one preferred stylesheet, so providing stylesheets with different title attributes will cause some of them to be ignored.
• Alternate (rel="alternate stylesheet", with title="…" specified): disabled by default, can be selected.

I recognize, however, that it may be difficult to change the style switcher without an overhaul of the entire theming system. hotdoc_bootstrap_theme is based on Bootstrap 3, and like bs3 uses LESS as its style backend. bs4 and bs5 made the switch from LESS to SASS, in part because it offers better support for modern CSS techniques.

The state of the art for style-selection today is to include all styles for all themes directly in the CSS sent to the client, style content using CSS variables, and allow the definitions for those variables to be modified locally by theme selection.

SASS makes this simple, with support for @mixin style definitions and downstream @include reuse of those definitions, including CSS variables. For example, a site might use the following SASS to implement a simple, switchable white-on-black vs. black-on-white theme set that includes automatic support for browser prefers-color-scheme preferences as well as manual switching:

@mixin light-theme {
  --body-text: #000;
  --page-bg: #fff;
}

@mixin dark-theme {
  --body-text: #fff;
  --page-bg: #000;
}

.dark {
  @include dark-theme;
}

.light {
  @include light-theme;
}

:root:not(.light):not(.dark) {
  @media (prefers-color-scheme: light) {
    @include light-theme;
  }

  @media (prefers-color-scheme: dark) {
    @include dark-theme;
  }
}

body {
  color: var(--body-text);
  background-color: var(--page-bg);
}

Selecting one theme or the other explicitly is a simple matter of setting a dark or light CSS class on the document <html> element. The "cascading" part of CSS does the rest.

LESS uses a very different model of variable-driven CSS, generating a separate style sheet for each theme, which complicates matters.