From 4da49276f96d54c5e8ad1729577ee3cd6a2be019 Mon Sep 17 00:00:00 2001 From: Juuddi Date: Tue, 4 Jun 2024 15:19:34 -0500 Subject: [PATCH] Add link formatter plugin --- .../plugins/typedoc-plugin-link-formatter.mjs | 24 +++++++ .../typedoc-plugin-mintlify-frontmatter.mjs | 39 +++++------ .../typedoc-plugin-navigation-output.mjs | 30 ++++----- typedoc.json | 65 ++++++++++--------- 4 files changed, 92 insertions(+), 66 deletions(-) create mode 100644 docs/plugins/typedoc-plugin-link-formatter.mjs diff --git a/docs/plugins/typedoc-plugin-link-formatter.mjs b/docs/plugins/typedoc-plugin-link-formatter.mjs new file mode 100644 index 00000000..5a94c7c0 --- /dev/null +++ b/docs/plugins/typedoc-plugin-link-formatter.mjs @@ -0,0 +1,24 @@ +// @ts-check +import { MarkdownPageEvent } from 'typedoc-plugin-markdown'; + +/** + * This plugin adds a title and description to the frontmatter of each markdown page for compliance with Mintlify. + * + * @param {import('typedoc-plugin-markdown').MarkdownApplication} app + */ +export function load(app) { + app.renderer.on( + MarkdownPageEvent.END, + /** + * @param {import('typedoc-plugin-markdown').MarkdownPageEvent} page + */ + (page) => { + if (page.contents) { + if (page.contents.includes('.mdx')) { + const regex = /(\.mdx)/g; + page.contents = page.contents.replace(regex, ''); + } + } + }, + ); +} diff --git a/docs/plugins/typedoc-plugin-mintlify-frontmatter.mjs b/docs/plugins/typedoc-plugin-mintlify-frontmatter.mjs index 341a7fdf..2605664a 100644 --- a/docs/plugins/typedoc-plugin-mintlify-frontmatter.mjs +++ b/docs/plugins/typedoc-plugin-mintlify-frontmatter.mjs @@ -1,27 +1,28 @@ // @ts-check -import { MarkdownPageEvent } from 'typedoc-plugin-markdown' +import { MarkdownPageEvent } from 'typedoc-plugin-markdown'; /** - * This plugin adds a title and description to the frontmatter of - * each markdown page for compliance with Mintlify. + * This plugin adds a title and description to the frontmatter of each markdown page for compliance with Mintlify. * * @param {import('typedoc-plugin-markdown').MarkdownApplication} app */ export function load(app) { - app.renderer.on( - MarkdownPageEvent.BEGIN, - /** @param {import('typedoc-plugin-markdown').MarkdownPageEvent} page */ - (page) => { - let summary = '' - if (page.model?.comment?.summary) { - summary = page.model.comment.summary[0].text + '...' - summary = summary.replace(/\n/g, ' ') - } - page.frontmatter = { - title: page.model?.name, - description: summary, - ...page.frontmatter, - } - } - ) + app.renderer.on( + MarkdownPageEvent.BEGIN, + /** + * @param {import('typedoc-plugin-markdown').MarkdownPageEvent} page + */ + (page) => { + let summary = ''; + if (page.model?.comment?.summary) { + summary = page.model.comment.summary[0].text + '...'; + summary = summary.replace(/\n/g, ' '); + } + page.frontmatter = { + title: page.model?.name, + description: summary, + ...page.frontmatter, + }; + }, + ); } diff --git a/docs/plugins/typedoc-plugin-navigation-output.mjs b/docs/plugins/typedoc-plugin-navigation-output.mjs index ca682880..e684322b 100644 --- a/docs/plugins/typedoc-plugin-navigation-output.mjs +++ b/docs/plugins/typedoc-plugin-navigation-output.mjs @@ -1,22 +1,22 @@ // @ts-check -import fs from 'fs' +import fs from 'fs'; /** - * This plugin parses and generates a navigation file for the documentation - * that complies with Mintlify's navigation format. + * This plugin parses and generates a navigation file for the documentation that complies with Mintlify's navigation + * format. * - * @param {import('typedoc-plugin-markdown').MarkdownApplication} app + * @param {import('typedoc-plugin-markdown').MarkdownApplication} app */ export function load(app) { - app.renderer.postRenderAsyncJobs.push(async (renderer) => { - const navigation = renderer.navigation - if (!navigation) { - return - } - const formattedNavigation = navigation.map((group) => ({ - group: group.title, - pages: (group.children || []).map((child) => `content/${child.url.replace('.mdx', '')}`), - })) - fs.writeFileSync('./docs/content/navigation.json', JSON.stringify(formattedNavigation, null, 2)) - }) + app.renderer.postRenderAsyncJobs.push(async (renderer) => { + const navigation = renderer.navigation; + if (!navigation) { + return; + } + const formattedNavigation = navigation.map((group) => ({ + group: group.title, + pages: (group.children || []).map((child) => `content/${child.url.replace('.mdx', '')}`), + })); + fs.writeFileSync('./docs/content/navigation.json', JSON.stringify(formattedNavigation, null, 2)); + }); } diff --git a/typedoc.json b/typedoc.json index 63e192d5..e618b4f7 100644 --- a/typedoc.json +++ b/typedoc.json @@ -1,37 +1,38 @@ { - // base config - "out": "docs/content", - "tsconfig": "tsconfig.base.json", - "entryPoints": ["./src/quais.ts"], + // base config + "out": "docs/content", + "tsconfig": "tsconfig.base.json", + "entryPoints": ["./src/quais.ts"], - // specific inclusions and exclusions - "excludeProtected": true, - "excludeNotDocumented": true, - "exclude": ["./src/_admin/**/*", "./src/_tests/**/*", "./src/testcases/**/*"], + // specific inclusions and exclusions + "excludeProtected": true, + "excludeNotDocumented": true, + "exclude": ["./src/_admin/**/*", "./src/_tests/**/*", "./src/testcases/**/*"], - // plugins - "plugin": [ - "typedoc-plugin-remove-references", // remove additional references that clutter documentation - "typedoc-plugin-markdown", // generate markdown files - "typedoc-plugin-frontmatter", // add frontmatter to markdown files, prereq for the below custom plugin - "./docs/plugins/typedoc-plugin-mintlify-frontmatter.mjs", // formats frontmatter to match mintlify - "./docs/plugins/typedoc-plugin-navigation-output.mjs" // formats navigation to match mintlify - ], + // plugins + "plugin": [ + "typedoc-plugin-remove-references", // remove additional references that clutter documentation + "typedoc-plugin-markdown", // generate markdown files + "typedoc-plugin-frontmatter", // add frontmatter to markdown files, prereq for the below custom plugin + "./docs/plugins/typedoc-plugin-mintlify-frontmatter.mjs", // formats frontmatter to match mintlify + "./docs/plugins/typedoc-plugin-navigation-output.mjs", // formats navigation to match mintlify + "./docs/plugins/typedoc-plugin-link-formatter.mjs" // removes ".mdx" from links + ], - // formatting + mintlify compatibility - "fileExtension": ".mdx", // use mdx files for mintlfiy compatibility - "entryFileName": "index.mdx", // rename entry from "README.md" to "index.mdx" - "mergeReadme": true, // merge README.md into index.mdx - "hidePageHeader": true, // hide page header, conflicts with mintlify - "hidePageTitle": true, // hide page title, conflicts with mintlify - "hideBreadcrumbs": true, // hide breadcrumbs, conflicts with mintlify - "useCodeBlocks": true, // makes API definitions more readable - "expandObjects": true, - "parametersFormat": "table", // readability - "propertiesFormat": "table", // readability - "publicPath": "/content/", // format links for mintlify - "navigation": { - "includeCategories": true, - "includeGroups": false - } + // formatting + mintlify compatibility + "fileExtension": ".mdx", // use mdx files for mintlfiy compatibility + "entryFileName": "index.mdx", // rename entry from "README.md" to "index.mdx" + "mergeReadme": true, // merge README.md into index.mdx + "hidePageHeader": true, // hide page header, conflicts with mintlify + "hidePageTitle": true, // hide page title, conflicts with mintlify + "hideBreadcrumbs": true, // hide breadcrumbs, conflicts with mintlify + "useCodeBlocks": true, // makes API definitions more readable + "expandObjects": true, + "parametersFormat": "table", // readability + "propertiesFormat": "table", // readability + "publicPath": "/content/", // format links for mintlify + "navigation": { + "includeCategories": true, + "includeGroups": false + } }