Docs Build Script

[NWylynko]

This builds script validates

• The manifest
• The markdown files contents (and frontmatter)
• Links (including hashes) between docs
• SDK filtering in the manifest
• SDK filtering in the frontmatter
• SDK filtering in the component

And then it generates out a new dist folder

• Core docs, (where the sdk isn't set in the frontmatter) get put in the root directory
• SDK specific docs (where one or more sdks has been set in the frontmatter) get put in a folder specific to there sdk
  • When the <If /> component has been used it filters out section that don't apply to the sdk
• A new manifest.json is generated for each sdk with only the links that apply to that sdk
• Content in <Partials /> gets embedded, this should help load times in cache miss situations
• A <SDKLink /> component gets placed in markdown files that links to sdk specific guides
• A <SDKDocRedirectPage /> component gets placed in guide landing page, to direct the user towards a sdk specific version

This is run on every push in a github action to help lint for authors and to build the dist package for clerk.com to use.
Authors can run npm run build locally to use it

TODO:

• Make a dev mode, that watches for file changes and updates the dist on demand

This is all to enable sdk based filtering at a fine-grained control. The goal is:

Starting from the top:

1. the "sdk" key value pair in the manifest.json file

   • By setting the sdk key on a group of guides, it hides that group when a user is using a different sdk

2. the "sdk" key value pair in the frontmatter of a guide

   • This controls which sdks a specific guide is available to
   • If this is left unset, it will show up for all sdks
   • If the guide sits within a filtered group of the manifest but attempts to use a different sdk, it will throw an error

3. The component

   • This allows showing parts of the guide to a subset of sdks
   • If this guide is being filtered by 1 or 2, this will error if you attempt to use a sdk outside of the filter

There is no requirement to use filter 3 to use 2 or using 1 to use 3, all three should be optional tools to achieve the docs we are aiming for. But the filtering down should follow a logical order.