简体中文 | English

介绍

jsdoctomd 是一个可以将带有JSDoc注释的JS或TS文件转换为markdown的工具。

安装

# npm
npm i @binbinji/jsdoctomd -D
# yarn
yarn add @binbinji/jsdoctomd -D
# pnpm
pnpm add @binbinji/jsdoctomd -D

示例

JS

TS

API

| 参数 | 类型 | 是否可选 | 默认值 | 描述 | | --- | --- | --- | --- | --- | | input | string | false | - | 想解析的文件内容 | | extname | string | false | - | 文件类型，比如js或者ts | | generate | (func: generateFunction) => string | true | - | 自定义markdown格式 |

使用指南

js脚本

可以通过js脚本读文件，转化，生成md文件。

import fs from 'fs'
import { fileURLToPath } from 'url'
import { jsdocToMD } from '@binbinji/jsdoctomd'

function generateMD() {
  const examplePath = fileURLToPath(new URL('../example', import.meta.url))
  const docsPath = fileURLToPath(new URL('../docs', import.meta.url))
  const exampleFiles = fs.readdirSync(examplePath)

  exampleFiles.forEach((file) => {
    const [fileName, extname] = file.split('.')
    const input = fs.readFileSync(`${examplePath}/${file}`, 'utf-8')

    const output = jsdocToMD({ input, extname })

    if (!fs.existsSync(docsPath)) {
      fs.mkdirSync(docsPath)
    }
    fs.writeFileSync(`${docsPath}/${fileName}.md`, output)
  })
}

generateMD()

使用gulp

也可以使用 gulp 来自动化工作流。

// gulpfile.js

import { src, dest } from 'gulp'
import rename from 'gulp-rename'
import { Transform } from 'stream'
import { jsdocToMD } from '@binbinji/jsdoctomd'

function generateMDFiles() {
  return src('example/*.{ts,js}') // the files will be converted to md
    .pipe(
      new Transform({
        objectMode: true,
        transform(file, _enc, cb) {
          const extname = file.extname.slice(1)
          const output = jsdocToMD({ input: file.contents.toString(), extname })
          file.contents = Buffer.from(output)

          cb(null, file)
        },
      }),
    )
    .pipe(rename({ extname: '.md' }))
    .pipe(dest('docs')) // the output dir
}

export default generateMDFiles