Creation of new Style Spec Docs

[birkskyum]

There are many reasons to abandon the existing docs, but mainly we need proper typescript support. MapBox Batfish only supports javascript, and while it forces us to do a ton of workarounds we still end up with bugs like maplibre/maplibre-gl-js-docs#421 due to lacking ts support.

This task covers the creation a docs site with feature parity to the existing Style Spec section found at maplibre.org/maplibre-gl-js-docs/style-spec/, but using a much more modern stack and a refactored codebase, but without touching the v8.json. Below is the reasoning for the selected stack:

Selection of SSG stack

This describes the reasoning behind the selected stack used for the style-spec docs, which is based on Solid / SolidStart.

What is the style spec ?

1. The style spec json
The style-spec is in it's essense a .json document, currently at v8.x, thus it can be found at v8.json. It contains all the style parameters, and for each parameter it has information about:

• the parameter type
• from which version each sdk added support for this property
• config for expressions
• default value
• text for the docs
• if the parameter is required/optional

2. Metadata for the style-spec
In order to read and document this json document of properties, it's necessary to know some things about it, such as the allowed types for each field. For instance, the parameter type, here it's good to know what potential types exist. For the expression config, when an expression like step or interpolate is mentioned, is has data about input and output types, as well as arguments, and allowed comparison signatures ('==', '!=', '<', '<=', '>', '>='). Currently, this style-spec data is found in typescript files located at:

• ./src/ - See compound_expression, expression/definitions/index.tsx, expression/types.ts
• ./docs/ - See item.tsx, expression-metadata.tsx

Even though each platform (gl js, gl native) in principle should be treated equal, the docs need a verison of the metadata to be built, and because both the docs and MapLibre GL JS are web based, this typescript version is used. MapLibre Native also has an inplementation of the same metadata, but it's to be found in the maplibre-gl-native repository.

How to build the docs?

We used pre-compiled static site generation to build the docs, because it allow us at not cost to deploy oru docs as GitHub Pages, and it performs well too. Conventional popular options here are:

• Hugo (go)
• MkDocs (python)
• Jekyll (ruby)
• Hexo (js)
• Slate (ruby)
• Docusaurus (js)

Because we use the MapLibre GL JS metadata implementation in TypeScript, and thus have to run some typescript logic in order to generate the markup, any of the options that are relying on other languages are suddenly no-ops, limiting our options to the likes of:

• Docusaurus (MDX v1 only)
• Next.js (React)
• Gatsby (React)
• Remix (React)
• Qwik City (Qwik) (Vite based)
• Astro (Astro / MDX v2 as entrypoint + Agnostic embed) (Vite based)
• SolidStart (Solid) (Vite based)
• VitePress (Vue) (Vite based)
• SvelteKit (Svelte) (Vite based)

It's of course desireable to use MDX or another markdown extentions langauge, because it's easy readable on GitHub. While the JSX components included in MDX can be generated dynamically at build time, the markdown itself is surprisingly difficult to generate, and in our case where we use a lot fo the data from the v8.json in the markup, this becomes problematic. Preliminary tests of Astro and Docusaurus here showed that in particular code snippets proved to be problematic, because a code snipped in markdown is designated with triple backticks ```. Inside of this code block it's impossible to include variables like example urls from v8.json and versions from package.json using the common syntax of {varname} - the variable names will simply be written out in plain text. This blocks us from using a tool like Docusaurus for now. For now this forces us to resort to template strings and running it through a markdown processor, and it leaves us the following options.

• Next.js (React)
• Gatsby (React)
• Remix (React)
• Qwik City (Qwik) (Vite based)
• Astro (Astro as entrypoint + Agnostic embed) (Vite based)
• SolidStart (Solid) (Vite based)
• VitePress (Vue) (Vite based)
• SvelteKit (Svelte) (Vite based)

In order to avoid further complexity, I think we should keep our code as plain typescript files, reducing our options further to:

• Next.js (React)
• Gatsby (React)
• Remix (React) (Vite based)
• Qwik City (Qwik) (Vite based)
• SolidStart (Solid) (Vite based)

Either of these options could have worked for us. I decided not go with Qwik, because their focus is on loading in only the needed js when interacting with each component on a page (thus delaying running js to the very last moment), which is the polar opposite to our usecase which is SSG where as much as possible of the work is done up front. Regarding Solid and React, they have a near identical syntax, but Solid has a much higher performance. SolidStart on isn't as mature as Solid yet, but it's merely a small addon built on top of the very stable and popular ViteJS, and my preliminary tests showed that it could do all that we needed well - and knowing that we could easily fall back to one of the alternatives I ended up selecting it:

• SolidStart (Solid)

A note on the near future: SolidStart currently maintains an in-house SSG module, but it will under the hood in the next release swap it for the one Astro also uses, thus stabilizing our setup quite a bit.

Selection of Markdown stack

There are many libraries to parse markdown, and just to name a few there are:

• remark
• markdown-it
• markdoc (new, created by Stripe)

Additionally, to highlight code blocks, the two commonly used libraries are:

• prismjs
• highlight.js

Markdoc is more performant when generating large amounts of documents, but this is a fairly small page. What we need is something that can be server side rendered, and it should have features like automatic generation of anchor links on headers, deflist support etc. Markdown-it has all these features, and in combination with PrismJS (which also was used on the existing docs site), we have a proven combo that can do the job well.

[birkskyum]

Closed by #88 - Load was >100 hours

[wipfli]

Thanks for the summary, @birkskyum