[Discussion] very custom styles - support using external components or ?

[joehand]

Hey, so we wanted to get the Dat docs a bit more consistent style-wise with everything else. This ended up requiring me to fork and modify the minidocs components to get this result. We'd rather not diverge from any more work that goes on here, opening this for discussion + thoughts on how to move forward.

My fork mostly supports the example docs. I cut a few corners and there are a few hardcoded things (mainly the navigation links in header). There were a few options for how a more custom style could be supported in minidocs:

• Change default style to use header
• Add option to use header instead of logo/title in sidebar
• Add option to allow custom components, essentially allowing external modules here as an option.

Change Default Style

Change the default minidocs style completely to use the header. This is mostly done in the fork, as I was using the example folder in development. There were a few hardcoded things that would need to be addressed.

Externally, this would be the smallest change in development (but a large change in style). We could probably accomplish this with a minor version update and adding a single option (for the navigation links).

Header Option

Support the default style and a style that has the header. I think this is a good middle ground that wouldn't require too much external customization. I'd lean towards this one since it wouldn't be a huge amount of work but would let both styles co-exist.

The changes I made ended up being a pretty big fork of the minidocs/components because of how sidebar styling was done previously. Reconciling the two in order to support both is definitely possible. The main task would be thinking through how to set the header option and add any navigation links in the header.

We could also do this with a minor version, adding an option to use the header styles and the navigation links.

Custom Components

Minidocs parsing and stuff is the really powerful part of this module. This option would allow for anyone to build custom styles on top of the minidocs parsing engine.

This would be pretty cool, but this option is probably the most work. We'd have to separate out the default components from the parsing stuff and add options to use an external component for styling.

See also:

• The Dat minidocs fork
• Changes for dat customization

[sethvincent]

@joehand The latest updates to the Dat docs look awesome!

I don't have a whole lot of time to help with this, but would definitely support the inclusion of a header in some form (optional would be cool).

The custom components idea is something I've also been thinking about. When I've considered this I've thought about it as making something lower-level that minidocs could then rely on.

Sort of related: I was working on converting minidocs to choo v5 but hit some issues and decided to wait until v6 is released.

[joehand]

I don't have a whole lot of time to help with this, but would definitely support the inclusion of a header in some form (optional would be cool).

Sounds good, I'll take initiative and try to finish implementing a header option.

Main question I had was how header navigation should be set, e.g. the Install, Home links on top right of https://docs.datproject.org/. Two options:

• Add some option + cli parsing argument
• Add new item to content.json (my preferred way):

  "_navigation": {
    "Install": "/install",
    "Home": "https://datproject.org
  }

I'd prefer the second one because adding this to CLI parsing could get ugly for many navigation links. But I didn't really dive into the parsing of content.json, so hopefully you can tell me if that'd be crazy.

Sort of related: I was working on converting minidocs to choo v5 but hit some issues and decided to wait until v6 is released.

Ya I almost used your new fork but datproject.org is still in choo v4 so it made it easier to reuse stuff =). I haven't followed the v6 news but can try to contribute when that gets released.