typedoc-plugin-markdown

typedoc-plugin-markdown

Version 4.2.9
Published 2 days ago
343 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
MarkdownRenderer
MarkdownRendererHooks
NavigationItem
PluginOptions
UrlMapping

Functions

function load

load: (app: Application) => void;

The function that is called by TypeDoc to bootstrap the plugin.
Here we expose additional TypeDoc options and make some adjustments.
This method is not intended to be consumed in any other context that via the plugin option.
See Also
- https://typedoc.org/guides/development/#plugins.

Classes

class MarkdownPageEvent

class MarkdownPageEvent<Model = Reflection> extends Event {}

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

constructor

constructor(name: string, model: {});

property BEGIN

static readonly BEGIN: string;

Triggered before a document will be rendered.

property contents

contents?: string;

The final markdown string content of the 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 complete string filename where the file will be written..

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: {};

The model that that is being rendered on this page. Either a or .

property pageHeadings

pageHeadings: any;

property pageSections

pageSections: any;

property project

project: ProjectReflection;

The instance the renderer is currently processing.

property startNewSection

startNewSection: any;

property url

url: string;

The url string of the page.

class MarkdownRendererEvent

class MarkdownRendererEvent extends Event {}

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

constructor

constructor(name: string, outputDirectory: string, project: ProjectReflection);

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 project

readonly project: ProjectReflection;

The project the renderer is currently processing.

property urls

urls?: UrlMapping<Reflection>[];

A list of all pages that should be generated.

method createPageEvent

createPageEvent: <Model>(
    mapping: UrlMapping<Model>
) => [RenderTemplate<MarkdownPageEvent<Model>>, MarkdownPageEvent<Model>];

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.
Theme Classes

constructor

constructor(renderer: Renderer);

method getNavigation

getNavigation: (
    project: ProjectReflection
) => import('../types').NavigationItem[];

Map the models of the given project to a navigation structure.

method getRenderContext

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

Creates a new instance of the current theme context.
This method can be overridden to provide an alternative theme context.

method getUrls

getUrls: (
    project: ProjectReflection
) => import('../types').UrlMapping<Reflection>[];

Maps the models of the given project to the desired output files.

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[];
    getGroupIndexList: (
        children:
            | import('typedoc').DeclarationReflection[]
            | import('typedoc').DocumentReflection[]
    ) => string;
    getGroupIndexTable: (
        children:
            | import('typedoc').DeclarationReflection[]
            | import('typedoc').DocumentReflection[]
    ) => string;
    getGroupIndex: (
        group:
            | import('typedoc').ReflectionCategory
            | import('typedoc').ReflectionGroup
    ) => any;
    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>
    ) => string;
    getPropertyDefaultValue: (model: any) => string | null;
    getReflectionFlags: (reflectionFlags: any) => string;
    getReturnType: (model?: import('typedoc').SomeType | undefined) => string;
    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 i18n

i18n: Internationalization.TranslationProxy;

property internationalization

