Typedown

Motivations

I often need to convert TypeScript definitions to Markdown to include them in a README file, discuss them in a GitHub issue or pull request, etc. so I decided to build a quick way to select in a custom Visual Studio Code editor various definitions from either a file or folder from a TypeScript project and export them to my clipboard in Markdown.

For more advanced use cases, you may want to check other solutions like TypeDoc (used internally).

Usage

You can export TypeScript definitions from either a file or a folder by invoking the associated Typedown command from the Visual Studio Code Command Palette (⌘ + ⇧ + P on macOS or Ctrl + ⇧ + P on Windows & Linux by default):

• Typedown: File Definitions to Markdown for a file.
• Typedown: Folder Definitions to Markdown for a folder.

The extension will collect your exported TypeScript definitions and present them to you in a custom Visual Studio Code editor fitting your theme where you will be able to select which definitions to export to Markdown. You can also select the heading level to use for the definition names.

When done, press the Export button to export the selected definitions to your clipboard in Markdown.

Definitions

Currently, only TypeScript interfaces & type aliases exported from your code are converted to Markdown.

Some comments and JSDoc tags in your code can also be used when exporting your definitions to infer a description, a default value, etc.

For example, imagine the following interface:

/**
 * A round plane figure whose boundary consists of points equidistant from a fixed point.
 */
export interface Circle extends Shape {
  kind: 'circle'
  /**
   * In pixels.
   * @default 10
   */
  radius?: number
}

The generated Markdown code is:

# Circle

A round plane figure whose boundary consists of points equidistant from a fixed point.

| Name   | Description | Type       | Optional | Default value |
| ------ | ----------- | ---------- | :------: | ------------- |
| kind   |             | `'circle'` |          |               |
| radius | In pixels.  | `number`   |    ✓     | 10            |

The rendered Markdown for this interface is:

Circle

A round plane figure whose boundary consists of points equidistant from a fixed point.

Name	Description	Type	Optional	Default value
kind		'circle'
radius	In pixels.	number	✓	10

License

Licensed under the MIT License, Copyright © HiDeoo.

See LICENSE for more information.