Skip to content

Commit 48438b4

Browse files
LekoArtsLekoArts
authored
chore(repo): Improve Typedoc MDX output (#5578)
1 parent e04bf25 commit 48438b4

21 files changed

+552
-659
lines changed

‎.changeset/giant-bats-leave.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
---
2+
'@clerk/shared': patch
3+
'@clerk/clerk-react': patch
4+
'@clerk/types': patch
5+
---
6+
7+
Improve JSDoc comments

‎.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap‎

Lines changed: 123 additions & 114 deletions
Original file line numberDiff line numberDiff line change
@@ -2,119 +2,128 @@
22

33
exports[`Typedoc output > should have a deliberate file structure 1`] = `
44
[
5-
"types/type-aliases/check-authorization-from-session-claims.mdx",
6-
"types/type-aliases/clerk-host-router.mdx",
7-
"types/type-aliases/clerk-pagination-request.mdx",
8-
"types/type-aliases/element-object-key.mdx",
9-
"types/type-aliases/elements-config.mdx",
10-
"types/type-aliases/id-selectors.mdx",
11-
"types/type-aliases/legacy-redirect-props.mdx",
12-
"types/type-aliases/localization-resource.mdx",
13-
"types/type-aliases/multi-domain-and-or-proxy.mdx",
14-
"types/type-aliases/organization-custom-role-key.mdx",
15-
"types/type-aliases/organization-permission-key.mdx",
16-
"types/type-aliases/organizations-jwt-claim.mdx",
17-
"types/type-aliases/override.mdx",
18-
"types/type-aliases/path-value.mdx",
19-
"types/type-aliases/record-to-path.mdx",
20-
"types/type-aliases/redirect-options.mdx",
21-
"types/type-aliases/saml-strategy.mdx",
22-
"types/type-aliases/sdk-metadata.mdx",
23-
"types/type-aliases/session-status-claim.mdx",
24-
"types/type-aliases/set-active.mdx",
25-
"types/type-aliases/sign-up-authenticate-with-metamask-params.mdx",
26-
"types/type-aliases/signed-in-session-resource.mdx",
27-
"types/type-aliases/state-selectors.mdx",
28-
"types/type-aliases/use-auth-return.mdx",
29-
"types/type-aliases/use-session-list-return.mdx",
30-
"types/type-aliases/use-session-return.mdx",
31-
"types/type-aliases/use-sign-in-return.mdx",
32-
"types/type-aliases/use-sign-up-return.mdx",
33-
"types/type-aliases/use-user-return.mdx",
34-
"types/type-aliases/without.mdx",
35-
"types/interfaces/act-claim.mdx",
36-
"types/interfaces/act-jwt-claim.mdx",
37-
"types/interfaces/active-session-resource.mdx",
38-
"types/interfaces/clerk-api-error.mdx",
39-
"types/interfaces/clerk-jwt-claims.mdx",
40-
"types/interfaces/clerk-paginated-response.mdx",
41-
"types/interfaces/clerk-pagination-params.mdx",
42-
"types/interfaces/clerk-resource.mdx",
43-
"types/interfaces/clerk.mdx",
44-
"types/interfaces/create-organization-params.mdx",
45-
"types/interfaces/jwt-claims.mdx",
46-
"types/interfaces/jwt-header.mdx",
47-
"types/interfaces/pending-session-resource.mdx",
48-
"types/interfaces/session-resource.mdx",
49-
"types/interfaces/set-active-params.mdx",
50-
"types/interfaces/sign-in-resource.mdx",
51-
"types/interfaces/sign-out.mdx",
52-
"types/interfaces/sign-up-resource.mdx",
53-
"shared/react/types/type-aliases/paginated-hook-config.mdx",
54-
"shared/react/types/interfaces/pages-or-infinite-options.mdx",
55-
"shared/react/types/interfaces/paginated-resources.mdx",
56-
"shared/react/hooks/use-clerk.mdx",
57-
"shared/react/hooks/use-organization-list-params.mdx",
58-
"shared/react/hooks/use-organization-list-return.mdx",
59-
"shared/react/hooks/use-organization-list.mdx",
60-
"shared/react/hooks/use-organization-params.mdx",
61-
"shared/react/hooks/use-organization-return.mdx",
62-
"shared/react/hooks/use-organization.mdx",
63-
"shared/react/hooks/use-reverification.mdx",
64-
"shared/react/hooks/use-session-list.mdx",
65-
"shared/react/hooks/use-session.mdx",
66-
"shared/react/hooks/use-user.mdx",
67-
"shared/index/functions/build-clerk-js-script-attributes.mdx",
68-
"shared/index/functions/clerk-js-script-url.mdx",
69-
"shared/index/functions/create-path-matcher.mdx",
70-
"shared/index/functions/deep-camel-to-snake.mdx",
71-
"shared/index/functions/deep-snake-to-camel.mdx",
72-
"shared/index/functions/deprecated-object-property.mdx",
73-
"shared/index/functions/derive-state.mdx",
74-
"shared/index/functions/extract-dev-browser-jwt-from-url.mdx",
75-
"shared/index/functions/fast-deep-merge-and-replace.mdx",
76-
"shared/index/functions/get-clerk-js-major-version-or-tag.mdx",
77-
"shared/index/functions/get-env-variable.mdx",
78-
"shared/index/functions/get-script-url.mdx",
79-
"shared/index/functions/icon-image-url.mdx",
80-
"shared/index/functions/in-browser.mdx",
81-
"shared/index/functions/is-browser-online.mdx",
82-
"shared/index/functions/is-clerk-runtime-error.mdx",
83-
"shared/index/functions/is-publishable-key.mdx",
84-
"shared/index/functions/is-staging.mdx",
85-
"shared/index/functions/is-truthy.mdx",
86-
"shared/index/functions/is-valid-browser-online.mdx",
87-
"shared/index/functions/is-valid-browser.mdx",
88-
"shared/index/functions/isomorphic-atob.mdx",
89-
"shared/index/functions/load-clerk-js-script.mdx",
90-
"shared/index/functions/read-json-file.mdx",
91-
"shared/index/functions/set-clerk-js-loading-error-package-name.mdx",
92-
"shared/index/functions/to-sentence.mdx",
93-
"shared/index/functions/user-agent-is-robot.mdx",
94-
"shared/index/functions/version-selector.mdx",
95-
"shared/index/classes/clerk-runtime-error.mdx",
96-
"nextjs/server/create-get-auth/variables/get-auth.mdx",
97-
"nextjs/server/create-get-auth/functions/create-async-get-auth.mdx",
98-
"nextjs/server/create-get-auth/functions/create-sync-get-auth.mdx",
99-
"nextjs/server/clerk-middleware/variables/clerk-middleware.mdx",
100-
"nextjs/server/clerk-middleware/interfaces/clerk-middleware-options.mdx",
101-
"nextjs/server/build-clerk-props/variables/build-clerk-props.mdx",
102-
"nextjs/app-router/server/current-user/functions/current-user.mdx",
103-
"nextjs/app-router/server/auth/variables/auth.mdx",
104-
"clerk-react/interfaces/clerk-provider-props.mdx",
105-
"clerk-react/functions/protect.mdx",
106-
"clerk-react/functions/redirect-to-create-organization.mdx",
107-
"clerk-react/functions/redirect-to-organization-profile.mdx",
108-
"clerk-react/functions/redirect-to-user-profile.mdx",
109-
"clerk-react/functions/use-auth.mdx",
110-
"clerk-react/functions/use-clerk.mdx",
111-
"clerk-react/functions/use-organization-list.mdx",
112-
"clerk-react/functions/use-organization.mdx",
113-
"clerk-react/functions/use-reverification.mdx",
114-
"clerk-react/functions/use-session-list.mdx",
115-
"clerk-react/functions/use-session.mdx",
116-
"clerk-react/functions/use-sign-in.mdx",
117-
"clerk-react/functions/use-sign-up.mdx",
118-
"clerk-react/functions/use-user.mdx",
5+
"types/act-claim.mdx",
6+
"types/act-jwt-claim.mdx",
7+
"types/active-session-resource.mdx",
8+
"types/check-authorization-fn.mdx",
9+
"types/check-authorization-from-session-claims.mdx",
10+
"types/check-authorization-with-custom-permissions.mdx",
11+
"types/clerk-api-error.mdx",
12+
"types/clerk-host-router.mdx",
13+
"types/clerk-jwt-claims.mdx",
14+
"types/clerk-paginated-response.mdx",
15+
"types/clerk-pagination-params.mdx",
16+
"types/clerk-pagination-request.mdx",
17+
"types/clerk-resource.mdx",
18+
"types/clerk.mdx",
19+
"types/create-organization-params.mdx",
20+
"types/element-object-key.mdx",
21+
"types/elements-config.mdx",
22+
"types/get-token.mdx",
23+
"types/id-selectors.mdx",
24+
"types/jwt-claims.mdx",
25+
"types/jwt-header.mdx",
26+
"types/legacy-redirect-props.mdx",
27+
"types/localization-resource.mdx",
28+
"types/multi-domain-and-or-proxy.mdx",
29+
"types/organization-custom-role-key.mdx",
30+
"types/organization-domain-verification-status.mdx",
31+
"types/organization-enrollment-mode.mdx",
32+
"types/organization-invitation-status.mdx",
33+
"types/organization-permission-key.mdx",
34+
"types/organization-suggestion-status.mdx",
35+
"types/organizations-jwt-claim.mdx",
36+
"types/override.mdx",
37+
"types/path-value.mdx",
38+
"types/pending-session-options.mdx",
39+
"types/pending-session-resource.mdx",
40+
"types/record-to-path.mdx",
41+
"types/redirect-options.mdx",
42+
"types/saml-strategy.mdx",
43+
"types/sdk-metadata.mdx",
44+
"types/session-resource.mdx",
45+
"types/session-status-claim.mdx",
46+
"types/set-active-params.mdx",
47+
"types/set-active.mdx",
48+
"types/sign-in-resource.mdx",
49+
"types/sign-out.mdx",
50+
"types/sign-up-authenticate-with-metamask-params.mdx",
51+
"types/sign-up-resource.mdx",
52+
"types/signed-in-session-resource.mdx",
53+
"types/state-selectors.mdx",
54+
"types/use-auth-return.mdx",
55+
"types/use-session-list-return.mdx",
56+
"types/use-session-return.mdx",
57+
"types/use-sign-in-return.mdx",
58+
"types/use-sign-up-return.mdx",
59+
"types/use-user-return.mdx",
60+
"types/user-resource.mdx",
61+
"types/without.mdx",
62+
"shared/build-clerk-js-script-attributes.mdx",
63+
"shared/clerk-js-script-url.mdx",
64+
"shared/clerk-runtime-error.mdx",
65+
"shared/create-path-matcher.mdx",
66+
"shared/deep-camel-to-snake.mdx",
67+
"shared/deep-snake-to-camel.mdx",
68+
"shared/deprecated-object-property.mdx",
69+
"shared/derive-state.mdx",
70+
"shared/extract-dev-browser-jwt-from-url.mdx",
71+
"shared/fast-deep-merge-and-replace.mdx",
72+
"shared/get-clerk-js-major-version-or-tag.mdx",
73+
"shared/get-env-variable.mdx",
74+
"shared/get-script-url.mdx",
75+
"shared/icon-image-url.mdx",
76+
"shared/in-browser.mdx",
77+
"shared/is-browser-online.mdx",
78+
"shared/is-clerk-runtime-error.mdx",
79+
"shared/is-publishable-key.mdx",
80+
"shared/is-staging.mdx",
81+
"shared/is-truthy.mdx",
82+
"shared/is-valid-browser-online.mdx",
83+
"shared/is-valid-browser.mdx",
84+
"shared/isomorphic-atob.mdx",
85+
"shared/load-clerk-js-script.mdx",
86+
"shared/pages-or-infinite-options.mdx",
87+
"shared/paginated-hook-config.mdx",
88+
"shared/paginated-resources.mdx",
89+
"shared/read-json-file.mdx",
90+
"shared/set-clerk-js-loading-error-package-name.mdx",
91+
"shared/to-sentence.mdx",
92+
"shared/use-clerk.mdx",
93+
"shared/use-organization-list-params.mdx",
94+
"shared/use-organization-list-return.mdx",
95+
"shared/use-organization-list.mdx",
96+
"shared/use-organization-params.mdx",
97+
"shared/use-organization-return.mdx",
98+
"shared/use-organization.mdx",
99+
"shared/use-reverification.mdx",
100+
"shared/use-session-list.mdx",
101+
"shared/use-session.mdx",
102+
"shared/use-user.mdx",
103+
"shared/user-agent-is-robot.mdx",
104+
"shared/version-selector.mdx",
105+
"nextjs/auth.mdx",
106+
"nextjs/build-clerk-props.mdx",
107+
"nextjs/clerk-middleware-options.mdx",
108+
"nextjs/clerk-middleware.mdx",
109+
"nextjs/create-async-get-auth.mdx",
110+
"nextjs/create-sync-get-auth.mdx",
111+
"nextjs/current-user.mdx",
112+
"nextjs/get-auth.mdx",
113+
"clerk-react/clerk-provider-props.mdx",
114+
"clerk-react/protect.mdx",
115+
"clerk-react/redirect-to-create-organization.mdx",
116+
"clerk-react/redirect-to-organization-profile.mdx",
117+
"clerk-react/redirect-to-user-profile.mdx",
118+
"clerk-react/use-auth.mdx",
119+
"clerk-react/use-clerk.mdx",
120+
"clerk-react/use-organization-list.mdx",
121+
"clerk-react/use-organization.mdx",
122+
"clerk-react/use-reverification.mdx",
123+
"clerk-react/use-session-list.mdx",
124+
"clerk-react/use-session.mdx",
125+
"clerk-react/use-sign-in.mdx",
126+
"clerk-react/use-sign-up.mdx",
127+
"clerk-react/use-user.mdx",
119128
]
120129
`;

‎.typedoc/__tests__/file-structure.test.ts‎

Lines changed: 0 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -36,33 +36,6 @@ describe('Typedoc output', () => {
3636
"nextjs",
3737
"shared",
3838
"types",
39-
"types/interfaces",
40-
"types/type-aliases",
41-
"shared/index",
42-
"shared/react",
43-
"shared/react/hooks",
44-
"shared/react/types",
45-
"shared/react/types/interfaces",
46-
"shared/react/types/type-aliases",
47-
"shared/index/classes",
48-
"shared/index/functions",
49-
"nextjs/app-router",
50-
"nextjs/server",
51-
"nextjs/server/build-clerk-props",
52-
"nextjs/server/clerk-middleware",
53-
"nextjs/server/create-get-auth",
54-
"nextjs/server/create-get-auth/functions",
55-
"nextjs/server/create-get-auth/variables",
56-
"nextjs/server/clerk-middleware/interfaces",
57-
"nextjs/server/clerk-middleware/variables",
58-
"nextjs/server/build-clerk-props/variables",
59-
"nextjs/app-router/server",
60-
"nextjs/app-router/server/auth",
61-
"nextjs/app-router/server/current-user",
62-
"nextjs/app-router/server/current-user/functions",
63-
"nextjs/app-router/server/auth/variables",
64-
"clerk-react/functions",
65-
"clerk-react/interfaces",
6639
]
6740
`);
6841
});

‎.typedoc/custom-plugin.mjs‎

Lines changed: 41 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -26,6 +26,8 @@ const LINK_REPLACEMENTS = [
2626
['session-resource', '/docs/references/javascript/session'],
2727
['signed-in-session-resource', '/docs/references/javascript/session'],
2828
['sign-up-resource', '/docs/references/javascript/sign-up'],
29+
['user-resource', '/docs/references/javascript/user'],
30+
['session-status-claim', '/docs/references/javascript/types/session-status'],
2931
];
3032

3133
/**
@@ -34,16 +36,45 @@ const LINK_REPLACEMENTS = [
3436
* It also shouldn't matter how level deep the relative link is.
3537
*
3638
* This function returns an array of `{ pattern: string, replace: string }` to pass into the `typedoc-plugin-replace-text` plugin.
39+
*
40+
* @example
41+
* [foo](../../bar.mdx) -> [foo](/new-path)
42+
* [foo](./bar.mdx) -> [foo](/new-path)
43+
* [foo](bar.mdx) -> [foo](/new-path)
44+
* [foo](bar.mdx#some-id) -> [foo](/new-path#some-id)
3745
*/
3846
function getRelativeLinkReplacements() {
3947
return LINK_REPLACEMENTS.map(([fileName, newPath]) => {
4048
return {
41-
pattern: new RegExp(`\\((?:\\.{1,2}\\/)+.*?${fileName}\\.mdx\\)`, 'g'),
42-
replace: `(${newPath})`,
49+
// Match both path and optional anchor
50+
pattern: new RegExp(`\\((?:(?:\\.{1,2}\\/)+[^()]*?|)${fileName}\\.mdx(#[^)]+)?\\)`, 'g'),
51+
// Preserve the anchor in replacement if it exists
52+
replace: (/** @type {string} */ _match, anchor = '') => `(${newPath}${anchor})`,
4353
};
4454
});
4555
}
4656