internationalization: Internationalization.Internationalization;

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: (
        model: import('typedoc').ReflectionCategory[],
        options: { headingLevel: number }
    ) => string;
    groups: (
        model: import('typedoc').ReflectionGroup[],
        options: { headingLevel: number; kind: import('typedoc').ReflectionKind }
    ) => string;
    members: (
        model: import('typedoc').DeclarationReflection[],
        options: { headingLevel: number }
    ) => string;
    accessor: (model: any, options: { headingLevel: number }) => string;
    constructor: (model: any, options: { headingLevel: number }) => string;
    memberContainer: (
        model: any,
        options: { headingLevel: number; nested?: boolean | 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;
    hierarchy: (model: any, options: { headingLevel: number }) => string;
    indexSignature: (model: any) => 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[]) => string;
    parametersTable: (model: import('typedoc').ParameterReflection[]) => string;
    propertiesTable: (
        model: import('typedoc').DeclarationReflection[],
        options?: { isEventProps: boolean } | undefined
    ) => string;
    referenceMember: (model: any) => string;
    reflectionIndex: (
        model:
            | import('typedoc').ProjectReflection
            | import('typedoc').DeclarationReflection,
        options: { headingLevel: number }
    ) => string;
    signature: (
        model: any,
        options: {
            headingLevel: number;
            nested?: boolean | undefined;
            accessor?: string | undefined;
            multipleSignatures?: boolean | undefined;
        }
    ) => string;
    signatureParameters: (
        model: import('typedoc').ParameterReflection[]
    ) => 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: { headingLevel: number }
    ) => string;
    member: (
        model: any,
        options: { headingLevel: number; nested?: boolean | undefined }
    ) => string;
    typeAndParent: (
        model: import('typedoc').ArrayType | import('typedoc').ReferenceType
    ) => string;
    typeArguments: (
        model: import('typedoc').SomeType[],
        options?: { forceCollapse?: boolean | undefined } | undefined
    ) => string;
    typeDeclaration: (model: any, options: { headingLevel: number }) => string;
    typeDeclarationList: (
        model: import('typedoc').DeclarationReflection[],
        options: { headingLevel: number }
    ) => string;
    typeDeclarationTable: (
        model: import('typedoc').DeclarationReflection[],
        options: { kind?: import('typedoc').ReflectionKind | undefined }
    ) => string;
    typeParametersList: (
        model: import('typedoc').TypeParameterReflection[]
    ) => 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;
    queryType: (model: any) => string;
    referenceType: (model: any) => string;
    declarationType: (model: any) => string;
    functionType: (
        model: import('typedoc').SignatureReflection[],
        options?: { forceParameterType: boolean } | undefined
    ) => string;
    reflectionType: (
        model: any,
        options?: { forceCollapse?: boolean | undefined } | undefined
    ) => string;
    someType: (model?: import('typedoc').SomeType | 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 templates

templates: {
    document: (
        page: MarkdownPageEvent<import('typedoc').DocumentReflection>
    ) => string;
    project: (
        page: MarkdownPageEvent<import('typedoc').ProjectReflection>
    ) => string;
    readme: (
        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

method getRelativeUrl

getRelativeUrl: (url: string, ignorePublicPath?: boolean) => string;

Returns the relative URL (from the current page context url).
If public path is set, it will be used as the base URL.
Parameter url
The URL to make relative.
Parameter ignorePublicPath
Whether to ignore the public path.

Interfaces

interface MarkdownApplication

interface MarkdownApplication extends Application {}

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

property renderer

renderer: MarkdownRenderer & Renderer;

interface MarkdownRenderer

interface MarkdownRenderer extends Renderer {}

The MarkdownRenderer extends TypeDoc's Renderer instance with custom hooks and async jobs.

property defineTheme

defineTheme: (
    name: string,
    theme: new (renderer: Renderer) => MarkdownTheme
) => void;

Define a new theme that can be used to render output.
Parameter name
The name of the theme.
Parameter theme
The theme class to use.

property markdownHooks

markdownHooks: EventHooks<MarkdownRendererHooks, string>;

property postRenderAsyncJobs

postRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise<void>>;

A list of async jobs which must be completed after rendering output files but before generation is considered successful. These functions will be called after all documents have been written to the filesystem.
Note: This array is cleared after calling the contained functions on each call.

property preRenderAsyncJobs

preRenderAsyncJobs: Array<(output: MarkdownRendererEvent) => Promise<void>>;

A list of async jobs which must be completed before rendering output.
Note: This array is cleared after calling the contained functions on each call.

method on

on: {
    (
        event: typeof MarkdownPageEvent.BEGIN | typeof MarkdownPageEvent.END,
        callback: (page: MarkdownPageEvent) => void
    ): void;
    (
        event: 'beginRender' | 'endRender',
        callback: (page: MarkdownRendererEvent) => void
    ): void;
};

Parameter event
Triggered before or after a document will be rendered.
Parameter callback
Receives the MarkdownPageEvent object as an argument.
Example 1
app.renderer.on(MarkdownPageEvent.BEGIN, (renderer) => {});
Parameter event
Triggered before or after rendering the project.
Parameter callback
Receives the MarkdownRendererEvent object as an argument.
Example 1
app.renderer.on(MarkdownRendererEvent.BEGIN, (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 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 when anchoring to in-page symbols.

property blockTagsPreserveOrder

blockTagsPreserveOrder: string[];

Specifies comment block tags that should preserve their position in relation to the comment summary.

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 hideBreadcrumbs

hideBreadcrumbs: boolean;

Do not print breadcrumbs.

property hideGroupHeadings

hideGroupHeadings: boolean;

Excludes grouping by kind so all members are rendered and sorted 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 when outputFileStrategy equals members.

property mergeReadme

mergeReadme: boolean;

Merges the resolved readme into the project index 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';

Determines how output files are generated.

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 propertiesFormat

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

Sets the format of property groups for interfaces and classes.

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;
    'header.docs': string;
    'breadcrumbs.home': string;
    'title.indexPage': string;
    'title.memberPage': string;
    'footer.text': string;
};

Change specific text placeholders in the template.

property typeDeclarationFormat

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

Sets the format of style for type declaration members.

property useCodeBlocks

useCodeBlocks: boolean;

Wraps signatures and declarations in code blocks.

property useHTMLAnchors

useHTMLAnchors: boolean;

Add HTML named anchors to headings and table rows.

property useHTMLEncodedBrackets

useHTMLEncodedBrackets: boolean;

Use HTML encoded entities for angle brackets.

interface UrlMapping

interface UrlMapping<Model> {}

The model used to define the URL mapping structure.

property model

model: Model;

property template

template: (data: MarkdownPageEvent<Model>) => string;

property url

url: string;

Package Files (10)

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 1 day ago.
Package analyzed in 5556 ms.
Missing or incorrect documentation? Open an issue for this package.

typedoc-plugin-markdown

Install

Overview

Index

Functions

Classes

Interfaces

Functions

function load

See Also

Classes

class MarkdownPageEvent

constructor

property BEGIN

property contents

property END

property filename

property frontmatter

property model

property pageHeadings

property pageSections

property project

property startNewSection

property url

class MarkdownRendererEvent

constructor

property BEGIN

property END

property navigation

property outputDirectory

property project

property urls

method createPageEvent

class MarkdownTheme

constructor

method getNavigation

method getRenderContext

method getUrls

class MarkdownThemeContext

constructor

property helpers

property i18n

property internationalization

property options

property page

property partials

property templates

method getRelativeUrl

Parameter url

Parameter ignorePublicPath

Interfaces

interface MarkdownApplication

property renderer

interface MarkdownRenderer

property defineTheme

Parameter name

Parameter theme

property markdownHooks

property postRenderAsyncJobs

property preRenderAsyncJobs

method on

Parameter event

Parameter callback

Example 1

Parameter event

Parameter callback

Example 1

interface MarkdownRendererHooks

property ['content.begin']

property ['index.page.begin']

property ['index.page.end']

property ['page.begin']

property ['page.end']

interface NavigationItem

property children

property kind

property path

property title

interface PluginOptions

property anchorPrefix