Redesign

[tmcw]

The current look of documentation is just what I cobbled together: it could look so much better with the help of a good designer, or lots of hours of my time. Either way...

• I want to rely less on indentation on the left side
• Left side color is kinda gross. threejs has a better one
• Color of links should be better
• Better fonts
• More fun syntax highlighting

v2

### v3

[tmcw]

Also, seeing the three.js docs, I wonder if, with a good monospace font, we can use one font for almost everything?

[tmcw]

Early redesign looks

[jfirebaugh]

Not a fan of the all monospace look, personally. I prefer having a clearer distinction between code snippets and prose.

[anandthakker]

I'm neutral on the monospace thing (but I see @jfirebaugh 's point).

I like these colors. One suggestion: though I know they're all links, I'd be for a different (darker?) color for the top-level items in the sidebar so that it's easier to see/scan the heirarchy

[tmcw]

I think @mayagao is game to work on this redesign for a little bit, but first I need to make it easier to test & develop designs.

[louh]

Re: monospace

You could distinguish code from prose by some other means, like color and weight. Even right now where the only distinction is typeface, it just feels like the kerning/sizing is "off" instead of saying "hey this is code."

I think monospace is fine if your audience is going to remain primarily developers who are used to it.

[mourner]

I strongly support ditching indentation-based hierarchy — I think it would have much better flow with something like heading-based hierarchy.

Also, adjusting table column widths so that there are no huge gaps in between would help readability a lot — currently it's pretty hard to line up things visually:

[mourner]

Also not a fan of monospace for body text BTW. Makes things harder to scan.

[tmcw]

Okay, spent a while making themes more hackable.

This assumes you have node.js installed:

First install dev-documentation:

npm install -g dev-documentation@2.1.0-alpha1

Get a JSDoc-documented project to test against:

git clone git@github.com:mapbox/mapbox-gl-js.git

Get a checkout of the default style

git@github.com:documentationjs/documentation-theme-default.git

Now start theming

dev-documentation mapbox-gl-js/js/mapbox-gl.js -t ./documentation-theme-default/

If you have LiveReload installed, you can enable it and it'll automatically refresh the page when you edit the theme.

/cc @mayagao and whoever wants to take a crack at this. The default theme is now managed in documentation-theme-default and the basics of how themes work are documented in THEME_HTML.

[mayagao]

awesome, thank you @tmcw ! will give it a try this weekend.

[tmcw]

GitHub didn't send me a notification at all for the PR, so I didn't know about that until posting back here :(

• Fix notifications somehow :/
• Integrate those changes into this work
• Ugh fix the columns here, been bashing my head against columns / flex / fixed whatever for a while now and can't get nada. Who knows basscss / flexbox, maybe @samanpwbb or @heyitsgarrett