57+
function getUnlinkedTypesReplacements() {
58+
return [
59+
{
60+
pattern: /\(setActiveParams\)/g,
61+
replace: '([setActiveParams](/docs/references/javascript/types/set-active-params))',
62+
},
63+
{
64+
pattern: /`_LocalizationResource`/g,
65+
replace: '[Localization](/docs/customization/localization)',
66+
},
67+
{
68+
pattern: /`LoadedClerk`/g,
69+
replace: '[Clerk](/docs/references/javascript/clerk)',
70+
},
71+
{
72+
pattern: /`OrganizationCustomRoleKey`/g,
73+
replace: '[OrganizationCustomRoleKey](/docs/references/javascript/types/organization-custom-role-key)',
74+
},
75+
];
76+
}
77+
4778
/**
4879
* @param {import('typedoc-plugin-markdown').MarkdownApplication} app
4980
*/
@@ -58,6 +89,14 @@ export function load(app) {
5889
}
5990
}
6091

92+
const unlinkedTypesReplacements = getUnlinkedTypesReplacements();
93+
94+
for (const { pattern, replace } of unlinkedTypesReplacements) {
95+
if (output.contents) {
96+
output.contents = output.contents.replace(pattern, replace);
97+
}
98+
}
99+
61100
if (fileName) {
62101
if (FILES_WITHOUT_HEADINGS.includes(fileName)) {
63102
if (output.contents) {

0 commit comments

Comments
 (0)