Left Nav

I'd like to at least experiment with some parts of this structure:

Root Page
n-parent Page
Grandparent Page
Parent Page
~~~
Sibling Page A
Sibling Page B
Current Page

• • Header A
  • Header B
  • Current Header
  • Header D
• Subpage A
• Subpage B
• Subpage C

Sibling Page D

That is:

• Consider putting all parents at the top, duplicating or replacing the breadcrumbs? I'm not really tied to this; the breadcrumbs are fine. But this might be attractive to improve non-desktop behaviors, or if pages get special navigation display behavior (like icons or colors which can't be shown in crumbs).
• List all the siblings as primary navigation. This will make varying amounts of sense depending on document structure, but is probably often good?
• List the table of contents as on-page navigation in the menu.
• List subpages under the table of contents.

This structure may make less sense on mobile, but it's probably not awful. Meaningful customizations here would be:

• Subpage ordering, particularly "by alphabet ascending / descending". Reverse-ordering is useful for "changelog"-style pages. Unclear if other orderings make sense. Ordering should be numeral-aware so numerals sort "9, 10, 11", not "1, 10, 11, 2".
• Letting pages have an icon or image, and maybe coloring.
• Subpage child/grandchild behavior. Perhaps this is not necessary if an {index ...} or {tree ...} element with some options is introduced.

This needs a lot more work, but here's very roughly where I'm trying to go with this:

This feels pretty promising so far.

At the lowest levels:

Remarkup currently can not export a structured representation of document headers, just a blob of HTML. It should support structured export instead. We need this to be able to render page headers into the left nav. This is not very difficult.

I'd like to figure out what's going on with Remarkup headers and anchors first. We currently generate very clumsy anchors, like #termination-for-nonpayme (this is not a typo; we truncate in the middle). At a minimum, I'd like to allow generation of longer anchors and try much harder not to truncate in the middle of words. For example, #termination-for-nonpayment is a better anchor here. As a compatibility step, we could also add Javascript to try to scroll #asdf to any anchor on the page which has asdf as a prefix, so #termination would scroll to the first anchor beginning with #termination. This would keep the legacy anchors working and let savvy users tidy up weird anchors if they want without having to actually edit the document.

I'm tentatively inclined to introduce {anchor ...} and {header ...}, which would have similar behavior. Something like {anchor #name [options]} and {header [#name] [options]} <text to end of line>, possibly?

So things like these would work:

{header #sizes icon=paw} Choosing the Right Size
{anchor #weights-and-measures} <table> ... </table>
{header} Dark Omens!
{header size=6} Ominous Darkness!

This seems generally reasonable. Headers which specify an anchor would also generate a default-named anchor, but the specified anchor would become preferred.

The {anchor} element would just generate an invisible document anchor for now. In the future, maybe it could generate a hint that the anchor exists in the left margin or something like that, or have a "name" option to make it appear in the table of contents. I think all of this stuff is relatively advanced, but at least some use cases involve auto-generating documents or compiling "presentation" documents where it makes more sense to put effort in upfront.

So my plan is:

• Add {anchor} and {header}.
• Fix anchor generation.
• Possibly deal with anchor jump behavior.
• Support getting a structured table of contents out of the Remarkup engine.
• Then, probably try to adopt this layout in Diviner first, since this is less disruptive than doing it in Phriction.