typedoc-plugin-markdown

typedoc-plugin-markdown

Version 4.6.3
Published 2 days ago
326 kB
No dependencies
MIT license

Install

npm i typedoc-plugin-markdown

yarn add typedoc-plugin-markdown

pnpm add typedoc-plugin-markdown

Overview

A plugin for TypeDoc that enables TypeScript API documentation to be generated in Markdown.

Index

Functions

load()

Interfaces

MarkdownApplication
- renderer
MarkdownRendererHooks
NavigationItem
PluginOptions

Functions

function load

load: (app: Application) => void;

The function that is called by TypeDoc to bootstrap the plugin.
Remarks
The load function exposes additional TypeDoc options and make some adjustments.
This method is not intended to be consumed in any other context that via the plugin option.
The module also exports anything that is available publicly.

Classes

class MarkdownPageEvent

class MarkdownPageEvent<out Model extends RouterTarget = RouterTarget> {}

An event emitted before and after the markdown of a page is rendered.

constructor

constructor(model: RouterTarget);

property BEGIN

static readonly BEGIN: string;

Triggered before a document will be rendered.

property contents

contents: string;

The final html content of this page.
Should be rendered by layout templates and can be modified by plugins.

property END

static readonly END: string;

Triggered after a document has been rendered, just before it is written to disc.

property filename

filename: string;

The filename the page will be written to.

property frontmatter

frontmatter?: Record<string, any>;

The frontmatter of this page represented as a key value object. This property can be utilised by other plugins.

property model

readonly model: RouterTarget;

The model that should be rendered on this page.

property pageHeadings

pageHeadings: PageHeading[];

property pageKind

pageKind: PageKind;

The type of page this is.

property pageSections

pageSections: { title: string; headings: PageHeading[] }[];

property preWriteAsyncJobs

preWriteAsyncJobs: ((page: MarkdownPageEvent) => Promise<void>)[];

property project

project: ProjectReflection;

The project the renderer is currently processing.

property url

url: string;

The url this page will be located at.

method isReflectionEvent

isReflectionEvent: () => this is MarkdownPageEvent<Reflection>;

method startNewSection

startNewSection: () => void;

class MarkdownRendererEvent

class MarkdownRendererEvent {}

An event emitted at the beginning and end of the rendering process.

constructor

constructor(
    outputDirectory: string,
    project: ProjectReflection,
    pages: PageDefinition[]
);

property BEGIN

static readonly BEGIN: string;

Triggered before the renderer starts rendering a project.

property END

static readonly END: string;

Triggered after the renderer has written all documents.

navigation?: NavigationItem[];

The navigation structure of the project that can be utilised by plugins.

property outputDirectory

readonly outputDirectory: string;

The path of the directory the documentation should be written to.

property pages

pages: PageDefinition[];

A list of all pages that will be generated.

property project

readonly project: ProjectReflection;

The project the renderer is currently processing.

class MarkdownTheme

class MarkdownTheme extends Theme {}

