dmbaturin
17 supporters
iproute2 manual and soupault in 2021

iproute2 manual and soupault in 2021

Jan 24, 2021

If you are wondering what I've been busy with in the first weeks of the new year...

First, I gave the iproute2 manual a serious overhaul. The most visible change is the sidebar ToC that remains visible as you scroll through the document. There's also a bunch of smaller CSS tweaks. For example, the text is justified and hyphenated in browsers that support it (that's Firefox since forever, and Google Chrome since 88). I've also removed the original CSS mess, and I'm still a bit surprised how little CSS it took to make the new layout.

There's another less visible but very important change: intra-document anchors are now hand-coded and permanent. The original version used to have anchor ids based on the heading text, which is most sites on the Internet do, often because ToC generators work on Markdown rather than HTML, and Markdown has no concept of a heading id... But the iproute2 page's ToC is generated by soupault, which works at the HTML level, so it can see id attributes and use them in the ToC links. I gave every heading a hand-coded id based on the command, like baturin.org/docs/iproute2/#ip-tunnel-add-sit. This means you can safely edit the heading text without breaking anyone's deep links.

Then there's a new release of soupault already: 2.4.0. One new feature is an option to treat a directory as a "hand-coded clean URL" rather than a section. Hugo calls such directories "leaf bundles". This makes it easier to maintain pages that need a lot of unique (non-shared) assets, like posts with lots of pictures. To enable it, you need to decide on the name of a special file that will mark "leaf" directories. For example, let's use ".leaf":

[index]
leaf_file = ".leaf"

Now every directory with a file named ".leaf" in it will be treated as a bundle rather than a section, and its index.html will be treated as a normal page.

Last but not least, Windows users can now install soupault from the Chocolatey repository.

Enjoy this post?

Buy dmbaturin a coffee

More from dmbaturin