Documentation site about mapbox.js HOT 6 CLOSED

Nice! I really like this approach and seems simple enough to script out. Saman is sketching out a new grid and typography set we should base the design of the documentation off of. When there is a good consensus there - I can start implementing this.

from mapbox.js.

Ah - I really liked the sound of this approach but currently using the build script to generate docs makes its a little disabling to apply doc like styles to the site.

Like there are sections where it would be nice to style out more clearly a passage like this:

This loads the information about a map on MapBox Hosting. The first argument can either be a full URL to a TileJSON file, like
http://a.tiles.mapbox.com/v3/tmcw.map-hehqnmda.jsonp, or a bare id, like tmcw.map-hehqnmda, which will get expanded to the > former.

In the passage above it would be nice to have a little heads up section on what TileJSON is and also a sort of "pro tip" note indicating you can just add in the id and mapbox.js will fill in the rest.

Also, not being able really add markup for syntax highlighting is a bummer. we could add <pre><code data-language=''javascript"> or something but that doesn't work well for html which would just be rendered out.

Build a TOC in JS

We can avoid having to do this if we don't generate the docs from API and STYLE. But API and STYLE should remain and we should follow the same formatting guidelines you have established here. We just unfortunately have a little duplication here.

from mapbox.js.

The other point:

Serve a jekyll site with a straight list of them all

Having worked on some of this on Friday - it felt a little too long going down this route and static pages are fast to generate anyways. Splitting them up into separate pages seems to feel better.

from mapbox.js.

Any alternative suggestions? I'm not sure that these are all really that valid. For instance, for syntax highlighting we can use prettify in js which I've used in Wax and elsewhere.

The jekyll site can be multiple pages, and we can have inter-doc links that just don't work as well in documentation pages.

Would this be more doable if we just abandoned the autogenerated approach and made this more manual? I'm trying to push out a dev release to the team like today and the rest is mostly ready to go, so whatever works works.

from mapbox.js.

Yeah, lets go manual for now - I'd like some markup freedom here.

from mapbox.js.

This is being handled in mapbox.github.com

from mapbox.js.