Introducing DocBrowser

Recently I've been working on a couple of projects that required on-line documentation.  After looking at several existing templates and not finding any that were quite right for what was needed, I decided to take the time to build one.

The result is "DocBrowser - A HTML Template for Documentation".

The best way to get a feel for DocBrowser is to test drive it yourself.  The DocBrowser documentation itself uses the template.  Check it out here.

This post is a quick look of some of its features.

Navigation Tree

Besides the content, the most prominent part of DocBrowser is the navigation tree.

One of the things that bothered me about the navigation trees in other templates is that they didn't maintain their position when transitioning between pages.  Not only is this  distracting but it makes it awkward to click through a sequence of pages because you can easily lose your place after each click.

I was after something more like a single page app and while I did consider that approach I needed something that would work for static HTML files with no server involved.

DocBrowser uses session state to store the tree state (ie: which nodes are expanded vs collapsed) and its scroll position.  I also spent considerable effort making the transition as flicker/flash/jump/jitter free as possible.  Try it for yourself... clicking between pages in the tree is pretty seamless.

Navigation Tree Filtering

The navigation tree can be filtered - just type in the filter box at the top of the tree, and it will show the matching items:

By default the filtering matches on the text of each leaf node in the tree but you can customize the search text to make it match on different text to what's displayed.  See here.

"On this page" Links

This is a fairly common feature and while there's nothing special about DocBrowser's implementation, it is supported:

These links are created automatically from article headings that have an id attribute.  You can also customize the text displayed in the side bar with a data attribute on the heading.  See here.

Heading Anchor Links

DocBrowser automatically adds link icons to headings. When you hover over a heading a little link icon appears that you can use to create a link to that location in the document.  

Responsive Design

DocBrowser works well on small screens:

• the "On this page" links are hidden,
• the wide aspect logo is reduced to a square icon and,
• the navigation panel is moved to a popup menu.

On large desktop displays, to improve the reading experience, DocBrowser deliberately limits the main content width and keeps it centered in the browser window:

Other Features

DocBrowser also includes:

• Header and footer areas, including project logo or icon display
• Ability to remove the navigation panel for pages that need similar styling but don't need the navigation tree.
• Syntax highlighting with Prism.JS. (including some suggestions on how to reduce jitter between transitions that Prism can cause)
• A couple of table styles that are often used in documentation
• Conditional content based on the current responsive display state (eg: display different help text about the navigation menu depending whether it's shown to the left vs in the popup panel).

Dependency Free

Aside from Prism.JS (which you can remove if you don't need it), DocBrowser is completely dependency free.  No jQuery, nor any other libs.

I even removed a dependency on FontAwesome by putting together a tiny custom font for the 3 icons it uses (the heading anchor link chain, the tree expander chevron and the hamburger menu).

Packaging

DocBrowser is available as a .zip file (get it here) that includes the styles sheets, script files, the custom font and a heavily commented example layout file showing how the HTML markup should look.  The zip also includes minified and source mapped styles sheets and scripts.

Finally, I've written up instructions on a recommended approach to using the template such that if I release a new version integrating it with your changes won't be too painful.

Wrap Up

So there you have it: DocBrowser, a nice HTML template for documentation that's easy to integrate, easy to customize, and provides a great reading experience.  

Feel free to use it in your own projects (see license) and let me know if you do - or if you have suggestions for how it could be improved.

Random Galaxy Generation

With each blog post I like to help spread the word on other people's projects.  This time, it's in the family...  

My son Mitch is working on a game where they needed randomly generated galaxy images.  Check out his post Random Galaxy Generation with C# and OpenGL and the game Sector's Edge.