diff --git a/docs/pages/api-docs/Interface.PluginOptions.md b/docs/pages/api-docs/Interface.PluginOptions.md index 45226490..73a36308 100644 --- a/docs/pages/api-docs/Interface.PluginOptions.md +++ b/docs/pages/api-docs/Interface.PluginOptions.md @@ -8,7 +8,7 @@ Describes the options declared by the plugin. > **anchorPrefix**: `string` -Custom anchor prefix +Custom anchor prefix when anchoring to in-page symbols. *** @@ -32,7 +32,7 @@ The name of a module that should act as the root page for the documentation. > **enumMembersFormat**: `"table"` \| `"list"` -Specify the render style of enumuration members. +Specify the render style of enumeration members. *** @@ -116,22 +116,6 @@ Specify the render format for index items. *** -### indexPageTitle - -> **indexPageTitle**: `string` - -The title of project index page. - -*** - -### memberPageTitle - -> **memberPageTitle**: `string` - -The page title of member pages. - -*** - ### membersWithOwnFile > **membersWithOwnFile**: (`"Enum"` \| `"Variable"` \| `"Function"` \| `"Class"` \| `"Interface"` \| `"TypeAlias"`)[] diff --git a/docs/pages/api-docs/index.mdx b/docs/pages/api-docs/index.mdx index 1b17a53e..8a686a49 100644 --- a/docs/pages/api-docs/index.mdx +++ b/docs/pages/api-docs/index.mdx @@ -1,6 +1,6 @@ # API -The public API of the plugin exposes some classes and types that can be used to extend the plugin. Please note this only covers the API relevant to this plugin and not cover the entire [TypeDoc API](https://typedoc.org/api/). +The public API of the typedoc-plugin-markdown exposes some classes and types that can be used to customize the output of the plugin. Please note this only covers the API relevant to this plugin and not cover the entire [TypeDoc API](https://typedoc.org/api/). The APIs are typically consumed by writing [local plugins](/docs/customizing-output#local-plugins). diff --git a/docs/pages/docs/_meta.js b/docs/pages/docs/_meta.js index c24adf55..fc9ec4f7 100644 --- a/docs/pages/docs/_meta.js +++ b/docs/pages/docs/_meta.js @@ -17,6 +17,5 @@ export default { type: 'separator', title: 'Support', }, - examples: '', changelog: '', }; diff --git a/docs/pages/docs/examples.mdx b/docs/pages/docs/examples.mdx deleted file mode 100644 index 374f93eb..00000000 --- a/docs/pages/docs/examples.mdx +++ /dev/null @@ -1,24 +0,0 @@ -import { Cards, Callout } from 'nextra/components'; -import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'; -import { faGithub } from '@fortawesome/free-brands-svg-icons'; -import { faExternalLinkAlt } from '@fortawesome/free-solid-svg-icons'; - -# Examples - -Here is a list of examples showcasing the output generated using the plugin. Available on GitHub . - -## Index - -| Example | Description | -| :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------ | -| [Default options ](https://raw.githubusercontent.com/tgreyuk/typedoc-plugin-markdown-examples/main/examples/01-default-options-example/docs/README.md) | This example uses the default settings of the plugin. | -| [Customized UX options ](https://raw.githubusercontent.com/tgreyuk/typedoc-plugin-markdown-examples/main/examples/02-ux-options-example/docs/README.md) | This example showcases how the UX can be customised. | -| [Single page modules ](https://raw.githubusercontent.com/tgreyuk/typedoc-plugin-markdown-examples/main/examples/03-single-page-modules-example/docs/README.md) | This example demonstrates output with single page modules. | -| [Single page docs ](https://raw.githubusercontent.com/tgreyuk/typedoc-plugin-markdown-examples/main/examples/04-single-page-docs-example/docs/README.md) | This example shows the output to a single page with a single entry point. | -| [Packages ](https://raw.githubusercontent.com/tgreyuk/typedoc-plugin-markdown-examples/main/examples/05-packages-example/docs/README.md) | This example showcases packages mode. | - -## Repository - -For clearer viewing, these examples open on `https://raw.githubusercontent.com`. - -If you would like to view the configuration and source then explore the [examples GitHub repository ](https://github.com/tgreyuk/typedoc-plugin-markdown-examples) in the normal web interface. diff --git a/docs/pages/docs/index.mdx b/docs/pages/docs/index.mdx index 52c5e38a..68d66c31 100644 --- a/docs/pages/docs/index.mdx +++ b/docs/pages/docs/index.mdx @@ -1,5 +1,7 @@ import { Cards, Callout } from 'nextra/components'; import pjson from '../../../packages/typedoc-plugin-markdown/package.json'; +import { FontAwesomeIcon } from '@fortawesome/react-fontawesome'; +import { faGithub } from '@fortawesome/free-brands-svg-icons'; # typedoc-plugin-markdown @@ -7,9 +9,9 @@ import pjson from '../../../packages/typedoc-plugin-markdown/package.json'; ## Overview -By default [TypeDoc](https://typedoc.org) will output API documentation as HTML. +By default [TypeDoc](https://typedoc.org) will output API documentation as HTML. The plugin replaces the default HTML theme with a built-in Markdown theme and exposes some additional options. -This plugin enables TypeDoc to output documentation in Markdown. Since many tools and platforms support Markdown, the documentation generated by this plugin can be easily integrated into different ecosystems, such as code repositories, static site generators or documentation hosting services. +Since many tools and platforms support Markdown, the documentation generated by this plugin can be easily integrated into different ecosystems, such as code repositories, static site generators or documentation hosting services. ## Features @@ -18,3 +20,17 @@ This plugin enables TypeDoc to output documentation in Markdown. Since many tool - Configurable output file structure. - Configurable UX options - [Frontmatter](/plugins/frontmatter) and [Remark](/plugins/remark) utility plugins available. + +## Examples + +Visit the dedicated examples repository of examples showcasing the output generated using the plugin. + + + } + arrow={true} + href="https://github.com/tgreyuk/typedoc-plugin-markdown-examples" + target="_blank" + /> + diff --git a/docs/pages/docs/options.mdx b/docs/pages/docs/options.mdx index 564e44c8..e8bb49a0 100644 --- a/docs/pages/docs/options.mdx +++ b/docs/pages/docs/options.mdx @@ -630,7 +630,9 @@ This option would typically be used when source code comes from an external libr ### anchorPrefix -Custom anchor prefix + + Custom anchor prefix when anchoring to in-page symbols. + > Accepts a string value. Defaults to `"undefined"`. diff --git a/docs/pages/docs/using-typedoc.mdx b/docs/pages/docs/using-typedoc.mdx index a0806ef7..d1588598 100644 --- a/docs/pages/docs/using-typedoc.mdx +++ b/docs/pages/docs/using-typedoc.mdx @@ -4,11 +4,45 @@ import { Callout, FileTree } from 'nextra/components'; This plugin is like any other TypeDoc plugin and is fully compatible with the TypeDoc ecosystem, supporting other plugins (not specifically targetting HTML output) and the majority of TypeDoc's options. -## TypeDoc Options +Please refer to TypeDoc's [Configuration Options](https://typedoc.org/options/configuration/) for detailed information on how to configure options. + +## Option Typings + +You can inform your IDE about the shape of the exported options the plugin provides. + +### JSON Files + +You can utilize the provided JSON schema at https://typedoc-plugin-markdown.org/schema.json. For simplicity of configuration, this schema consolidates all options from TypeDoc and the plugin. + +```json filename="typedoc.json" +{ + "$schema": "https://typedoc-plugin-markdown.org/schema.json", + "entryPoints": ["./src/index.ts", "./src/secondary-entry.ts"], + "out": "docs", + "plugin": ["typedoc-plugin-markdown", "some-other-plugin"], +}; +``` + +### JavaScript Files + +For JavaScript files, the `PluginOptions` interface that can be imported to a `typedoc.config.js` file with a `@type` annotation. + +You can use intersection types to combine the TypeDoc options with the plugin options. + +```js filename="typedoc.config.js" +/** @type {import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions} */ +module.exports = { + entryPoints: ['./src/index.ts', './src/secondary-entry.ts'], + out: 'doc', + plugin: ['typedoc-plugin-markdown', 'some-other-plugin'], +}; +``` + +## Supported TypeDoc Options ### Pre-Render Options -Most of [TypeDoc's options](https://typedoc.org/options/) are used internally by TypeDoc to convert a project and define the structure of the models. +The majority of [TypeDoc's options](https://typedoc.org/options/) are used internally by TypeDoc to convert a project and define the structure of the models. These options are output/theme agnostic and can be set in the same as you would with the HTML theme: @@ -47,16 +81,3 @@ Below is a list of which TypeDoc Output options are supported or not: - `--gaID` No ❌ - `--hideGenerator` No ❌ - `--searchInComments` No ❌ - -## Option Typings - -If you would like to inform your IDE about the shape of the exported options the plugin provides a `PluginOptions` interface that can be imported to a `typedoc.config.js` file with a `@type` annotation: - -```js filename="typedoc.config.js" -/** @type {import('typedoc').TypeDocOptions & import('typedoc-plugin-markdown').PluginOptions} */ -module.exports = { - entryPoints: ['./src/index.ts', './src/secondary-entry.ts'], - out: 'doc', - plugin: ['typedoc-plugin-markdown', 'some-other-plugin'], -}; -``` diff --git a/docs/pages/plugins/frontmatter.mdx b/docs/pages/plugins/frontmatter.mdx index 4b57d9be..218f27cc 100644 --- a/docs/pages/plugins/frontmatter.mdx +++ b/docs/pages/plugins/frontmatter.mdx @@ -36,7 +36,7 @@ Please see the [option guide](/plugins/frontmatter/options) for available config title="View on Github" icon={} arrow={true} - href="https://github.com/tgreyuk/typedoc-plugin-markdown-examples/tree/main/examples/02-typedoc-plugin-frontmatter" + href="https://github.com/tgreyuk/typedoc-plugin-markdown-examples/tree/main/examples/08-frontmatter-example#readme" target="_blank" /> diff --git a/docs/pages/plugins/github-wiki.mdx b/docs/pages/plugins/github-wiki.mdx index 5bd4bed9..b7043c6b 100644 --- a/docs/pages/plugins/github-wiki.mdx +++ b/docs/pages/plugins/github-wiki.mdx @@ -29,7 +29,7 @@ The following is a simple example of a GithubWiki project running TypeDoc. title="View Source on Github" icon={} arrow={true} - href="https://github.com/tgreyuk/typedoc-plugin-markdown-examples/tree/main/examples/04-typedoc-github-wiki-theme" + href="https://github.com/tgreyuk/typedoc-plugin-markdown-examples/tree/main/examples/07-typedoc-github-wiki-theme" target="_blank" /> diff --git a/docs/theme.config.jsx b/docs/theme.config.jsx index a0714595..58daca0a 100644 --- a/docs/theme.config.jsx +++ b/docs/theme.config.jsx @@ -29,7 +29,7 @@ export default { sidebar: { defaultMenuCollapseLevel: 1, }, - editLink: { text: 'x' }, + editLink: { content: '' }, banner: { content: ( <> diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts index 39b7bfc8..d3ec1cde 100644 --- a/packages/typedoc-plugin-markdown/src/options/declarations.ts +++ b/packages/typedoc-plugin-markdown/src/options/declarations.ts @@ -483,7 +483,7 @@ export const sanitizeComments: Partial = { * @category Utility */ export const anchorPrefix: Partial = { - help: 'Custom anchor prefix', + help: 'Custom anchor prefix when anchoring to in-page symbols.', type: ParameterType.String, defaultValue: undefined, }; diff --git a/packages/typedoc-plugin-markdown/src/options/index.ts b/packages/typedoc-plugin-markdown/src/options/index.ts index daa1c9a6..bfb1c53b 100644 --- a/packages/typedoc-plugin-markdown/src/options/index.ts +++ b/packages/typedoc-plugin-markdown/src/options/index.ts @@ -1,3 +1,8 @@ +import { TypeDocOptions } from 'typedoc'; +import { PluginOptions } from './option-types'; + export * from './option-maps'; export * from './option-types'; export * from './text-mappings'; + +export type Options = TypeDocOptions & PluginOptions; diff --git a/packages/typedoc-plugin-markdown/src/options/option-types.ts b/packages/typedoc-plugin-markdown/src/options/option-types.ts index e9624ccb..04d1cb4c 100644 --- a/packages/typedoc-plugin-markdown/src/options/option-types.ts +++ b/packages/typedoc-plugin-markdown/src/options/option-types.ts @@ -52,7 +52,7 @@ declare module 'typedoc' { */ export interface PluginOptions { /** - * Custom anchor prefix + * Custom anchor prefix when anchoring to in-page symbols. */ anchorPrefix: string; diff --git a/packages/typedoc-plugin-markdown/src/public-api.ts b/packages/typedoc-plugin-markdown/src/public-api.ts index b94ad303..e825c88e 100644 --- a/packages/typedoc-plugin-markdown/src/public-api.ts +++ b/packages/typedoc-plugin-markdown/src/public-api.ts @@ -1,5 +1,5 @@ /** - * The public API of the plugin exposes some classes and types that can be used to extend the plugin. Please note this only covers the API relevant to this plugin and not cover the entire [TypeDoc API](https://typedoc.org/api/). + * The public API of the typedoc-plugin-markdown exposes some classes and types that can be used to customize the output of the plugin. Please note this only covers the API relevant to this plugin and not cover the entire [TypeDoc API](https://typedoc.org/api/). * * The APIs are typically consumed by writing [local plugins](/docs/customizing-output#local-plugins). *