Design Documents

This design document aims to sum up my current thoughts and feelings about where I’d like this project to go. I feel that for medium sized projects Docket is starting to show the roughness around some edges. The plan is to allow docket to walk a tree of directories rather than just processing a single set of files from a single directory.

Docket aims to understand documentation as a heriachy of nodes and leaves that form a tree. The nodes in the tree are the bales The leaves in the tree are the pages.

This high level heriachy will be navigable with the breadcrumbs, and with the main navigation. Navigation should allow moving around within a bundle, and navigating to sibling bundles, if any. Within a document however there is a separate heirachy. This is the Tree of Contents, or TOC.

Currently when docet walks the tree to produce a TOC blocks of code are highlighed. We support two highling modes: js, and Syntect. Syntect is the preferred mode. We should keep it that way. JS highlight may be a good fallback however if Syntect can’t be built on a given environment for some reason.

Currently we walk the tree of bales and render out the indexes and pages within them. Moving more of the knowledge of the tree structure into the render contex will hopefully simplify some of the job of rendering.

A documentation set is a tree. The interior nodes in this tree are what we call Bales. The leaf nodes are Pages. All together this is the doctree.

A single node in the doctree should represent the un-traversed state of that node. Each unopend bale can contain any number of child items, along with it’s current index. If no index found on disk we should fabricate one from the folder name. Later layouts may choose to render this with a grid of child pages or similar.