Architecture redesign

[blaine-arcjet]

As I was working on the bots docs revamp, I thought about some wants for the new architecture. We can all contribute on this issue.

• Versioned docs
  • The SDK API can change between versions, but we shouldn't erase docs that users might still need
  • The ability to keep the default docs a specific version, so we can let users default to a stable version while we work on unstable changes
  • This will likely be done through copy-paste of the old version into a directory for the new version where changes will be made
  • This is probably a selector in the navbar or fixed in the sidebar
• Single language/framework/adapter selector
  • Users should be able to change 1 selector to switch all examples and docs to their framework of choice
  • In designing how this works, we'll also need to account for the fact that some plain text (non-example) writing will need to vary between frameworks and languages
  • This is probably a selector in the navbar or fixed in the sidebar
• Besides the above, the majority of the text should be written exactly once.
• JavaScript examples
  • Ideally, JavaScript examples are just compiled out from our TypeScript examples without losing formatting/comments, etc. These shouldn't need to be handwritten unless we are only writing a JavaScript example

[davidmytton]

Good list! We're using Starlight by Astro which has some interesting features we could take more advantage of. Some comments:

• Content collections are quite powerful and can be queried.
• The Starlight Versions plugin could solve the versioning issue.
• Cloudflare has multiple languages in their docs (which also use Starlight). See this example and the source. However, they embed the code sample in the mdx whereas we load from files. That was a specific decision to allow us to use syntax checking, formatting, etc as if they were real code examples to avoid errors. The downside is you have to bundle all the dependencies in the repo. I'm also not sure how well it will work with other languages as we move on from JS.
• Starlight uses Expressive Code which is quite powerful, so we could adapt this and write a plugin.
• Vercel's code samples have both a framework selector and a language selector, which is a nice approach. It doesn't solve the issue of different text by language or framework though.

[blaine-arcjet]

That was a specific decision to allow us to use syntax checking, formatting, etc as if they were real code examples to avoid errors. The downside is you have to bundle all the dependencies in the repo. I'm also not sure how well it will work with other languages as we move on from JS.

I was actually thinking about this over the weekend and you touched on it a bit. I think we should type check with TypeScript only as a lint (and the same for compiling/linting with any other language). This would allow us to still build and preview the docs before the SDKs are released.

[morekid]

I've explored a layout considering the points discussed, you can see all the mocks here.
Let me know if this covers everything UX wise and your feedback in general, eg: if you'd like to see some specific use cases.

As for the content duplication, I need to investigate the implementation a bit to see what's possible and how to tackle it. Starting on this now.

[morekid]

I've setup a docs branch that uses the Starlight Versions plugin. To make it work I had to move all non-mdx files outside the docs/ collection and adjust the referenced import paths (needed to be absolute) and asset paths (needed to be relative).

Even with these changes the plugin is not a complete solution as it ignores everything else, eg: the content in the newly created snippets/ folder is not versioned, which for us would be a requisite. We could move the snippets back into the content but they'd have to be wrapped in .mdx. Also worth mentioning that assets are versioned to their immediate parent which might or might not be desirable.

I couldn't test the search locally.

Also couldn't find an easy way to customize the placement of the version banners and switcher that appear when the plugin is installed.

Custom versioning

We could implement our own versioning script. This would create a version folder in content/docs/ and copy over all files. Then run though each file and for any referenced asset create a copy into a versioned folder and update the path so that it links to the versioned resource.

Even with this in place we'd still need to handle the versioned sidebar, pagination, search, ... .

---

Some useful content:

• Astro discussion on versions.
• Approach to branch based versioning.
• Docusaurus has versions built-in but I'm not sure yet that it has the features we need.

---

Edit 1: Official workaround for multiple sidebars using component overrides.

[morekid]

Alternative https://mintlify.com/

[davidmytton]

In our discussion yesterday we came to the conclusion that the versioning plugin wasn't a good enough solution because it didn't add much and was difficult to customize. We also discussed the idea of branching, but I think that would be too difficult to manage in GitHub and figuring out the deploys - see also the problems mentioned at withastro/starlight#957 (comment)

Mintlify has versioning, but I'm reluctant to use a commercial product for a core part of the Arcjet product experience (looks like it could get expensive as well).

We're limited by Starlight's sidebar. We'd could develop our own dynamic sidebar based on the selected version using component overrides. This could be based on placing content in subdirectories, but we could also use frontmatter in the MDX to query the relevant pages.

[morekid]

Apologies for the lengthy comment, I did my test of Mintlify:

• Most CSS/JS customization is for pro plan $150/mo
• Small feature set judging from the docs

Then specifically on features:

• Navigation
  • Pros
    • Tabs flexibility
  • Cons
    • Menu name and displayed page title tightly coupled as derived from front matter
• Content
  • No component overrides
  • Can’t render raw code imports (custom JS on pro plan to possibly get around this)
  • No built-in homepage design
• Versioning
  • Pros
    • Works out of the box
  • Cons
    • No root version (they all go each in a folder), difficult to diff new version changes
    • Difficult to customize

There's surely more to test but I don't feel that the product is advanced enough for our use case or without relying on their support extensively. Plus it's expensive.

---

I explored the code from the Starlight Versions plugin, the main pain points in functionality remain the ability to version snippets and the difficulty in visual customization. We could get around the former by manually versioning our snippets (and using paths accordingly), and I could design around the latter to make it work. So perhaps not an option to ditch necessarily.

---

Branch versioning

@davidmytton curious to know what you think of this approach.

see also the problems mentioned at withastro/starlight#957 (comment)

I don't necessarily agree with these points:

1. Versioning is a maintenance burden regardless and both folder and branch based have pros and cons in this respect. Something to consider is that with folder based the repo can become big and unwieldy in a short span of versions.
2. A theme/template left behind visually can actually be a feature where people are not disoriented by the new changes and can navigate the docs they know from the version they're using. I see that as an advantage where we can decide to update past versions of the docs or not. Whereas with folders, the template will always need to take into account past versions which might limit us in making bolder updates later on.

[blaine-arcjet]

From another issue we have:

When Next.js has a warning or an error, it often includes a link to a page in their documentation (e.g. https://nextjs.org/docs/messages/prerender-error). We should design a similar system in our docs where we can link to an individual page that explains the warning/error and suggested fixes. Also, these URLs should be short and clean (e.g. not linking to a heading).

[morekid]

Find the exploration for displaying the page content dynamically #82.

[blaine-arcjet]

I think it might be worth exploring the Content Layer API, which is currently an experimental API but would give us the flexibility to build the collections we need.