You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Markdown files and their required frontmatter fields:
Ensures title is present (required)
Warns if description is missing (optional)
Validates SDK declarations in frontmatter
Validates internal doc links exist
Validates hash links point to headings
SDK filtering in three contexts:
Manifest: Ensures SDK scoping is properly defined and inherited
Frontmatter: Validates SDK declarations in document metadata
<If /> components: Ensures:
Referenced SDKs exist in the manifest
SDKs are available in the frontmatter
SDK values match the list of valid SDKs
Parent group SDK compatibility
Unique headings within documents
Typedoc content structure and references
Validates all embedded content (partials, typedocs) exists and is properly formatted
Transforms
Content Integration:
Embeds partial content into markdown files
Embeds typedoc content where referenced
Handles special character encoding in typedoc tables
Link Processing:
Updates links to SDK-specific docs to use <SDKLink /> components
Removes .mdx extensions from doc links
SDK-Specific Processing:
Generates SDK-specific versions of docs in their respective folders
Creates "landing" pages for SDK-specific docs at original URLs
Strips out content filtered by SDKs
Manifest Processing:
Generates processed manifest.json with SDK scoping
Applies inheritance rules for SDK scoping in the navigation tree
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
This is all to enable sdk based filtering at a fine-grained control. The goal is:
Starting from the top:
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
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
The <If /> 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.
The reason will be displayed to describe this comment to others. Learn more.
We already have the list under the <If /> component section, I don't think it makes sense to duplicate it, but maybe move it somewhere relevant to both?
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Things this script does
Validates
<If />components: Ensures:Transforms
<SDKLink />componentsThis 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 buildlocally to use itThis is all to enable sdk based filtering at a fine-grained control. The goal is:
Starting from the top:
the "sdk" key value pair in the manifest.json file
the "sdk" key value pair in the frontmatter of a guide
The
<If />componentThere 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.