Formation Docs

Utilities to generate Markdown or HTML documentation files from JSDoc comments in JavaScript or TypeScript files.

Installation

npm install -D @alanizcreative/formation-docs

getDocs

getDocs(args: DocsArgs): Promise<DocsResult>

Rich text objects from source code and JSDoc explain.

Parameters

• args DocsArgs required

Returns

Promise<DocsResult>

Examples

// src/button/button.ts
// src/button/buttonTypes.ts
// src/form/__tests__/form.test.ts
// src/form/form.ts
/**
 * Form
 *
 * @file
 * title: Form Components
 * Output form, field and option elements.
 */
import type { FormType } from './formTypes.js'
/**
 * Outputs form element.
 *
 * @param {FormType} type
 * @return {string}
 */
const Form = (type: FormType): string => {
  // ...
}
// src/form/formTypes.ts:
/**
 * @typedef {'a'|'b'|'c'} FormType
 */
export type FormType = 'a' | 'b' | 'c'

// =========================================================================

import { getDocs } from '@alanizcreative/formation-docs/docs.js'

const result = await getDocs({
  include: 'src/**\/*.ts',
  exclude: 'src/**\/*.test.ts',
  docsInclude: 'src/form/**\/*.ts',
  docsExclude: 'src/**\/*Types.ts'
})

result = {
  'src/form': {
    content: [
      { tag: 'h1', content: 'Form Components' },
      { tag: 'p', content: 'Output form, field and option elements.' },
      { tag: 'h2', content: 'Form' },
      { tag: 'p', content: [{
        tag: 'strong', content: [{
          tag: 'code', content: [{
            content: 'Form(type: FormType): string'
          }]
        }]}
      ]},
      { tag: 'p', content: 'Outputs form element.' },
      { tag: 'h2', content: 'Parameters' },
      { tag: 'dl', content: [{
        tag: 'div', content: [{
          tag: 'dt', content: [
            { tag: 'strong', content: [{ tag: 'code', content: 'type' }]},
            { content: ' ' },
            { tag: 'code', content: [{
              content: [{ tag: 'a', content: 'FormType', link: '#formtype' }]
            }]},
            { content: ' ' },
            { content: 'required' }
          ]
        },
        { tag: 'dd', content: [] }
      ]}]},
      { tag: 'h2', content: 'Returns' },
      { tag: 'p', content: [{
        tag: 'code', content: [{ content: 'string' }]
      }]},
      { tag: 'h2', content: 'Types' },
      { tag: 'h3', content: 'FormType' },
      { tag: 'p', content: [
        { tag: 'strong', content: 'Type:' },
        { content: ' ' },
        { tag: 'code', content: [{
          content: [{ content: ''a' | 'b' | 'c'' }]
        }]}
      ]}
    ]
  } 
}

renderMarkdownDocs

renderMarkdownDocs(args: DocsArgs): Promise<void>

Output normalized JSDoc data as Markdown files.

Parameters

• args DocsArgs required

Returns

Promise<void>

Examples

import { renderMarkdownDocs } from '@alanizcreative/formation-docs/docs.js'

await renderMarkdownDocs({
  include: 'src/**\/*.ts',
  exclude: [
    'src/**\/*.test.ts',
    'src/**\/*Mock.ts'
  ],
  docsInclude: 'src/form/**\/*.ts',
  docsExclude: 'src/**\/*Types.ts'
})

// src/button/button.ts
// src/button/buttonTypes.ts
// src/form/__tests__/form.test.ts
// src/form/form.ts
// src/form/README.md
// src/form/formMock.ts
// src/form/formTypes.ts

renderHtmlDocs

renderHtmlDocs(args: DocsHtmlArgs): Promise<void>

Output normalized JSDoc data as HTML files.

Parameters

• args DocsHtmlArgs required

Returns

Promise<void>

Examples

import { renderHtmlDocs } from '@alanizcreative/formation-docs/docs.js'

await renderHtmlDocs({
  outDir: 'docs',
  include: 'src/**\/*.ts',
  exclude: 'src/**\/*.test.ts',
  docsExclude: 'src/**\/*Types.ts',
  url: 'https://docs.formation.org'
})

// src/button/button.ts
// src/button/buttonTypes.ts
// src/form/__tests__/form.test.ts
// src/form/form.ts
// src/form/formTypes.ts
// docs/button/index.html
// docs/form/index.html

Types

DocsFilterTitle

Type: function

Parameters

• title string required
• dir string required

DocsArgs

Type: object

Properties

• include string | string[] required
  Glob pattern of files to include in types.
• exclude string | string[] optional
  Glob pattern of files to exclude from types.
• docsInclude string | string[] optional
  Glob pattern of files to include in result.
• docsExclude string | string[] optional
  Glob pattern of files to exclude from result.
• docsTypes string | string[] optional
  Glob pattern of type definition files.
• srcDir string optional
  Source directory of input files.
  Default: src
• outDir string optional
  Directory to write documentation files to.
• url string optional
  Repository URL for Markdown docs or site URL for HTML docs.
• index string optional
  Comments representing index documentation page.
• filterTitle DocsFilterTitle optional
  Customize title for multi file directories.

DocsContent

Type: object

Properties

• content string | DocsContent[] required
  Plain text or nested HTML content.
• tag string optional
  HTML element tag.
• link string optional
  Anchor link to type definition.

DocsResult

Type: Object<string, DocsContent>

DocsFilterAttr

Type: function

Parameters

• attr Object<string, string> required
  Element attributes as key-value pairs.
• data DocsContent required
  Element tag and content.
• outerTag string required
  Parent element tag.

Returns

Object<string, string>

DocsNavigationItem

Type: object

Properties

• id string required
• title string required
• link string required
• children DocsNavigationItem[] optional

DocsHeading

Type: object

Properties

• id string required
• tag string required
• title string required
• children DocsHeading[] optional

DocsFilterOutput

Type: function

Parameters

• output string required
  HTML output.
• id string required
  Kebab case of file path.
• title string required
  File title.
• slug string required
  File path as link.
• navigation DocsNavigationItem[] required
  Objects matching directory stucture in alphabetical order.
• headings DocsHeading[] required
  File headings as nested object stucture.
• css string optional
  CSS output by Shiki.

Returns

string

DocsHtmlArgs

Type: object

Augments: DocsArgs

Properties

• outDir string optional
  Directory to write documentation files to.
  Default: docs
• themes Object<string, string> optional
  Themes to pass to Shiki for syntax highlighting.
• classPrefix string optional
  Prefix classes output by Shiki Transformer.
• filterAttr DocsFilterAttr optional
  Customize HTML element attributes.
• filterOutput DocsFilterOutput optional
  Customize HTML output.