feat: dynamic docs content structure

[morekid]

This is the exploration for consolidating the page structure and adding the flexibility to show content based on framework.

Find the working example at /docs/rate-limiting/quick-start.

Things to note:

• Everything under /docs uses the page layout at /src/pages/docs/[...slug].astro, which loads a custom sidebar. Besides multiple sidebars, this also adds the flexibility of further layout customization later on.
• With this approach all frontmatter for each page will need to be generic and not dependent on the framework, and as such will be indexed for SEO. We can however customize the title/description content displayed on the page, although not always in a straightforward manner.
• All titles need to be explicitly typed in the root page if we want them to be in the automatic page TOC on the right. This is why I'm adding them as <slots /> in a few cases. However this will always make them available for the TOC of any framework, which is also not desirable(see the multiple 4. ... links in the page. Haven't found a workaround for this yet, but can investigate more. The fallback is that we take it into account when writing the page content: framework dependent titles won't appear in the TOC.
• It's feasible to explore a totally custom page TOC, replacing the one that Starlight ships with.
• UPDATE: I've added a custom TOC component and collection schema scaffold to address the above. This is a proof of concept I can refine, but it's 99% there and I like that we can build the index as we like in the frontmatter for each page. It's still probably a good idea to add the titles as slots as it is currently so that we can always use markdown and the id attrs are automatically generated.
• The non-docs prefixed URLs are still accessible so we might need to then redirect /* > /docs/*.
• The code language preference is persisted when using Starlight's <Tabs /> built in syncKey prop.
• This still doesn't handle linkable URLs based on framework, which in this approach should be done with params.

There's of course a considerable amount of manual work to port everything over the new approach.

Screen.Recording.2024-09-19.at.15.49.57.mov

[vercel]

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
arcjet-docs	✅ Ready (Inspect)	Visit Preview	✅ 1 resolved	Oct 17, 2024 2:40pm

[morekid]

cc @bendechrai

[morekid]

Added a custom TOC component approach.

[davidmytton]

Concept looks good. Why do we have to have the /docs prefix? Seems redundant if we're at docs.arcjet.com ?

At https://arcjet-docs-3jr1p35n6-arcjet.vercel.app/docs/rate-limiting/quick-start I see multiple ordered list items in the TOC:

[morekid]

@davidmytton added plugins for expressive code for collapsing sections and showing line numbers, I've also added the Aj code syntax theme.

You can test like so on a <Code /> component:

<Code
  ...
  mark={[1, {range: "3-6"}, {range: "8-12", label: "test"}]}
  ins={[{range: "13-15", label: "no"}]}
  del={[{range: "20"}]}
  collapse={"22-28"}
/>

[davidmytton]

Code theme looks great! It only has dark mode though - is that right? Fine by me either way.

When you collapse the viewsize, the Next.js icon doesn't show properly in the theme switcher. The others do.

[morekid]

Code theme looks great! It only has dark mode though - is that right? Fine by me either way.

Yes, I don't have a light variant with expressive code atm, but everything in place and just needs some time to design/fill in the light theme vars. Regardless of whether the code stays dark in light mode it will still need brightness/contrast adjustments.

When you collapse the viewsize, the Next.js icon doesn't show properly in the theme switcher. The others do.

Yep, will fix.

[davidmytton]

@morekid all the docs are migrated. Can you give it a final review and then it's ready to merge!

[morekid]

@davidmytton looks all good, fixed a few cosmetic issues + the Next.js icon rendering.