The main theme class for the plugin.
The class controls how TypeDoc models are mapped to files and templates and extends TypeDoc's base Theme class.
You would typically only be interested in overriding the the theme's render context instance.
The API follows the implementation of [TypeDoc's custom theming](https://github.com/TypeStrong/typedoc/blob/master/internal-docs/custom-themes.md) with some minor adjustments.

constructor

constructor(renderer: Renderer);

property documentTemplate

documentTemplate: (page: MarkdownPageEvent<DocumentReflection>) => string;

property hierarchyTemplate

hierarchyTemplate: (page: MarkdownPageEvent<ProjectReflection>) => string;

property indexTemplate

indexTemplate: (page: MarkdownPageEvent<ProjectReflection>) => string;

property reflectionTemplate

reflectionTemplate: (page: MarkdownPageEvent<DeclarationReflection>) => string;

property router

router: Router;

method getNavigation

getNavigation: (
    project: ProjectReflection
) => import('../public-api.js').NavigationItem[];

method getRenderContext

getRenderContext: (page: MarkdownPageEvent<Reflection>) => MarkdownThemeContext;

method render

render: (page: MarkdownPageEvent) => string;

Renders a template and page model to a string.

class MarkdownThemeContext

class MarkdownThemeContext {}

The theme context class that is provided as context on the rendering of every page.
It is heavily influenced by the equivalent [DefaultThemeRenderContext](https://typedoc.org/api/classes/DefaultThemeRenderContext.html) from the default theme.
This class can be used to customize the theme output by extending the class and overriding the templates, partials and helpers.
Properties
Properties are passed into the constructor and are used to provide context to the theme.
Methods
General context aware helper methods not bound to any specific models that can be used by the theme resources.
Resources
Theme resources are the main building blocks for the theme context. They are split into three namespaces: templates, partials and helpers.

constructor

constructor(
    theme: MarkdownTheme,
    page: MarkdownPageEvent<Reflection>,
    options: Options
);

property helpers

helpers: {
    getAngleBracket: (bracket: '>' | '<') => string;
    getCommentParts: (model: import('typedoc').CommentDisplayPart[]) => string;
    getDeclarationType: (model: any) => import('typedoc').SomeType | undefined;
    getDescriptionForComment: (comment: any) => string | null;
    getFlattenedDeclarations: (
        model: import('typedoc').DeclarationReflection[],
        options?: { includeSignatures: boolean } | undefined
    ) => import('typedoc').DeclarationReflection[];
    getHierarchyType: (
        model: any,
        options?: { isTarget: boolean } | undefined
    ) => string;
    getKeyword: (model: any) => string;
    getModifier: (model: any) => string | null;
    getParameterDefaultValue: (model: any) => string;
    getProjectName: (
        stringWithPlaceholders: string,
        page: MarkdownPageEvent<Reflection>,
        includeVersion?: boolean
    ) => string;
    getPropertyDefaultValue: (model: any) => string | null;
    getReflectionFlags: (reflectionFlags: any) => string;
    getReturnType: (model?: import('typedoc').SomeType | undefined) => string;
    hasUsefulTypeDetails: (type: any) => boolean;
    isGroupKind: (
        model:
            | import('typedoc').DeclarationReflection
            | import('typedoc').SignatureReflection
    ) => boolean;
    useTableFormat: (
        key:
            | 'properties'
            | 'parameters'
            | 'enums'
            | 'typeDeclarations'
            | 'propertyMembers',
        reflectionKind?: import('typedoc').ReflectionKind | undefined
    ) => boolean;
};

The helpers namespace holds the helpers for the theme and are smaller utility functions that return snippets or text or other data transformations.
Please note that partials:
- Take a model param (that references a specific TypeDoc model) and an options param if required. - Can reference other helpers but should not reference partials. - Can return strings or other models.
Resources

property hook

hook: EventHooks<MarkdownRendererHooks, string>;

Hook into the TypeDoc rendering system.

property options

readonly options: Options;

The options provided to the application.

property page

readonly page: MarkdownPageEvent<Reflection>;

The current page event.

property partials

partials: {
    comment: (
        model: any,
        options?: {
            headingLevel?: number | undefined;
            showSummary?: boolean | undefined;
            showTags?: boolean | undefined;
            showReturns?: boolean | undefined;
            isTableColumn?: boolean | undefined;
        }
    ) => string;
    body: (model: any, options: { headingLevel: number }) => string;
    categories: (
        models: import('typedoc').ReflectionCategory[],
        options: { headingLevel: number }
    ) => string;
    groups: (
        model: any,
        options: { headingLevel: number; kind: import('typedoc').ReflectionKind }
    ) => string;
    members: (
        model: import('typedoc').DeclarationReflection[],
        options: { headingLevel: number; groupTitle?: string | undefined }
    ) => string;
    accessor: (model: any, options: { headingLevel: number }) => string;
    constructor: (model: any, options: { headingLevel: number }) => string;
    memberContainer: (
        model: any,
        options: {
            headingLevel: number;
            nested?: boolean | undefined;
            groupTitle?: string | undefined;
        }
    ) => string;
    declaration: (
        model: any,
        options?: { headingLevel: number; nested?: boolean | undefined }
    ) => string;
    declarationTitle: (model: any) => string;
    documents: (
        model:
            | import('typedoc').ProjectReflection
            | import('typedoc').DeclarationReflection
            | import('typedoc').ContainerReflection,
        options: { headingLevel: number }
    ) => string;
    enumMembersTable: (
        model: import('typedoc').DeclarationReflection[]
    ) => string;
    groupIndex: (
        group:
            | import('typedoc').ReflectionCategory
            | import('typedoc').ReflectionGroup
    ) => string;
    hierarchy: (model: any, options: { headingLevel: number }) => string;
    indexSignature: (
        model: any,
        options?: { headingLevel: number } | undefined
    ) => string;
    inheritance: (
        model:
            | import('typedoc').DeclarationReflection
            | import('typedoc').SignatureReflection,
        options: { headingLevel: number }
    ) => string;
    memberTitle: (model: any) => string;
    memberWithGroups: (model: any, options: { headingLevel: number }) => string;
    parametersList: (
        model: import('typedoc').ParameterReflection[],
        options: { headingLevel: number }
    ) => string;
    parametersTable: (model: import('typedoc').ParameterReflection[]) => string;
    propertiesTable: (
        model: import('typedoc').DeclarationReflection[],
        options?:
            | { isEventProps: boolean; kind: import('typedoc').ReflectionKind }
            | undefined
    ) => string;
    referenceMember: (model: any) => string;
    signature: (
        model: any,
        options: {
            headingLevel: number;
            nested?: boolean | undefined;
            accessor?: string | undefined;
            multipleSignatures?: boolean | undefined;
            hideTitle?: boolean | undefined;
        }
    ) => string;
    signatureParameters: (
        model: import('typedoc').ParameterReflection[],
        options?: { forceExpandParameters?: boolean | undefined } | undefined
    ) => string;
    signatureReturns: (model: any, options: { headingLevel: number }) => string;
    signatureTitle: (
        model: any,
        options?:
            | {
                  accessor?: string | undefined;
                  includeType?: boolean | undefined;
              }
            | undefined
    ) => string;
    signatures: (
        model: any,
        options: { headingLevel: number; nested?: boolean | undefined }
    ) => string;
    sources: (
        model:
            | import('typedoc').DeclarationReflection
            | import('typedoc').SignatureReflection,
        options?: { hideLabel: boolean } | undefined
    ) => string;
    member: (
        model: any,
        options: { headingLevel: number; nested?: boolean | undefined }
    ) => string;
    typeAndParent: (
        model: import('typedoc').ReferenceType | import('typedoc').ArrayType
    ) => string;
    typeArguments: (
        model: import('typedoc').SomeType[],
        options?: { forceCollapse?: boolean | undefined } | undefined
    ) => string;
    typeDeclaration: (
        model: any,
        options: { headingLevel: number; allowSource?: boolean | undefined }
    ) => string;
    typeDeclarationContainer: (
        model: any,
        typeDeclaration: any,
        opts: { headingLevel: number; nested?: boolean | undefined }
    ) => string;
    typeDeclarationList: (
        model: import('typedoc').DeclarationReflection[],
        options: { headingLevel: number }
    ) => string;
    typeDeclarationTable: (
        model: import('typedoc').DeclarationReflection[],
        options: { kind?: import('typedoc').ReflectionKind | undefined }
    ) => string;
    typeDeclarationUnionContainer: (
        model: any,
        options: { headingLevel: number }
    ) => string;
    typeParametersList: (
        model: import('typedoc').TypeParameterReflection[],
        options: { headingLevel: number }
    ) => string;
    typeParametersTable: (
        model: import('typedoc').TypeParameterReflection[]
    ) => string;
    breadcrumbs: () => string;
    footer: () => string;
    header: () => string;
    packagesIndex: (model: any) => string;
    pageTitle: () => string;
    arrayType: (model: any) => string;
    conditionalType: (model: any) => string;
    indexAccessType: (model: any) => string;
    inferredType: (model: any) => string;
    intersectionType: (model: any) => string;
    intrinsicType: (model: any) => string;
    literalType: (model: any) => string;
    namedTupleType: (model: any) => string;
    optionalType: (
        model: any,
        options?: { forceCollapse?: boolean | undefined } | undefined
    ) => string;
    queryType: (model: any) => string;
    referenceType: (model: any) => string;
    declarationType: (
        model: any,
        options?: { forceCollapse?: boolean | undefined } | undefined
    ) => string;
    functionType: (
        model: import('typedoc').SignatureReflection[],
        options?:
            | {
                  forceParameterType?: boolean | undefined;
                  typeSeparator?: string | undefined;
              }
            | undefined
    ) => string;
    reflectionType: (
        model: any,
        options?: { forceCollapse?: boolean | undefined } | undefined
    ) => string;
    someType: (
        model?: import('typedoc').SomeType | undefined,
        options?: { forceCollapse?: boolean | undefined } | undefined
    ) => string;
    tupleType: (model: any) => string;
    typeOperatorType: (model: any) => string;
    unionType: (model: any) => string;
    unknownType: (model: any) => string;
};

The partials namespace holds the partials for the theme and are used by templates to map speficic models to page output.
Please note that partials::
- Take a model param (that references a specific TypeDoc model) and an options param if required. - Can call other partials and helpers. - Must return a string.
Partials are categorised by their use:
- Page Partials: Partials that render core page elements such as header and breadcrumbs. - Container Partials: Partials that are used to render reflection groups and categories. - Member Partials: Partials that render specific parts of reflections. - Comment Partials: Partials that render comments. - Type Partials: Partials that render specific TypeDoc model types.
Resources

property router

router: Router;

The markdown router instance.

property templates

templates: {
    document: (
        page: MarkdownPageEvent<import('typedoc').DocumentReflection>
    ) => string;
    hierarchy: (
        page: MarkdownPageEvent<import('typedoc').ProjectReflection>
    ) => string;
    index: (
        page: MarkdownPageEvent<import('typedoc').ProjectReflection>
    ) => string;
    reflection: (
        page: MarkdownPageEvent<import('typedoc').DeclarationReflection>
    ) => string;
};

Then templates namespace holds the main templates for the theme and are mapped to single pages and configured in the MarkdownTheme.
All templates return a string that is passed back to the renderer. Internally templates call partials and helpers.
Resources

property theme

readonly theme: MarkdownTheme;

The theme instance.

method getPackageMetaData

getPackageMetaData: (packageName: string) => PackageMetaData | undefined;

Returns the package meta data for a given package name when entrypointStrategy is set to packages.
Parameter packageName
The package name as per name field from package.json.

method getPackagesCount

getPackagesCount: () => number;

Return the number of packages in the project.

method relativeURL

relativeURL: (url: string) => string;

Returns a url relative to the current page.

method urlTo

urlTo: (reflection: Reflection) => string;

Returns the relative url of a given reflection.

class MemberRouter

class MemberRouter extends MarkdownRouter {}

method buildChildPages

buildChildPages: (reflection: Reflection, outPages: PageDefinition[]) => void;

method getIdealBaseName

getIdealBaseName: (reflection: Reflection) => string;

class ModuleRouter

class ModuleRouter extends MarkdownRouter {}

method buildChildPages

buildChildPages: (reflection: Reflection, outPages: PageDefinition[]) => void;

method getIdealBaseName

getIdealBaseName: (reflection: Reflection) => string;

Interfaces

interface MarkdownApplication

interface MarkdownApplication extends Application {}

The MarkdownApplication extends TypeDoc's instance with a custom renderer.

property renderer

renderer: MarkdownRenderer & Renderer;

interface MarkdownRendererHooks

interface MarkdownRendererHooks {}

Describes the hooks available to inject output in the markdown theme.

property ['content.begin']

['content.begin']: [MarkdownThemeContext];

Applied before the main markdown content is rendered.
Hooks

property ['index.page.begin']

['index.page.begin']: [MarkdownThemeContext];

Applied at the start of the markdown output on the index page.
Hooks

property ['index.page.end']

['index.page.end']: [MarkdownThemeContext];

Applied at the end of the markdown output on the index page.
Hooks

property ['page.begin']

['page.begin']: [MarkdownThemeContext];

Applied at the start of the markdown output.
Hooks

property ['page.end']

['page.end']: [MarkdownThemeContext];

Applied at the end of the markdown output.
Hooks

interface NavigationItem

interface NavigationItem {}

The model used to define the navigation structure.

property children

children?: NavigationItem[];

property isDeprecated

isDeprecated?: boolean;

property kind

kind?: ReflectionKind;

property path

path?: string | null;

property title

title: string;

interface PluginOptions

interface PluginOptions {}

Describes the options declared by the plugin.

property anchorPrefix

anchorPrefix?: string;

Custom anchor prefix to add to anchor links.

property blockTagsPreserveOrder

blockTagsPreserveOrder?: string[];

Specifies comment block tags that should preserve their position.

property classPropertiesFormat

classPropertiesFormat?: 'list' | 'table' | 'htmlTable';

Sets the format of property groups for classes.

property entryFileName

entryFileName?: string;

The file name of the entry page.

property entryModule

entryModule?: string;

The name of a module that should act as the root page for the documentation.

property enumMembersFormat

enumMembersFormat?: 'list' | 'table' | 'htmlTable';

Sets the format of enumeration members.

property excludeGroups

excludeGroups?: boolean;

Deprecated
This option has been renamed hideGroupHeadings to better reflect its purpose.

property excludeScopesInPaths

excludeScopesInPaths?: boolean;

Exclude writing @ scope directories in paths.

property expandObjects

expandObjects?: boolean;

Expand objects inside declarations.

property expandParameters

expandParameters?: boolean;

Expand parameters in signature parentheses to display type information.

property fileExtension

fileExtension?: string;

Specify the file extension for generated output files.

property flattenOutputFiles

flattenOutputFiles?: boolean;

Flatten output files to a single directory.

property formatWithPrettier

formatWithPrettier?: boolean;

Apply additional output formatting with Prettier.

property hideBreadcrumbs

hideBreadcrumbs?: boolean;

Do not print breadcrumbs.

property hideGroupHeadings

hideGroupHeadings?: boolean;

Excludes grouping by kind so all members are rendered at the same level.

property hidePageHeader

hidePageHeader?: boolean;

Do not print page header.

property hidePageTitle

hidePageTitle?: boolean;

Do not print page title.

property indexFormat

indexFormat?: 'list' | 'table' | 'htmlTable';

Sets the format of index items.

property interfacePropertiesFormat

interfacePropertiesFormat?: 'list' | 'table' | 'htmlTable';

Sets the format of property groups for interfaces.

property membersWithOwnFile

membersWithOwnFile?: (
    | 'Enum'
    | 'Variable'
    | 'Function'
    | 'Class'
    | 'Interface'
    | 'TypeAlias'
)[];

Determines which members are exported to their own file.

property mergeReadme

mergeReadme?: boolean;

Appends the documentation index page to the readme page.

property modulesFileName

modulesFileName?: string;

The file name of the separate modules / index page.

property navigationModel

navigationModel?: {
    excludeGroups?: boolean;
    excludeCategories?: boolean;
    excludeFolders?: boolean;
};

Deprecated
This option has been deprecated in favour of TypeDoc navigation option.

property outputFileStrategy

outputFileStrategy?: 'members' | 'modules';

Deprecated
Deprecated in favour of --router.

property pageTitleTemplates

pageTitleTemplates?: {
    index: string | ((name: { projectName: string; version: string }) => string);
    member:
        | string
        | ((name: { name: string; kind: string; group: string }) => string);
    module: string | ((name: { name: string; kind: string }) => string);
};

Change specific text placeholders in the template.

property parametersFormat

parametersFormat?: 'list' | 'table' | 'htmlTable';

Sets the format of parameter and type parameter groups.

property preserveAnchorCasing

preserveAnchorCasing?: boolean;

Preserve anchor casing when generating link to symbols.

property prettierConfigFile

prettierConfigFile?: string;

Specify a custom Prettier configuration file location.

property propertiesFormat

propertiesFormat?: 'list' | 'table' | 'htmlTable';

Deprecated
This option has been deprecated in favour of --interfacePropertiesFormat and --classPropertiesFormat.

property propertyMembersFormat

propertyMembersFormat?: 'list' | 'table' | 'htmlTable';

Sets the format of style for property members for interfaces and classes.

property publicPath

publicPath?: string;

Specify the base path for all urls.

property sanitizeComments

sanitizeComments?: boolean;

Sanitize HTML and JSX inside JsDoc comments.

property tableColumnSettings

tableColumnSettings?: {
    hideDefaults?: boolean;
    hideInherited?: boolean;
    hideModifiers?: boolean;
    hideOverrides?: boolean;
    hideSources?: boolean;
    hideValues?: boolean;
    leftAlignHeaders?: boolean;
};

Control how table columns are configured and displayed.

property textContentMappings

textContentMappings?: {
    'header.title': string;
    'breadcrumbs.home': string;
    'title.indexPage': string;
    'title.memberPage': string;
    'title.modulePage': string;
};

Deprecated
This option has been deprecated in favour of --pageTitleTemplates.

property typeAliasPropertiesFormat

typeAliasPropertiesFormat?: 'list' | 'table' | 'htmlTable';

Sets the format of style for type alias properties.

property typeDeclarationFormat

typeDeclarationFormat?: 'list' | 'table' | 'htmlTable';

Sets the format of style for type declaration members.

property typeDeclarationVisibility

typeDeclarationVisibility?: 'compact' | 'verbose';

Set the visibility level for type declaration documentation.

property useCodeBlocks

useCodeBlocks?: boolean;

Wraps signatures and declarations in code blocks.

property useHTMLAnchors

useHTMLAnchors?: boolean;

Add HTML anchors to page headings.

property useHTMLEncodedBrackets

useHTMLEncodedBrackets?: boolean;

Use HTML encoded entities for angle brackets.

Package Files (11)

Dependencies (0)

No dependencies.

Dev Dependencies (0)

No dev dependencies.

Peer Dependencies (1)

typedoc

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/typedoc-plugin-markdown.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/typedoc-plugin-markdown)

HTML

<a href="https://www.jsdocs.io/package/typedoc-plugin-markdown"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 2 days ago.
Package analyzed in 5169 ms.
Missing or incorrect documentation? Open an issue for this package.

typedoc-plugin-markdown

Install

Overview

Index

Functions

Classes

Interfaces

Functions

function load

Remarks

Classes

class MarkdownPageEvent

constructor

property BEGIN

property contents

property END

property filename

property frontmatter

property model

property pageHeadings

property pageKind

property pageSections

property preWriteAsyncJobs

property project

property url

method isReflectionEvent

method startNewSection

class MarkdownRendererEvent

constructor

property BEGIN

property END

property navigation

property outputDirectory

property pages

property project

class MarkdownTheme

constructor

property documentTemplate

property hierarchyTemplate

property indexTemplate

property reflectionTemplate

property router

method getNavigation

method getRenderContext

method render

class MarkdownThemeContext

constructor

property helpers

property hook

property options

property page

property partials

property router

property templates

property theme

method getPackageMetaData

Parameter packageName

method getPackagesCount

method relativeURL

method urlTo

class MemberRouter

method buildChildPages

method getIdealBaseName

class ModuleRouter

method buildChildPages

method getIdealBaseName

Interfaces

interface MarkdownApplication

property renderer

interface MarkdownRendererHooks

property ['content.begin']

property ['index.page.begin']

property ['index.page.end']

property ['page.begin']

property ['page.end']

interface NavigationItem

property children

property isDeprecated

property kind

property path