Skip to content

docs(repo): Update typedoc guides #6353

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

docs(repo): Update typedoc guides #6353

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
6b97468
Update guides
NWylynko Jul 18, 2025
3961d00
review
alexisintech Jul 22, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion .typedoc/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -71,7 +71,7 @@ To generate the Typedoc MDX files inside `.typedoc/docs` run the following scrip
pnpm run typedoc:generate
```

The `.typedoc/docs` folder is inside the `.gitignore` on purpose. Its contents will be pushed to [clerk/generated-typedoc](https://github.com/clerk/generated-typedoc) in CI. You can use it to debug and tweak the output locally before it gets published.
The `.typedoc/docs` folder is inside the `.gitignore` on purpose. Its contents will be pushed to [clerk/clerk-docs](https://github.com/clerk/clerk-docs/tree/main/clerk-typedoc) in CI. You can use it to debug and tweak the output locally before it gets published.

### Adding a package to the Typedoc output

Expand Down
2 changes: 1 addition & 1 deletion docs/CICD.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ A stable release will be triggered every time the "ci(repo): Version packages" P
- All SDKs will be published to `npm`, except for those found in the excluded packages list in `.changeset/config.json`, or any packages with `private: true` set in their `package.json` file.
- A workflow dispatch will be triggered to update the `clerkjs-proxy` worker in `clerk/sdk-infra-workers`.
- A workflow dispatch will be triggered to update the `@clerk/nextjs` version in `clerk/dashboard`.
- A workflow dispatch will be triggered to update the generated docs in `clerk/generated-typedoc`.
- A workflow dispatch will be triggered to update the typedoc generated docs in `clerk/clerk-docs`.

For details regarding the package versioning/publishing process, refer to the [Publishing docs](https://github.com/clerk/javascript/blob/main/docs/PUBLISH.md).

Expand Down
18 changes: 14 additions & 4 deletions docs/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -178,13 +178,23 @@ If your change can't only be tested by unit tests, you should add/edit an integr

### Authoring Typedoc information

As explained in [documenting your changes](#documenting-your-changes), we use JSDoc to annotate our public API surface. We then use [Typedoc](https://typedoc.org/) to autogenerate docs from these comments.
As explained in [documenting your changes](#documenting-your-changes), we use JSDoc to annotate our public API surface. We then use [Typedoc](https://typedoc.org/) to autogenerate MDX docs from these comments.

Locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typdoc/docs`.
For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see [this guide](https://www.notion.so/clerkdev/Typedoc-JSDoc-1df2b9ab44fe808a8cf2c9cca324ea89?source=copy_link).

Comment on lines +183 to 184
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Replace private Notion link with a publicly accessible resource

The Notion link is likely inaccessible to external contributors, breaking the CONTRIBUTING guide for the majority of the OSS audience. Please swap it for a public URL (e.g. a section in clerk-docs).

-For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see [this guide](https://www.notion.so/clerkdev/Typedoc-JSDoc-1df2b9ab44fe808a8cf2c9cca324ea89?source=copy_link).
+For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see the [Typedoc authoring section in the clerk-docs CONTRIBUTING guide](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#typedoc-).
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see [this guide](https://www.notion.so/clerkdev/Typedoc-JSDoc-1df2b9ab44fe808a8cf2c9cca324ea89?source=copy_link).
For a comprehensive guide on **authoring** JSDoc/Typedoc comments, see the [Typedoc authoring section in the clerk-docs CONTRIBUTING guide](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#typedoc-).
🤖 Prompt for AI Agents 
In docs/CONTRIBUTING.md around lines 183 to 184, replace the private Notion link
with a publicly accessible URL to ensure external contributors can access the
guide. Find or create a public resource, such as a section in clerk-docs, that
covers authoring JSDoc/Typedoc comments and update the link accordingly.

These files are pushed to [clerk/generated-typedoc](https://github.com/clerk/generated-typedoc) and then used on Clerk's docs. In the docs you can access the files by using a `<Typedoc src="path/to/file" />` component.
To review your changes locally, you can run `pnpm run typedoc:generate` to generate the docs. Afterwards, you can inspect the MDX files inside `.typedoc/docs`. But if you want to preview how the Typedoc output will look in Clerk Docs, there's a few things you need to do first:

So if you find a typo that's inside a Typedoc file, you'll need to edit the source file, [open a PR](#opening-a-pull-request), and get it merged to `main`. You can preview your changes with the aforementioned `pnpm typedoc:generate` command.
Create a PR that includes your changes to any Typedoc comments. Once the PR has been merged and a release is published, a PR will [automatically](https://github.com/clerk/clerk-docs/blob/main/.github/workflows/typedoc.yml) be opened in `clerk-docs` to merge in the Typedoc changes.

Typedoc output is embedded in `clerk-docs` files with the `<Typedoc />` component. For example, if you updated Typedoc comments for the `useAuth()` hook in `clerk/javascript`, you'll need to make sure that in `clerk-docs`, in the `/hooks/use-auth.mdx` file, there's a `<Typedoc />` component linked to the `./clerk-typedoc/clerk-react/use-auth.mdx` file, like:

```mdx
<Typedoc src='clerk-react/use-auth' />
```

Read more about this in the [`clerk-docs` CONTRIBUTING.md](https://github.com/clerk/clerk-docs/blob/main/CONTRIBUTING.md#typedoc-).

Then, to preview how the `<Typedoc />` component renders, the `clerk-docs` PR will have a Vercel preview. Or to get local previews set up, see the [section in `clerk/clerk` about setting up local docs](https://github.com/clerk/clerk?tab=readme-ov-file#5-optional-set-up-local-docs).

## Opening a Pull Request

Expand Down
Loading