Generates markdown documentation from TypeScript source code.

Overview

tsdoc-markdown

Generates markdown documentation from TypeScript source code. Useful for generating docs from code and injecting automatically the outcome into project README files.

Installation

Install the library in your project from npm:

npm install -D tsdoc-markdown

GitHub Actions

A GitHub Actions workflow that generates the documentation for pull requests using this library is available in tsdoc.yml.

Usage

This tool is shipped with a NodeJS bin script that can be executed with the shortcut tsdoc.

e.g. generating the documentation for a source file ./src/index.ts:

tsdoc --src=src/index.ts

The --src parameter accepts a comma separated list of paths and wildcards as well.

e.g.

tsdoc --src=src/lib/*
tsdoc --src=src/lib/index.ts,src/lib/docs.ts

Note: the library exports per default only the documentation of the pattern you provide. It does not explore the TypeScript tree. If you wish to do so, either provide a PR to the Cli to support the option explore or create your own script for your project 😉

The Markdown documentation is parsed per default in a ./README.md that finds place where you started the command line. The output file will be over write unless you specify a TSDOC_START and TSDOC_END tag (as HTML comment). In such case, the documentation will be parsed within these two tags.

Specifying another output file is also supported with the parameter --dest.

Using above script is of course optional. You can also develop your own JavaScript script and use one of the functions here under.

e.g.

#!/usr/bin/env node

const {generateDocumentation} = require('tsdoc-markdown');

// Generate documentation for a list of files
const nnsInputFiles = [
  './packages/nns/src/account_identifier.ts',
  './packages/nns/src/genesis_token.canister.ts',
  './packages/nns/src/governance.canister.ts',
  './packages/nns/src/icp.ts'
];

generateDocumentation({
  inputFiles: nnsInputFiles,
  outputFile: './packages/nns/README.md'
});

// Start from a single file and explore the TypeScript tree

const utilsInputFiles = ['./packages/utils/src/index.ts'];

generateDocumentation({
  inputFiles: utilsInputFiles,
  outputFile: './packages/utils/YOLO.md',
  buildOptions: {explore: true}
});

Note: Chapter "Functions" is auto-generated with tsdoc-markdown.

🧰 Functions

⚙️ buildDocumentation

Build the documentation entries for the selected sources.

Function Type
buildDocumentation ({ inputFiles, options }: { inputFiles: string[]; options?: BuildOptions; }) => DocEntry[]

Parameters:

  • params.inputFiles: The list of files to scan and for which the documentation should be build.
  • params.options: Optional compiler options to generate the docs

⚙️ documentationToMarkdown

Convert the documentation entries to an opinionated Markdown format.

Function Type
documentationToMarkdown ({ entries, options }: { entries: DocEntry[]; options?: MarkdownOptions; }) => string

Parameters:

  • params.entries: The entries of the documentation (functions, constants and classes).
  • params.options: Optional configuration to render the Markdown content. See types.ts for details.

⚙️ generateDocumentation

Generate documentation and write output to a file. If the file exists, it will try to insert the docs between and comments. If these does not exist, the output file will be overwritten.

Function Type
generateDocumentation ({ inputFiles, outputFile, markdownOptions, buildOptions }: { inputFiles: string[]; outputFile: string; markdownOptions?: MarkdownOptions; buildOptions?: BuildOptions; }) => void

Parameters:

  • params.inputFiles: The list of files to scan for documentation. Absolute or relative path.
  • params.outputFile: The file to output the documentation in Markdown.
  • params.markdownOptions: Optional settings passed to the Markdown parser. See MarkdownOptions for details.
  • params.buildOptions: Options to construct the documentation tree. See BuildOptions for details.

Useful Resources

License

MIT © David Dal Busco

You might also like...

Open Source projects are a project to improve your JavaScript knowledge with JavaScript documentation, design patterns, books, playlists.

Open Source projects are a project to improve your JavaScript knowledge with JavaScript documentation, design patterns, books, playlists.

It is a project I am trying to list the repos that have received thousands of stars on Github and deemed useful by the JavaScript community. It's a gi

Aug 14, 2022

Convert some JavaScript/TypeScript code string into a .d.ts TypeScript Declaration code string

convert-to-dts Converts the source code for any .js or .ts file into the equivalent .d.ts code TypeScript would generate. Usage import { convertToDecl

Mar 3, 2022

Link your documentation to the relevant code files

Link your documentation to the relevant code files

Jul 19, 2022

Dokka plugin to render Mermaid graphics, from your code comments to your Dokka documentation.

Dokka plugin to render Mermaid graphics, from your code comments to your Dokka documentation.

Html Mermaid Dokka plugin Mermaid-Dokka MermaidJS 0.2.2 8.14.0 0.3.0 9.0.0 Step 1: install dependencies { dokkaPlugin("com.glureau:html-mermaid-dokk

Sep 16, 2022

Generate rich documentation data for TypeScript and MDX codebases.

⚠️ Currently under development, not ready for use yet This library is currently unstable and the API is in flux. It is being worked on in the open for

Oct 30, 2022

A refined tool for exploring open-source projects on GitHub with a file tree, rich Markdown and image previews, multi-pane multi-tab layouts and first-class support for Ink syntax highlighting.

A refined tool for exploring open-source projects on GitHub with a file tree, rich Markdown and image previews, multi-pane multi-tab layouts and first-class support for Ink syntax highlighting.

Ink codebase browser, "Kin" 🔍 The Ink codebase browser is a tool to explore open-source code on GitHub, especially my side projects written in the In

Oct 30, 2022

The open source embeddable online markdown editor (component).

The open source embeddable online markdown editor (component).

Editor.md Editor.md : The open source embeddable online markdown editor (component), based on CodeMirror & jQuery & Marked. Features Support Standard

Dec 30, 2022

Codebraid Preview provides a Markdown preview for Pandoc documents within VS Code.

Codebraid Preview provides a Markdown preview for Pandoc documents within VS Code.

Codebraid Preview provides a Markdown preview for Pandoc documents within VS Code. Most Markdown previews don't support all of Pandoc's extensions to Markdown syntax. Codebraid Preview supports 100% of Pandoc features—because the preview is generated by Pandoc itself! There is also full bidirectional scroll sync and document export.

Dec 28, 2022

A Hackable Markdown Note Application for Programmers. Version control, AI completion, mind map, documents encryption, code snippet running, integrated terminal, chart embedding, HTML applets, plug-in, and macro replacement.

A Hackable Markdown Note Application for Programmers. Version control, AI completion, mind map, documents encryption, code snippet running, integrated terminal, chart embedding, HTML applets, plug-in, and macro replacement.

Yank Note A hackable markdown note application for programmers Download | Try it Online Not ecommended English | 中文说明 [toc]{level: [2]} Highlights

Dec 31, 2022
Comments
  • NPM links to wrong package

    NPM links to wrong package

    Hello. I'm keen to use this package but npm installs a different package from the "cheap-glitch" org.

    npm install tsdoc-to-markdown -D
    

    Installs this incorrect package.

    question 
    opened by joeldbirch 7
  • generate url to code

    generate url to code

    It would be cool if the parser generates a markdown links linked with the source code of the function, constant etc. that gets documented.

    Maybe 🔗 instead of ⚙️

    opened by peterpeterparker 0
  • не работает с асинхронными методами((((

    не работает с асинхронными методами((((

    example:

    export default class foo {
      /**
      * Description
      */
      bar() {} 
    }
    

    output:

    
    ## :factory: default
    
    
    
    ### Constructors
    
    `public`
    
    
    
    ### Methods
    
    - [bar](#gear-bar)
    
    #### :gear: bar
    
    Description
    
    | Method | Type |
    | ---------- | ---------- |
    | `bar` | `() => void` |
    
    

    example:

    export default class foo {
      /**
      * Description
      */
      async bar() {} 
    }
    

    output:

    
    ## :factory: default
    
    
    
    ### Constructors
    
    `public`
    
    
    
    
    opened by VityaSchel 6
  • SyntaxError: Named export 'SyntaxKind' not found.

    SyntaxError: Named export 'SyntaxKind' not found.

    Compile is successful but when used in ES modules, the lib might throw following error:

    SyntaxError: Named export 'SyntaxKind' not found. The requested module 'typescript' is a CommonJS module, which may not support all module.exports as named exports. CommonJS modules can always be imported via the default export, for example using:...

    Stacktrace leads to TypeScript issue #45813 which might be solved in v4.6.x (?)

    opened by peterpeterparker 0
Releases(v0.0.1)
Owner
David Dal Busco
"They've done studies, you know. 60% of the time, it works every time." - Brian Fantana
David Dal Busco
This package generates a GraphQL API from a directory of Markdown files

This package generates a GraphQL API from a directory of Markdown files. Additional metadata like tags, descriptions, or custom fields can be added to the Markdown files in the form of YAML front matter, a simple schema at the top of each file. These fields will be indexed and available to query and filter by in the GraphQL API.

Tim Mikeladze 8 Dec 29, 2022
Markdoc is a Markdown-based syntax and toolchain for creating custom documentation sites and experiences.

A powerful, flexible, Markdown-based authoring framework. Markdoc is a Markdown-based syntax and toolchain for creating custom documentation sites and

Markdoc 5.8k Jan 2, 2023
MySQL meets Jupyter notebooks. Grasp provides a new way to learn and write SQL, by providing a coding-notebook style with runnable blocks, markdown documentation, and shareable notebooks. ✨

A New Way to Write & Learn SQL Report Bug · Request Feature Table of Contents About The Project Built With Getting Started Prerequisites Installation

Lakshya 7 Sep 1, 2022
This extension allows you to create Markdown files which are automatically transformed to in-game documentation for your Add-On.

Markdown Doc Generator An extension for bridge editor which makes creating docs in minecraft easier, by generating json-ui from markdown View extensio

Freddie 7 Dec 31, 2022
typescript-to-jsonschema generates JSON Schema files from your Typescript sources.

fast-typescript-to-jsonschema English | 简体中文 a tool generate json schema from typescript. Feature compile Typescript to get all type information conve

yunfly 21 Nov 28, 2022
A plugin for the Obsidian markdown note application, adding functionality to render markdown documents with multiple columns of text.

Multi-Column Markdown Take your boring markdown document and add some columns to it! With Multi Column Markdown rather than limiting your document lay

Cameron Robinson 91 Jan 2, 2023
A markdown-it plugin that process images through the eleventy-img plugin. Can be used in any projects that uses markdown-it.

markdown-it-eleventy-img A markdown-it plugin that process images through the eleventy-img plugin. Can be used in any projects that use markdown-it. F

null 25 Dec 20, 2022
An obsidian plugin for uploading local images embedded in markdown to remote store and export markdown for publishing to static site.

Obsidian Publish This plugin cloud upload all local images embedded in markdown to specified remote image store (support imgur only, currently) and ex

Addo.Zhang 7 Dec 13, 2022
Markdown Transformer. Transform markdown files to different formats

Mdtx Inspired by generative programming and weed :). So I was learning Elm language at home usually in the evening and now I am missing all this gener

Aexol 13 Jan 2, 2023
Landscape Generator is An open Source web application that generates landscape drawings randomly, then gives you the ability to edit it and export it as SVG or PNG.

Landscape Generator ## About Landscape Generator is An open Source web application that generates landscape drawings randomly, then gives you the abil

null 9 Apr 15, 2022