It’s now easier to add sidebars to HTML output in yelp-xsl 3.30. When I finally landed the HTML modernization changes in 3.28, I added the ability to have sidebars without completely mucking up the layout. There’s a main element that’s a horizontal flexbox, and you could implement html.sidebar.custom to put stuff in main. But you’d have to do sizing and styling yourself, and you’d have to implement all the stuff you want in there.
I wanted to make sidebars easy in Pintail, so I started implementing some stock sidebars there. Then I realized I could move most of that work into yelp-xsl.
With 3.30, you can now set what you want to see in the sidebars using the html.sidebar.left and html.sidebar.right parameters. These are both space-separated lists of words, where each word is a sidebar component. In yelp-xsl, we have two components out of the box: contents to give you a table of contents for the whole document, and sections to give you a list of sections on the current page. You can also use the special blank token to force a sidebar to appear without actually adding anything to it.
More importantly, you can add your own components. So you can still make fully custom sidebar content while letting yelp-xsl do the rest of the work. For example, let’s say you wanted a left sidebar with a table of contents followed by a Google ad. You could set html.sidebar.left to "contents googlead". Then add a template to your extension stylesheet like this:
<xsl:template
mode="html.sidebar.mode"
match="token[. = 'googlead']">
<!-- Put Google's stuff here -->
</xsl:template>
Pintail will add further sidebar components, such as one to switch between versions of a document, a language selector, and a search bar.
If you use yelp-build, you can pass the extension stylesheet with -x. The extension styleshet is also where you’d set the parameters when using yelp-build.
With Pintail, you’ll be able to set the parameters in your pintail.cfg file.
[pintail] sidebar_left = contents sidebar_right = search languages
What’s more, you’ll be able to set these on a per-directory basis. So, for example, on nightly builds you could add a warning message. In your extension stylesheet:
<xsl:template
mode="html.sidebar.mode"
match="token[. = 'nightly']">
<p style="color: red">NIGHTLY BUILD!</p>
</xsl:template>
Then your pintail.cfg would look like this:
[pintail] sidebar_left = contents sidebar_right = search languages [/path/to/nightly/] sidebar_left = contents nightly
