diff --git a/packages/typedoc-plugin-markdown/README.md b/packages/typedoc-plugin-markdown/README.md index 605a628e4..f9030b457 100644 --- a/packages/typedoc-plugin-markdown/README.md +++ b/packages/typedoc-plugin-markdown/README.md @@ -1,6 +1,6 @@ # typedoc-plugin-markdown -![npm](https://img.shields.io/npm/v/typedoc-plugin-markdown%2Fnext?&logo=npm) [![Build Status](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml) +![npm](https://img.shields.io/npm/v/typedoc-plugin-markdown%2Fnext?\&logo=npm) [![Build Status](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml/badge.svg?branch=master)](https://github.com/tgreyuk/typedoc-plugin-markdown/actions/workflows/ci.yml) > **Please note this pre-release version may contain breaking changes within the same semantic version.** @@ -8,14 +8,13 @@ A plugin for [TypeDoc](https://typedoc.org) that renders TypeScript API document ## Contents -- [What does it do?](#what-does-it-do) -- [Installation](#installation) -- [Usage](#usage) -- [Plugin Options](#plugin-options) -- [Customization](#customization) -- [Examples](#examples) -- [Contributing](#contributing) -- [License](#license) +* [What does it do?](#what-does-it-do) +* [Installation](#installation) +* [Usage](#usage) +* [Plugin Options](#plugin-options) +* [Custom templates](#custom-templates) +* [Contributing](#contributing) +* [License](#license) ## What does it do? @@ -31,67 +30,69 @@ npm install typedoc typedoc-plugin-markdown@next --save-dev ## Usage -Specify the using the `plugin` configuration option. +### How to load the plugin? + +Plugins are loaded by using the `plugin` configuration option: + +Via the command line. ```bash typedoc --plugin typedoc-plugin-markdown ``` -This guide assumes familarity with TypeDoc and please refer to [TypeDoc documenation](https://typedoc.org/guides/installation/) on how to use TypeDoc in general. - -Please note: +Using a `typedoc.json` config file or under the `typedocOptions` key in `tsconfig.json`. -- All of TypeDoc's [Configuration](https://typedoc.org/options/configuration/), [Input](https://typedoc.org/options/input/) and [Organization](https://typedoc.org/options/organization/) options are all respected as these are executed at the conversion phase of the project. +```json +{ "plugin": ["typedoc-plugin-markdown"] } +``` -- TypeDoc's [Output](https://typedoc.org/options/output/) options are relevant to the rendering phase and are HTML output specific and are ignored by this plugin with the exception of [`--cleanOutputDir`](). +Please see for general TypeDoc option configuration. -## Options +### What TypeDoc options are supported? -Additional [Output](./docs/guides/options/output.md), [Frontmatter](./docs/guides/options/ui.md) and [Remark](./docs/guides/options/utility.md) options exposed by this plugin. +* All of TypeDoc's [Configuration](https://typedoc.org/options/configuration/), [Input](https://typedoc.org/options/input/) and [Organization](https://typedoc.org/options/organization/) options are all respected as these are executed at the conversion phase of the project. -### File Options +* TypeDoc's [Output](https://typedoc.org/options/output/) options are relevant to the rendering phase and in the main HTML output specific and are ignored by this plugin with the exception of [`--out`]() and [`--cleanOutputDir`](). -Options which control how output files are generated. +## Plugin Options -- [`--outputFileStrategy`]() -- [`--includeFileNumberPrefixes`]() -- [`--flattenOutputFiles`]() -- [`--entryFileName`]() -- [`--indexFileName`]() -- [`--indexPageTitle`]() -- [`--skipIndexPage`]() +This plugin exposes additional options. Please see [Options Guide](./docs/guides/options.md) for detailed usage. -### UI Options +### Output Options -Options which control the format of the output on the page. +Options that define how output files are generated. -- [`--excludeGroups`]() -- [`--hidePageHeader`]() -- [`--hidePageTitle`]() -- [`--hideBreadcrumbs`]() -- [`--hideInPageTOC`]() -- [`--hideHierarchy`]() -- [`--identifiersAsCodeBlocks`]() -- [`--propertiesFormat`]() -- [`--enumMembersFormat`]() -- [`--typeDeclarationFormat`]() -- [`--tocFormat`]() -- [`--titleTemplate`]() +* [`--outputFileStrategy`]() +* [`--includeFileNumberPrefixes`]() +* [`--flattenOutputFiles`]() +* [`--entryFileName`]() +* [`--indexFileName`]() +* [`--indexPageTitle`]() +* [`--skipIndexPage`]() +* [`--preserveAnchorCasing`]() +* [`--anchorPrefix`]() -### Utility Options +### UI Options -- [`--remarkPlugins`]() -- [`--translations`]() -- [`--preserveAnchorCasing`]() +UI Options + +* [`--excludeGroups`](./docs/guides/options.md#--excludegroups) +* [`--hidePageHeader`](./docs/guides/options.md#--hidepageheader) +* [`--hidePageTitle`](./docs/guides/options.md#--hidepagetitle) +* [`--hideBreadcrumbs`](./docs/guides/options.md#--hidebreadcrumbs) +* [`--hideInPageTOC`](./docs/guides/options.md#--hideinpagetoc) +* [`--hideHierarchy`](./docs/guides/options.md#--hidehierarchy) +* [`--identifiersAsCodeBlocks`](./docs/guides/options.md#--identifiersascodeblocks) +* [`--propertiesFormat`](./docs/guides/options.md#--propertiesformat) +* [`--enumMembersFormat`](./docs/guides/options.md#--enummembersformat) +* [`--typeDeclarationFormat`](./docs/guides/options.md#--typedeclarationformat) +* [`--tocFormat`](./docs/guides/options.md#--tocformat) +* [`--titleTemplate`](./docs/guides/options.md#--titletemplate) ## Custom templates Coming soon -## Examples - -Coming soon - ## Contributing Contributions and suggestions are welcome. Please see the [contributing guidelines](CONTRIBUTING.md) for further details. diff --git a/packages/typedoc-plugin-markdown/docs/guides/options.md b/packages/typedoc-plugin-markdown/docs/guides/options.md index 168c042db..9ad8b616a 100644 --- a/packages/typedoc-plugin-markdown/docs/guides/options.md +++ b/packages/typedoc-plugin-markdown/docs/guides/options.md @@ -1,58 +1,59 @@ -# Plugin Options - -Some introduction to options. +# Options Guide ## Contents -- [Output Options](#output-options) - - - [`--outputFileStrategy`](#--outputfilestrategy) `Output` - - [`--includeFileNumberPrefixes`](#--includefilenumberprefixes) - - [`--flattenOutputFiles`](#--flattenoutputfiles) - - [`--entryFileName`](#--entryfilename) - - [`--indexFileName`](#--indexfilename) - - [`--indexPageTitle`](#--indexpagetitle) - - [`--skipIndexPage`](#--skipindexpage) - - [`--excludeGroups`](#--excludegroups) - - [`--hidePageHeader`](#--hidepageheader) - - [`--hidePageTitle`](#--hidepagetitle) - - [`--hideBreadcrumbs`](#--hidebreadcrumbs) - - [`--hideInPageTOC`](#--hideinpagetoc) - - [`--hideHierarchy`](#--hidehierarchy) - - [`--identifiersAsCodeBlocks`](#--identifiersascodeblocks) - - [`--propertiesFormat`](#--propertiesformat) - - [`--enumMembersFormat`](#--enummembersformat) - - [`--typeDeclarationFormat`](#--typedeclarationformat) - - [`--tocFormat`](#--tocformat) - - [`--titleTemplate`](#--titletemplate) - - [`--preserveAnchorCasing`](#--preserveanchorcasing) - -- [Frontmatter Options](#frontmatter-options) - - - [`--frontmatterVars`](#--frontmattervars) - - [`--frontmatterDocTags`](#--frontmatterdoctags) - - [`--frontmatterFormat`](#--frontmatterformat) - -- [Remark Options](#remark-options) - - - [`--remarkPlugins`](#--remarkplugins) - - [`--remarkSettings`](#--remarksettings) - -## Output Options +* [File Options](#file-options) + + * [`--outputFileStrategy`](#--outputfilestrategy) + * [`--includeFileNumberPrefixes`](#--includefilenumberprefixes) + * [`--flattenOutputFiles`](#--flattenoutputfiles) + * [`--entryFileName`](#--entryfilename) + * [`--indexFileName`](#--indexfilename) + * [`--indexPageTitle`](#--indexpagetitle) + * [`--skipIndexPage`](#--skipindexpage) + * [`--preserveAnchorCasing`](#--preserveanchorcasing) + * [`--anchorPrefix`](#--anchorprefix) + +* [UI Options](#ui-options) + + * [`--excludeGroups`](#--excludegroups) + * [`--hidePageHeader`](#--hidepageheader) + * [`--hidePageTitle`](#--hidepagetitle) + * [`--hideBreadcrumbs`](#--hidebreadcrumbs) + * [`--hideInPageTOC`](#--hideinpagetoc) + * [`--hideHierarchy`](#--hidehierarchy) + * [`--identifiersAsCodeBlocks`](#--identifiersascodeblocks) + * [`--propertiesFormat`](#--propertiesformat) + * [`--enumMembersFormat`](#--enummembersformat) + * [`--typeDeclarationFormat`](#--typedeclarationformat) + * [`--tocFormat`](#--tocformat) + * [`--titleTemplate`](#--titletemplate) + +## File Options + +Options that define how output files are generated. + +*** ### `--outputFileStrategy` +> Determines how output files are generated. + +#### Type + `"members" | "modules"` -> Determines how output files are generated. +#### Default ```json { "outputFileStrategy": "members" -} +} ``` -TypeDoc creates documentation according to exports. The structure will be driven by the implemented entryPoints config. https\://typedoc.org/guides/options/#entrypointstrategy. +#### Usage + +TypeDoc creates documentation according to exports. The structure will be driven by the implemented entryPoints config. https://typedoc.org/guides/options/#entrypointstrategy. This options aims to provide some flexibility as to how files can be generated. @@ -68,56 +69,80 @@ Generates a single file for every Module or Namespace where all members are hois ![outputFileStrategy modules folders](../images/options/outputFileStrategy-modules.png) ---- +[↑ Top](#options-guide) + +*** ### `--includeFileNumberPrefixes` +> Prefixes generated files and folders with number prefixes. + +#### Type + `boolean` -> Prefixes generated files and folders with number prefixes. +#### Default ```json { "includeFileNumberPrefixes": "false" -} +} ``` +#### Usage + This makes files and folders appear in the file system in the same order as they are sorted. This is useful where auto sidebar generation may be required. ![includeFileNumberPrefixes folders](../images/options/includeFileNumberPrefixes.png) ---- +[↑ Top](#options-guide) + +*** ### `--flattenOutputFiles` +> Flatten output files without folders. + +#### Type + `boolean` -> Flatten output files without folders. +#### Default ```json { "flattenOutputFiles": "false" -} +} ``` +#### Usage + This creates a flat folder structure without any folders - a required format for some Wikis. ![flattenOutputFiles folders](../images/options/flattenOutputFiles.png) ---- +[↑ Top](#options-guide) + +*** ### `--entryFileName` +> The file name of the entry page. + +#### Type + `string` -> The file name of the entry page. +#### Default ```json { "entryFileName": "README.md" -} +} ``` +#### Usage + `README.md` is recognised when browsing folders on repos and Wikis. `index.md` might be better if published as a web site. Note the content of this file is either the API entry / index page, or the project readme (dependant on if a readme file is resolved or not). @@ -131,72 +156,154 @@ b. If a readme file is NOT resolved, then the index page becomes the entryFileNa ├── {entryFileName} - (API index page) ---- +[↑ Top](#options-guide) + +*** ### `--indexFileName` +> The file name the seperate index page. + +#### Type + `string` -> The file name the seperate index page. +#### Default ```json { "indexFileName": "API.md" -} +} ``` +#### Usage + This page either contains the module index or exported symbols depending on the given `entryPoints`. This page may not be required (if navigation is present for example) and can be skipped. See `skipIndexPage`. This option is ignored if `readme=none` or `skipIndexPage=true`. ---- +[↑ Top](#options-guide) + +*** ### `--indexPageTitle` +> The title of API index page. + +#### Type + `string` -> The title of API index page. +#### Default ```json { - "indexPageTitle": "API Reference" -} + "indexPageTitle": "API" +} ``` ---- +#### Usage + +[↑ Top](#options-guide) + +*** ### `--skipIndexPage` +> Skips generation of a seperate API index page. + +#### Type + `boolean` -> Skips generation of a seperate API index page. +#### Default ```json { "skipIndexPage": "false" -} +} ``` +#### Usage + This option skips the generation of the index page if it is not required. Please note this option will be ignored if a single entryPoint is defined as it will contain exported symbols. ---- +[↑ Top](#options-guide) -### `--excludeGroups` +*** + +### `--preserveAnchorCasing` + +> Preserve anchor casing when generating links. + +#### Type `boolean` +#### Default + +```json +{ + "preserveAnchorCasing": "false" +} +``` + +#### Usage + +[↑ Top](#options-guide) + +*** + +### `--anchorPrefix` + +> Custom anchor prefix + +#### Type + +`string` + +#### Default + +```json +{ + "anchorPrefix": "undefined" +} +``` + +#### Usage + +[↑ Top](#options-guide) + +*** + +## UI Options + +UI Options + +*** + +### `--excludeGroups` + > Excludes grouping by reflection kind so all members are rendered and sorted at the same level. +#### Type + +`boolean` + +#### Default + ```json { "excludeGroups": "false" -} +} ``` +#### Usage + By default members are grouped by kind (eg Classes, Functions etc). This creates a flat structure where all members are displayed at the same level. @@ -225,252 +332,254 @@ This creates a flat structure where all members are displayed at the same level. ## FunctionA ``` ---- +[↑ Top](#options-guide) + +*** ### `--hidePageHeader` +> Do not print page header. + +#### Type + `boolean` -> Do not print page header. +#### Default ```json { "hidePageHeader": "false" -} +} ``` ---- +#### Usage + +[↑ Top](#options-guide) + +*** ### `--hidePageTitle` +> Do not print page title. + +#### Type + `boolean` -> Do not print page title. +#### Default ```json { "hidePageTitle": "false" -} +} ``` ---- +#### Usage + +[↑ Top](#options-guide) + +*** ### `--hideBreadcrumbs` +> Do not print breadcrumbs. + +#### Type + `boolean` -> Do not print breadcrumbs. +#### Default ```json { "hideBreadcrumbs": "false" -} +} ``` ---- +#### Usage + +[↑ Top](#options-guide) + +*** ### `--hideInPageTOC` +> Do not render in-page TOC/Index items. + +#### Type + `boolean` -> Do not render in-page TOC/Index items. +#### Default ```json { "hideInPageTOC": "false" -} +} ``` ---- +#### Usage + +[↑ Top](#options-guide) + +*** ### `--hideHierarchy` +> Do not print reflection hierarchy. + +#### Type + `boolean` -> Do not print reflection hierarchy. +#### Default ```json { "hideHierarchy": "false" -} +} ``` ---- +#### Usage + +[↑ Top](#options-guide) + +*** ### `--identifiersAsCodeBlocks` +> Format signature and declaration identifiers in code blocks. + +#### Type + `boolean` -> Format signature and declaration identifiers in code blocks. +#### Default ```json { "identifiersAsCodeBlocks": "false" -} +} ``` +#### Usage + Note if `true` references will not be linked. ---- +[↑ Top](#options-guide) -### `--propertiesFormat` +*** -`"list" | "table"` +### `--propertiesFormat` > Specify the render style of properties groups for interfaces and classes. -```json -{ - "propertiesFormat": "list" -} -``` - ---- - -### `--enumMembersFormat` +#### Type `"list" | "table"` -> Specify the render style of Enum members. +#### Default ```json { - "enumMembersFormat": "list" -} + "propertiesFormat": "list" +} ``` ---- +#### Usage -### `--typeDeclarationFormat` - -`"list" | "table"` +[↑ Top](#options-guide) -> Specify the render style for type declaration members. +*** -```json -{ - "typeDeclarationFormat": "list" -} -``` +### `--enumMembersFormat` ---- +> Specify the render style of Enum members. -### `--tocFormat` +#### Type `"list" | "table"` -> Render TOC either as a simple list or a table with a description. +#### Default ```json { - "tocFormat": "list" -} + "enumMembersFormat": "list" +} ``` ---- - -### `--titleTemplate` - -`string` - -> Specify a template for displaying page titles. +#### Usage -```json -{ - "titleTemplate": "{kind}: {name}" -} -``` +[↑ Top](#options-guide) -Supports {kind} and {name} placeholders. +*** - titleTemplate: "{kind}: {name}" +### `--typeDeclarationFormat` ---- +> Specify the render style for type declaration members. -### `--preserveAnchorCasing` +#### Type -`boolean` +`"list" | "table"` -> Preserve anchor casing when generating links. +#### Default ```json { - "preserveAnchorCasing": "false" -} + "typeDeclarationFormat": "list" +} ``` ---- - -## Frontmatter Options - -### `--frontmatterVars` +#### Usage -`string` +[↑ Top](#options-guide) -> Specify static variables to be added to all frontmatter. +*** -```json -{ - "frontmatterVars": "[object Object]" -} -``` +### `--tocFormat` ---- +> Render TOC either as a simple list or a table with a description. -### `--frontmatterDocTags` +#### Type -`any[]` +`"list" | "table"` -> Specify which file comment tags should be added to frontmatter. +#### Default ```json { - "frontmatterDocTags": "" -} + "tocFormat": "list" +} ``` ---- - -### `--frontmatterFormat` +#### Usage -`boolean` - -> Jsdoc tags cannot be snake case. Tags by default must be camelCase +[↑ Top](#options-guide) -```json -{ - "frontmatterFormat": "false" -} -``` +*** ---- +### `--titleTemplate` -## Remark Options +> Specify a template for displaying page titles. -### `--remarkPlugins` +#### Type -`any[]` +`string` -> Remark Plugins. +#### Default ```json { - "remarkPlugins": "" -} + "titleTemplate": "{kind}: {name}" +} ``` ---- +#### Usage -### `--remarkSettings` - -`any[]` +Supports {kind} and {name} placeholders. -> Remark Settings. + titleTemplate: "{kind}: {name}" -```json -{ - "remarkSettings": "" -} -``` +[↑ Top](#options-guide) ---- +*** diff --git a/packages/typedoc-plugin-markdown/docs/guides/options/frontmatter.md b/packages/typedoc-plugin-markdown/docs/guides/options/frontmatter.md deleted file mode 100644 index d8b0f671b..000000000 --- a/packages/typedoc-plugin-markdown/docs/guides/options/frontmatter.md +++ /dev/null @@ -1,43 +0,0 @@ -# Frontmatter Options - -## Contents - -* [frontmatterVars](#frontmattervars) -* [frontmatterDocTags](#frontmatterdoctags) -* [frontmatterFormat](#frontmatterformat) - -## frontmatterVars - -**`string`** - -Specify static variables to be added to all frontmatter. - -```json -{ - frontmatterVars: "[object Object]" -} -``` - -## frontmatterDocTags - -**`any[]`** - -Specify which file comment tags should be added to frontmatter. - -```json -{ - frontmatterDocTags: "" -} -``` - -## frontmatterFormat - -**`boolean`** - -Jsdoc tags cannot be snake case. Tags by default must be camelCase - -```json -{ - frontmatterFormat: "false" -} -``` diff --git a/packages/typedoc-plugin-markdown/docs/guides/options/options.md b/packages/typedoc-plugin-markdown/docs/guides/options/options.md deleted file mode 100644 index 93667c9f5..000000000 --- a/packages/typedoc-plugin-markdown/docs/guides/options/options.md +++ /dev/null @@ -1,351 +0,0 @@ -# Plugin Options - -Some introduction to options. - -## Contents - -- [outputFileStrategy](#outputfilestrategy) -- [includeFileNumberPrefixes](#includefilenumberprefixes) -- [flattenOutputFiles](#flattenoutputfiles) -- [entryFileName](#entryfilename) -- [indexFileName](#indexfilename) -- [indexPageTitle](#indexpagetitle) -- [skipIndexPage](#skipindexpage) -- [excludeGroups](#excludegroups) -- [hidePageHeader](#hidepageheader) -- [hidePageTitle](#hidepagetitle) -- [hideBreadcrumbs](#hidebreadcrumbs) -- [hideInPageTOC](#hideinpagetoc) -- [hideHierarchy](#hidehierarchy) -- [identifiersAsCodeBlocks](#identifiersascodeblocks) -- [propertiesFormat](#propertiesformat) -- [enumMembersFormat](#enummembersformat) -- [typeDeclarationFormat](#typedeclarationformat) -- [tocFormat](#tocformat) -- [titleTemplate](#titletemplate) -- [preserveAnchorCasing](#preserveanchorcasing) - -## Output Options - -### `--outputFileStrategy` - -`"members" | "modules"` - -Determines how output files are generated. - -```json -{ - "outputFileStrategy": "members" -} -``` - -TypeDoc creates documentation according to exports. The structure will be driven by the implemented entryPoints config. . - -This options aims to provide some flexibility as to how files can be generated. - -**"members"** - -Generates an individual file for each exported member. This is the standard behaviour of the HTML theme and the plugin default. - -![outputFileStrategy members folders](../images/options/outputFileStrategy-members.png) - -**"modules"** - -Generates a single file for every Module or Namespace where all members are hoisted to a single module file. This creates a flat navigation structure and reduces the amount of files generated. - -![outputFileStrategy modules folders](../images/options/outputFileStrategy-modules.png) - ---- - -### `--includeFileNumberPrefixes` - -**`boolean`** - -Prefixes generated files and folders with number prefixes. - -```json -{ - "includeFileNumberPrefixes": "false" -} -``` - -This makes files and folders appear in the file system in the same order as they are sorted. This is useful where auto sidebar generation may be required. - -![includeFileNumberPrefixes folders](../images/options/includeFileNumberPrefixes.png) - -## flattenOutputFiles - -**`boolean`** - -Flatten output files without folders. - -```json -{ - "flattenOutputFiles": "false" -} -``` - -This creates a flat folder structure without any folders - a required format for some Wikis. - -![flattenOutputFiles folders](../images/options/flattenOutputFiles.png) - -## entryFileName - -**`string`** - -The file name of the entry page. - -```json -{ - "entryFileName": "README.md" -} -``` - -`README.md` is recognised when browsing folders on repos and Wikis. `index.md` might be better if published as a web site. - -Note the content of this file is either the API entry / index page, or the project readme (dependant on if a readme file is resolved or not). - -a. If a readme file is resolved then two root files are generated: - -├── {entryFileName} - (the project readme file) -├── API.md - (API index page) - -b. If a readme file is NOT resolved, then the index page becomes the entryFileName page. - -├── {entryFileName} - (API index page) - -## indexFileName - -**`string`** - -The file name the seperate index page. - -```json -{ - "indexFileName": "API.md" -} -``` - -This page either contains the module index or exported symbols depending on the given `entryPoints`. - -This page may not be required (if navigation is present for example) and can be skipped. See `skipIndexPage`. - -This option is ignored if `readme=none` or `skipIndexPage=true`. - -## indexPageTitle - -**`string`** - -The title of API index page. - -```json -{ - "indexPageTitle": "API Reference" -} -``` - -## skipIndexPage - -**`boolean`** - -Skips generation of a seperate API index page. - -```json -{ - "skipIndexPage": "false" -} -``` - -This option skips the generation of the index page if it is not required. - -Please note this option will be ignored if a single entryPoint is defined as it will contain exported symbols. - -## excludeGroups - -**`boolean`** - -Excludes grouping by reflection kind so all members are rendered and sorted at the same level. - -```json -{ - "excludeGroups": "false" -} -``` - -By default members are grouped by kind (eg Classes, Functions etc). - -This creates a flat structure where all members are displayed at the same level. - -**With groups** - -```markdown -# SomeModule - -## Classes - -### ClassA - -## Functions - -### FunctionA -``` - -**Without groups** - -```markdown -# SomeModule - -## ClassA - -## FunctionA -``` - -## hidePageHeader - -**`boolean`** - -Do not print page header. - -```json -{ - "hidePageHeader": "false" -} -``` - -## hidePageTitle - -**`boolean`** - -Do not print page title. - -```json -{ - "hidePageTitle": "false" -} -``` - -## hideBreadcrumbs - -**`boolean`** - -Do not print breadcrumbs. - -```json -{ - "hideBreadcrumbs": "false" -} -``` - -## hideInPageTOC - -**`boolean`** - -Do not render in-page TOC/Index items. - -```json -{ - "hideInPageTOC": "false" -} -``` - -## hideHierarchy - -**`boolean`** - -Do not print reflection hierarchy. - -```json -{ - "hideHierarchy": "false" -} -``` - -## identifiersAsCodeBlocks - -**`boolean`** - -Format signature and declaration identifiers in code blocks. - -```json -{ - "identifiersAsCodeBlocks": "false" -} -``` - -Note if `true` references will not be linked. - -## propertiesFormat - -**`"list" | "table"`** - -Specify the render style of properties groups for interfaces and classes. - -```json -{ - "propertiesFormat": "list" -} -``` - -## enumMembersFormat - -**`"list" | "table"`** - -Specify the render style of Enum members. - -```json -{ - "enumMembersFormat": "list" -} -``` - -## typeDeclarationFormat - -**`"list" | "table"`** - -Specify the render style for type declaration members. - -```json -{ - "typeDeclarationFormat": "list" -} -``` - -## tocFormat - -**`"list" | "table"`** - -Render TOC either as a simple list or a table with a description. - -```json -{ - "tocFormat": "list" -} -``` - -## titleTemplate - -**`string`** - -Specify a template for displaying page titles. - -```json -{ - "titleTemplate": "{kind}: {name}" -} -``` - -Supports {kind} and {name} placeholders. - - titleTemplate: "{kind}: {name}" - -## preserveAnchorCasing - -**`boolean`** - -Preserve anchor casing when generating links. - -```json -{ - "preserveAnchorCasing": "false" -} -``` diff --git a/packages/typedoc-plugin-markdown/docs/guides/options/remark.md b/packages/typedoc-plugin-markdown/docs/guides/options/remark.md deleted file mode 100644 index c8465fc36..000000000 --- a/packages/typedoc-plugin-markdown/docs/guides/options/remark.md +++ /dev/null @@ -1,30 +0,0 @@ -# Remark Options - -## Contents - -* [remarkPlugins](#remarkplugins) -* [remarkSettings](#remarksettings) - -## remarkPlugins - -**`any[]`** - -Remark Plugins. - -```json -{ - remarkPlugins: "" -} -``` - -## remarkSettings - -**`any[]`** - -Remark Settings. - -```json -{ - remarkSettings: "" -} -``` diff --git a/packages/typedoc-plugin-markdown/docs/guides/options/ui.md b/packages/typedoc-plugin-markdown/docs/guides/options/ui.md deleted file mode 100644 index fb389159d..000000000 --- a/packages/typedoc-plugin-markdown/docs/guides/options/ui.md +++ /dev/null @@ -1,207 +0,0 @@ -# UI Options - -## Contents - -* [indexPageTitle](#indexpagetitle) -* [excludeGroups](#excludegroups) -* [hidePageHeader](#hidepageheader) -* [hidePageTitle](#hidepagetitle) -* [hideBreadcrumbs](#hidebreadcrumbs) -* [hideInPageTOC](#hideinpagetoc) -* [hideHierarchy](#hidehierarchy) -* [identifiersAsCodeBlocks](#identifiersascodeblocks) -* [propertiesFormat](#propertiesformat) -* [enumMembersFormat](#enummembersformat) -* [typeDeclarationFormat](#typedeclarationformat) -* [tocFormat](#tocformat) -* [titleTemplate](#titletemplate) - -## indexPageTitle - -**`string`** - -The title of API index page. - -```json -{ - indexPageTitle: "API Reference" -} -``` - -## excludeGroups - -**`boolean`** - -Excludes grouping by reflection kind so all members are rendered and sorted at the same level. - -```json -{ - excludeGroups: "false" -} -``` - -By default members are grouped by kind (eg Classes, Functions etc). - -This creates a flat structure where all members are displayed at the same level. - -**With groups** - -```markdown -# SomeModule - -## Classes - -### ClassA - -## Functions - -### FunctionA -``` - -**Without groups** - -```markdown -# SomeModule - -## ClassA - -## FunctionA -``` - -## hidePageHeader - -**`boolean`** - -Do not print page header. - -```json -{ - hidePageHeader: "false" -} -``` - -## hidePageTitle - -**`boolean`** - -Do not print page title. - -```json -{ - hidePageTitle: "false" -} -``` - -## hideBreadcrumbs - -**`boolean`** - -Do not print breadcrumbs. - -```json -{ - hideBreadcrumbs: "false" -} -``` - -## hideInPageTOC - -**`boolean`** - -Do not render in-page TOC/Index items. - -```json -{ - hideInPageTOC: "false" -} -``` - -## hideHierarchy - -**`boolean`** - -Do not print reflection hierarchy. - -```json -{ - hideHierarchy: "false" -} -``` - -## identifiersAsCodeBlocks - -**`boolean`** - -Format signature and declaration identifiers in code blocks. - -```json -{ - identifiersAsCodeBlocks: "false" -} -``` - -Note if `true` references will not be linked. - -## propertiesFormat - -**`"list" | "table"`** - -Specify the render style of properties groups for interfaces and classes. - -```json -{ - propertiesFormat: "list" -} -``` - -## enumMembersFormat - -**`"list" | "table"`** - -Specify the render style of Enum members. - -```json -{ - enumMembersFormat: "list" -} -``` - -## typeDeclarationFormat - -**`"list" | "table"`** - -Specify the render style for type declaration members. - -```json -{ - typeDeclarationFormat: "list" -} -``` - -## tocFormat - -**`"list" | "table"`** - -Render TOC either as a simple list or a table with a description. - -```json -{ - tocFormat: "list" -} -``` - -## titleTemplate - -**`string`** - -Specify a template for displaying page titles. - -```json -{ - titleTemplate: "{kind}: {name}" -} -``` - -Supports {kind} and {name} placeholders. - - titleTemplate: "{kind}: {name}" diff --git a/packages/typedoc-plugin-markdown/docs/guides/options/utility.md b/packages/typedoc-plugin-markdown/docs/guides/options/utility.md deleted file mode 100644 index 4310c8e7c..000000000 --- a/packages/typedoc-plugin-markdown/docs/guides/options/utility.md +++ /dev/null @@ -1,56 +0,0 @@ -# Utility Options - -## Contents - -* [remarkPlugins](#remarkplugins) -* [preserveAnchorCasing](#preserveanchorcasing) -* [frontmatterVars](#frontmattervars) -* [frontmatterDocTags](#frontmatterdoctags) - -## remarkPlugins - -**`any[]`** - -Remark Plugins. - -```json -{ - remarkPlugins: "" -} -``` - -## preserveAnchorCasing - -**`boolean`** - -Preserve anchor casing when generating links. - -```json -{ - preserveAnchorCasing: "false" -} -``` - -## frontmatterVars - -**`string`** - -Specify static variables to be added to all frontmatter. - -```json -{ - frontmatterVars: "[object Object]" -} -``` - -## frontmatterDocTags - -**`any[]`** - -Specify which file comment tags should be added to frontmatter. - -```json -{ - frontmatterDocTags: "" -} -``` diff --git a/packages/typedoc-plugin-markdown/scripts/docs/docs.mjs b/packages/typedoc-plugin-markdown/scripts/docs/docs.mjs index 9cd01e0a8..83435d065 100644 --- a/packages/typedoc-plugin-markdown/scripts/docs/docs.mjs +++ b/packages/typedoc-plugin-markdown/scripts/docs/docs.mjs @@ -12,18 +12,17 @@ async function readmePage() { const file = await read('./README.md'); const vfile = await remark() .use(remarkGfm) - .use(remarkToc, { heading: 'Contents', maxDepth: 2 }) .use(readmeOptions) + .use(remarkToc, { heading: 'Contents', maxDepth: 2 }) .process(file); writeSync(vfile); } async function optionsPage() { const file = await read('./docs/guides/options.md'); + const processor = await remark().use(remarkGfm).use(guideOptions); const vfile = await remark() - .use(remarkGfm) .use(remarkToc, { heading: 'Contents', maxDepth: 3 }) - .use(guideOptions) - .process(file); + .processSync(processor.processSync(file)); writeSync(vfile); } diff --git a/packages/typedoc-plugin-markdown/scripts/docs/remark/guide-options.mjs b/packages/typedoc-plugin-markdown/scripts/docs/remark/guide-options.mjs index 5f34ec72d..db32d49a9 100644 --- a/packages/typedoc-plugin-markdown/scripts/docs/remark/guide-options.mjs +++ b/packages/typedoc-plugin-markdown/scripts/docs/remark/guide-options.mjs @@ -1,20 +1,17 @@ import { fromMarkdown } from 'mdast-util-from-markdown'; import { headingRange } from 'mdast-util-heading-range'; import { ParameterType } from 'typedoc'; -import { TITLE_MAP, groupedConfig } from '../../utils/options.utils.mjs'; +import { + INTRO_MAP, + TITLE_MAP, + groupedConfig, +} from '../../utils/options.utils.mjs'; /** @type {import('unified').Plugin<[], import('mdast').Root>} */ export default function guideOptions() { return (tree) => { - parseOptions( - tree, - - 'fileOutput', - ); - - parseOptions(tree, 'remark'); - - parseOptions(tree, 'frontmatter'); + parseOptions(tree, 'fileOutput'); + parseOptions(tree, 'ui'); }; } @@ -26,20 +23,25 @@ function parseOptions(tree, key) { } function getMarkdown(key) { - const md = []; + const md = [INTRO_MAP[key]]; + md.push('***'); + groupedConfig[key].forEach((config, i) => { md.push(`### \`--${config.name}\``); - md.push(`\`${getType(config)}\``); md.push(`> ${config.help}`); + md.push('#### Type'); + md.push(`\`${getType(config)}\``); + md.push('#### Default'); md.push(` \`\`\`json { - ${config.name}: "${config.defaultValue}" + "${config.name}": "${config.defaultValue}" } \`\`\` `); - + md.push('#### Usage'); md.push(config.comments); + md.push('[↑ Top](#options-guide)'); md.push('***'); }); diff --git a/packages/typedoc-plugin-markdown/scripts/docs/remark/readme-options.mjs b/packages/typedoc-plugin-markdown/scripts/docs/remark/readme-options.mjs index aebe78e81..e2057f4cb 100644 --- a/packages/typedoc-plugin-markdown/scripts/docs/remark/readme-options.mjs +++ b/packages/typedoc-plugin-markdown/scripts/docs/remark/readme-options.mjs @@ -1,21 +1,20 @@ import { fromMarkdown } from 'mdast-util-from-markdown'; import { headingRange } from 'mdast-util-heading-range'; -import { TITLE_MAP, groupedConfig } from '../../utils/options.utils.mjs'; +import { + INTRO_MAP, + TITLE_MAP, + groupedConfig, +} from '../../utils/options.utils.mjs'; /** @type {import('unified').Plugin<[], import('mdast').Root>} */ export default function readmeOptions() { return (tree) => { - parseOptions( - tree, - 'Options that define how output files are generated.', - 'fileOutput', - ); - parseOptions(tree, 'Remark options.', 'remark'); - parseOptions(tree, 'Frontmatter options.', 'frontmatter'); + parseOptions(tree, 'fileOutput'); + parseOptions(tree, 'ui'); }; } -function parseOptions(tree, intro, key) { +function parseOptions(tree, key) { const heading = TITLE_MAP[key]; headingRange(tree, heading, (start, nodes, end) => { return [start, fromMarkdown(getMarkdown(key)), end]; @@ -23,7 +22,13 @@ function parseOptions(tree, intro, key) { } function getMarkdown(key) { - return groupedConfig[key] - .map((config) => `- [\`--${config.name}\`]()`) + const intro = INTRO_MAP[key]; + const list = groupedConfig[key] + .map((config) => { + return `- [\`--${ + config.name + }\`](./docs/guides/options.md#--${config.name.toLowerCase()})`; + }) .join('\n'); + return [intro, list].join('\n\n'); } diff --git a/packages/typedoc-plugin-markdown/scripts/utils/options.utils.mjs b/packages/typedoc-plugin-markdown/scripts/utils/options.utils.mjs index 17808f2c4..5599c7c64 100644 --- a/packages/typedoc-plugin-markdown/scripts/utils/options.utils.mjs +++ b/packages/typedoc-plugin-markdown/scripts/utils/options.utils.mjs @@ -42,7 +42,11 @@ export const parsedConfig = Object.values(optionsConfig).map((value, i) => { export const groupedConfig = parsedConfig.groupBy('category'); export const TITLE_MAP = { - fileOutput: 'Output Options', - remark: 'Remark Options', - frontmatter: 'Frontmatter Options', + fileOutput: 'File Options', + ui: 'UI Options', +}; + +export const INTRO_MAP = { + fileOutput: 'Options that define how output files are generated.', + ui: 'UI Options', }; diff --git a/packages/typedoc-plugin-markdown/src/plugin/options/config.ts b/packages/typedoc-plugin-markdown/src/plugin/options/config.ts index c0e95fd7d..8d9a92630 100644 --- a/packages/typedoc-plugin-markdown/src/plugin/options/config.ts +++ b/packages/typedoc-plugin-markdown/src/plugin/options/config.ts @@ -150,7 +150,7 @@ export const skipIndexPage: DeclarationOption = { * ## FunctionA * ``` * - * @category fileOutput + * @category ui */ export const excludeGroups: DeclarationOption = { name: 'excludeGroups', @@ -160,7 +160,7 @@ export const excludeGroups: DeclarationOption = { }; /** - * @category fileOutput + * @category ui */ export const hidePageHeader: DeclarationOption = { name: 'hidePageHeader', @@ -170,7 +170,7 @@ export const hidePageHeader: DeclarationOption = { }; /** - * @category fileOutput + * @category ui */ export const hidePageTitle: DeclarationOption = { name: 'hidePageTitle', @@ -180,7 +180,7 @@ export const hidePageTitle: DeclarationOption = { }; /** - * @category fileOutput + * @category ui */ export const hideBreadcrumbs: DeclarationOption = { name: 'hideBreadcrumbs', @@ -190,7 +190,7 @@ export const hideBreadcrumbs: DeclarationOption = { }; /** - * @category fileOutput + * @category ui */ export const hideInPageTOC: DeclarationOption = { name: 'hideInPageTOC', @@ -200,7 +200,7 @@ export const hideInPageTOC: DeclarationOption = { }; /** - * @category fileOutput + * @category ui */ export const hideHierarchy: DeclarationOption = { name: 'hideHierarchy', @@ -212,7 +212,7 @@ export const hideHierarchy: DeclarationOption = { /** * Note if `true` references will not be linked. * - * @category fileOutput + * @category ui */ export const identifiersAsCodeBlocks: DeclarationOption = { name: 'identifiersAsCodeBlocks', @@ -222,7 +222,7 @@ export const identifiersAsCodeBlocks: DeclarationOption = { }; /** - * @category fileOutput + * @category ui */ export const propertiesFormat: DeclarationOption = { name: 'propertiesFormat', @@ -233,7 +233,7 @@ export const propertiesFormat: DeclarationOption = { }; /** - * @category fileOutput + * @category ui */ export const enumMembersFormat: DeclarationOption = { name: 'enumMembersFormat', @@ -244,7 +244,7 @@ export const enumMembersFormat: DeclarationOption = { }; /** - * @category fileOutput + * @category ui */ export const typeDeclarationFormat: DeclarationOption = { name: 'typeDeclarationFormat', @@ -255,7 +255,7 @@ export const typeDeclarationFormat: DeclarationOption = { }; /** - * @category fileOutput + * @category ui */ export const tocFormat: DeclarationOption = { name: 'tocFormat', @@ -271,7 +271,7 @@ export const tocFormat: DeclarationOption = { * ``` * titleTemplate: "{kind}: {name}" * ``` - * @category fileOutput + * @category ui */ export const titleTemplate: DeclarationOption = { name: 'titleTemplate',