{"id":19584825,"url":"https://github.com/flex-development/docast-util-from-docs","last_synced_at":"2026-01-02T12:03:42.802Z","repository":{"id":222953330,"uuid":"758387961","full_name":"flex-development/docast-util-from-docs","owner":"flex-development","description":"docast utility to parse docblocks","archived":false,"fork":false,"pushed_at":"2024-05-23T05:26:53.000Z","size":2867,"stargazers_count":1,"open_issues_count":11,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-05-23T06:31:58.790Z","etag":null,"topics":["comment","docast","docblock","documentation","jsdoc","markdown","mdast","parse","tokenize","tsdoc","typedoc","typescript","unist"],"latest_commit_sha":null,"homepage":"https://github.com/flex-development/docast-util-from-docs","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flex-development.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/funding.yml","license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":["flex-development"]}},"created_at":"2024-02-16T08:01:15.000Z","updated_at":"2024-05-30T07:55:03.296Z","dependencies_parsed_at":"2024-03-26T07:28:37.078Z","dependency_job_id":"2a6b3790-0505-4e90-81ad-843168b9c446","html_url":"https://github.com/flex-development/docast-util-from-docs","commit_stats":null,"previous_names":["flex-development/docast-util-from-docs"],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fdocast-util-from-docs","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fdocast-util-from-docs/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fdocast-util-from-docs/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flex-development%2Fdocast-util-from-docs/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flex-development","download_url":"https://codeload.github.com/flex-development/docast-util-from-docs/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242852058,"owners_count":20195759,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["comment","docast","docblock","documentation","jsdoc","markdown","mdast","parse","tokenize","tsdoc","typedoc","typescript","unist"],"created_at":"2024-11-11T07:49:59.341Z","updated_at":"2026-01-02T12:03:42.725Z","avatar_url":"https://github.com/flex-development.png","language":"TypeScript","readme":"# docast-util-from-docs\n\n[![github release](https://img.shields.io/github/v/release/flex-development/docast-util-from-docs.svg?include_prereleases\u0026sort=semver)](https://github.com/flex-development/docast-util-from-docs/releases/latest)\n[![npm](https://img.shields.io/npm/v/@flex-development/docast-util-from-docs.svg)](https://npmjs.com/package/@flex-development/docast-util-from-docs)\n[![codecov](https://codecov.io/gh/flex-development/docast-util-from-docs/graph/badge.svg?token=um87Ekggjn)](https://codecov.io/gh/flex-development/docast-util-from-docs)\n[![module type: esm](https://img.shields.io/badge/module%20type-esm-brightgreen)](https://github.com/voxpelli/badges-cjs-esm)\n[![license](https://img.shields.io/github/license/flex-development/docast-util-from-docs.svg)](LICENSE.md)\n[![conventional commits](https://img.shields.io/badge/-conventional%20commits-fe5196?logo=conventional-commits\u0026logoColor=ffffff)](https://conventionalcommits.org/)\n[![typescript](https://img.shields.io/badge/-typescript-3178c6?logo=typescript\u0026logoColor=ffffff)](https://typescriptlang.org/)\n[![vitest](https://img.shields.io/badge/-vitest-6e9f18?style=flat\u0026logo=vitest\u0026logoColor=ffffff)](https://vitest.dev/)\n[![yarn](https://img.shields.io/badge/-yarn-2c8ebb?style=flat\u0026logo=yarn\u0026logoColor=ffffff)](https://yarnpkg.com/)\n\n[**docast**][docast] utility that turns docblocks into a syntax tree.\n\n## Contents\n\n- [What is this?](#what-is-this)\n- [When should I use this?](#when-should-i-use-this)\n- [Install](#install)\n- [Use](#use)\n- [API](#api)\n  - [`fromDocs(value[, options])`](#fromdocsvalue-options)\n  - [`parseMarkdown\u003cT\u003e(value, options)`](#parsemarkdowntvalue-options)\n  - [`MarkdownOptions`](#markdownoptions)\n  - [`Options`](#options)\n  - [`ParseMarkdownOptions`](#parsemarkdownoptions)\n  - [`Transform`](#transform)\n- [Syntax](#syntax)\n  - [Docblock](#docblock)\n  - [Markdown](#markdown)\n- [Syntax tree](#syntax-tree)\n- [Types](#types)\n- [Contribute](#contribute)\n\n## What is this?\n\nThis package is a utility that takes [docblock][docblock] input and turns it into a [docast][docast] syntax tree.\n\nThis utility turns docblocks into tokens, and then turns those tokens into nodes. Markdown in docblocks is turned into\ntokens using [micromark][micromark], and turned into nodes using [mdast-util-from-markdown][mdast-util-from-markdown].\nThis package is also the backbone of [`docast-parse`][docast-parse], a [**unified**][unified] compliant file parser that\nfocuses on making it easier to transform docblocks by abstracting these internals away.\n\n## When should I use this?\n\n**TODO**: ecosystem\n\nIf you want to handle syntax trees manually, use this. For an easier time processing docblocks, use\n[`docast-parse`][docast-parse] instead.\n\n## Install\n\nThis package is [ESM only][esm].\n\nIn Node.js (version 18+) with [yarn][yarn]:\n\n```sh\nyarn add @flex-development/docast-util-from-docs\n```\n\n\u003cblockquote\u003e\n  \u003csmall\u003e\n    See \u003ca href='https://yarnpkg.com/protocol/git'\u003eGit - Protocols | Yarn\u003c/a\u003e\n    \u0026nbsp;for details regarding installing from Git.\n  \u003c/small\u003e\n\u003c/blockquote\u003e\n\nIn Deno with [`esm.sh`][esmsh]:\n\n```ts\nimport { fromDocs } from 'https://esm.sh/@flex-development/docast-util-from-docs'\n```\n\nIn browsers with [`esm.sh`][esmsh]:\n\n```html\n\u003cscript type=\"module\"\u003e\n  import { fromDocs } from 'https://esm.sh/@flex-development/docast-util-from-docs'\n\u003c/script\u003e\n```\n\n## Use\n\nSay we have the following TypeScript file `fibonacci-sequence.ts`:\n\n````ts\n/**\n * @file FibonacciSequence\n * @module FibonacciSequence\n * @see https://codewars.com/kata/55695bc4f75bbaea5100016b\n */\n\n/**\n * Fibonacci sequence iterator.\n *\n * :::info\n * A fibonacci sequence starts with two `1`s. Every element afterwards is the\n * sum of the two previous elements:\n * ```txt\n * 1, 1, 2, 3, 5, 8, 13, ..., 89, 144, 233, 377, ...\n * ```\n * :::\n *\n * @implements {Iterator\u003cnumber, number\u003e}\n */\nclass FibonacciSequence implements Iterator\u003cnumber, number\u003e {\n  /**\n   * First managed sequence value.\n   *\n   * @public\n   * @instance\n   * @member {number} fib1\n   */\n  public fib1: number\n\n  /**\n   * Second managed sequence value.\n   *\n   * @public\n   * @instance\n   * @member {number} fib2\n   */\n  public fib2: number\n\n  /**\n   * Max sequence value.\n   *\n   * @private\n   * @instance\n   * @member {number} max\n   */\n  readonly #max: number\n\n  /**\n   * Create a new fibonacci sequence iterator.\n   *\n   * @param {number} [max=Number.MAX_SAFE_INTEGER] - Max sequence value\n   */\n  constructor(max: number = Number.MAX_SAFE_INTEGER) {\n    this.#max = max \u003c 0 ? 0 : max\n    this.fib1 = this.fib2 = 1\n  }\n\n  /**\n   * Iterable protocol.\n   *\n   * @public\n   * @instance\n   *\n   * @return {IterableIterator\u003cnumber\u003e} Current sequence iterator\n   */\n  public [Symbol.iterator](): IterableIterator\u003cnumber\u003e {\n    return this\n  }\n\n  /**\n   * Get the next value in the fibonacci sequence.\n   *\n   * @public\n   * @instance\n   *\n   * @return {IteratorResult\u003cnumber, number\u003e} Next sequence value\n   */\n  public next(): IteratorResult\u003cnumber, number\u003e {\n    /**\n     * Temporary sequence value.\n     *\n     * @const {number} value\n     */\n    const value: number = this.fib1\n\n    // reset current sequence values\n    this.fib1 = this.fib2\n    this.fib2 = value + this.fib1\n\n    return { done: value \u003e= this.#max, value }\n  }\n}\n\nexport default FibonacciSequence\n````\n\n…and our module `example.mjs` looks as follows:\n\n```js\nimport { fromDocs } from '@flex-development/docast-util-from-docs'\nimport { inspect } from '@flex-development/unist-util-inspect'\nimport { directiveFromMarkdown } from 'mdast-util-directive'\nimport { directive } from 'micromark-extension-directive'\nimport { read } from 'to-vfile'\n\nconst file = await read('fibonacci-sequence.ts')\n\nconst tree = fromDocs(file, {\n  mdastExtensions: [directiveFromMarkdown()],\n  micromarkExtensions: [directive()]\n})\n\nconsole.log(inspect(tree))\n```\n\n…now running `node example.mjs` yields:\n\n```sh\nroot[9]\n├─0 comment[3] (1:1-5:4, 0-122)\n│   │ code: null\n│   ├─0 blockTag\u003c@file\u003e[1] (2:4-2:27, 7-30)\n│   │   └─0 text \"FibonacciSequence\" (2:10-2:27, 13-30)\n│   ├─1 blockTag\u003c@module\u003e[1] (3:4-3:29, 34-59)\n│   │   └─0 text \"FibonacciSequence\" (3:12-3:29, 42-59)\n│   └─2 blockTag\u003c@see\u003e[1] (4:4-4:59, 63-118)\n│       └─0 text \"https://codewars.com/kata/55695bc4f75bbaea5100016b\" (4:9-4:59, 68-118)\n├─1 comment[2] (7:1-19:4, 124-414)\n│   │ code: null\n│   ├─0 description[4] (8:4-16:7, 131-365)\n│   │   ├─0 paragraph[1] (8:4-8:32, 131-159)\n│   │   │   └─0 text \"Fibonacci sequence iterator.\" (8:4-8:32, 131-159)\n│   │   ├─1 break (8:32-9:1, 159-160)\n│   │   ├─2 break (9:3-10:1, 162-163)\n│   │   │     data: {\"blank\":true}\n│   │   └─3 containerDirective\u003cinfo\u003e[2] (10:4-16:7, 166-365)\n│   │       │ attributes: {}\n│   │       ├─0 paragraph[3] (11:4-12:37, 177-288)\n│   │       │   ├─0 text \"A fibonacci sequence starts with two \" (11:4-11:41, 177-214)\n│   │       │   ├─1 inlineCode \"1\" (11:41-11:44, 214-217)\n│   │       │   └─2 text \"s. Every element afterwards is the sum of the two previous elements:\" (11:44-12:37, 217-288)\n│   │       └─1 code \"1, 1, 2, 3, 5, 8, 13, ..., 89, 144, 233, 377, ...\" (13:4-15:7, 292-358)\n│   │             lang: \"txt\"\n│   │             meta: null\n│   └─1 blockTag\u003c@implements\u003e[1] (18:4-18:42, 372-410)\n│       └─0 typeExpression \"Iterator\u003cnumber, number\u003e\" (18:16-18:42, 384-410)\n├─2 comment[4] (21:3-27:6, 479-583)\n│   │ code: null\n│   ├─0 description[1] (22:6-22:35, 488-517)\n│   │   └─0 paragraph[1] (22:6-22:35, 488-517)\n│   │       └─0 text \"First managed sequence value.\" (22:6-22:35, 488-517)\n│   ├─1 blockTag\u003c@public\u003e[0] (24:6-24:13, 528-535)\n│   ├─2 blockTag\u003c@instance\u003e[0] (25:6-25:15, 541-550)\n│   └─3 blockTag\u003c@member\u003e[2] (26:6-26:27, 556-577)\n│       ├─0 typeExpression \"number\" (26:14-26:22, 564-572)\n│       └─1 text \"fib1\" (26:23-26:27, 573-577)\n├─3 comment[4] (30:3-36:6, 609-714)\n│   │ code: null\n│   ├─0 description[1] (31:6-31:36, 618-648)\n│   │   └─0 paragraph[1] (31:6-31:36, 618-648)\n│   │       └─0 text \"Second managed sequence value.\" (31:6-31:36, 618-648)\n│   ├─1 blockTag\u003c@public\u003e[0] (33:6-33:13, 659-666)\n│   ├─2 blockTag\u003c@instance\u003e[0] (34:6-34:15, 672-681)\n│   └─3 blockTag\u003c@member\u003e[2] (35:6-35:27, 687-708)\n│       ├─0 typeExpression \"number\" (35:14-35:22, 695-703)\n│       └─1 text \"fib2\" (35:23-35:27, 704-708)\n├─4 comment[4] (39:3-45:6, 740-834)\n│   │ code: null\n│   ├─0 description[1] (40:6-40:25, 749-768)\n│   │   └─0 paragraph[1] (40:6-40:25, 749-768)\n│   │       └─0 text \"Max sequence value.\" (40:6-40:25, 749-768)\n│   ├─1 blockTag\u003c@private\u003e[0] (42:6-42:14, 779-787)\n│   ├─2 blockTag\u003c@instance\u003e[0] (43:6-43:15, 793-802)\n│   └─3 blockTag\u003c@member\u003e[2] (44:6-44:26, 808-828)\n│       ├─0 typeExpression \"number\" (44:14-44:22, 816-824)\n│       └─1 text \"max\" (44:23-44:26, 825-828)\n├─5 comment[2] (48:3-52:6, 862-995)\n│   │ code: null\n│   ├─0 description[1] (49:6-49:47, 871-912)\n│   │   └─0 paragraph[1] (49:6-49:47, 871-912)\n│   │       └─0 text \"Create a new fibonacci sequence iterator.\" (49:6-49:47, 871-912)\n│   └─1 blockTag\u003c@param\u003e[2] (51:6-51:72, 923-989)\n│       ├─0 typeExpression \"number\" (51:13-51:21, 930-938)\n│       └─1 text \"[max=Number.MAX_SAFE_INTEGER] - Max sequence value\" (51:22-51:72, 939-989)\n├─6 comment[4] (58:3-65:6, 1122-1259)\n│   │ code: null\n│   ├─0 description[1] (59:6-59:24, 1131-1149)\n│   │   └─0 paragraph[1] (59:6-59:24, 1131-1149)\n│   │       └─0 text \"Iterable protocol.\" (59:6-59:24, 1131-1149)\n│   ├─1 blockTag\u003c@public\u003e[0] (61:6-61:13, 1160-1167)\n│   ├─2 blockTag\u003c@instance\u003e[0] (62:6-62:15, 1173-1182)\n│   └─3 blockTag\u003c@return\u003e[2] (64:6-64:66, 1193-1253)\n│       ├─0 typeExpression \"IterableIterator\u003cnumber\u003e\" (64:14-64:40, 1201-1227)\n│       └─1 text \"Current sequence iterator\" (64:41-64:66, 1228-1253)\n├─7 comment[4] (70:3-77:6, 1340-1504)\n│   │ code: null\n│   ├─0 description[1] (71:6-71:51, 1349-1394)\n│   │   └─0 paragraph[1] (71:6-71:51, 1349-1394)\n│   │       └─0 text \"Get the next value in the fibonacci sequence.\" (71:6-71:51, 1349-1394)\n│   ├─1 blockTag\u003c@public\u003e[0] (73:6-73:13, 1405-1412)\n│   ├─2 blockTag\u003c@instance\u003e[0] (74:6-74:15, 1418-1427)\n│   └─3 blockTag\u003c@return\u003e[2] (76:6-76:66, 1438-1498)\n│       ├─0 typeExpression \"IteratorResult\u003cnumber, number\u003e\" (76:14-76:46, 1446-1478)\n│       └─1 text \"Next sequence value\" (76:47-76:66, 1479-1498)\n└─8 comment[2] (79:5-83:8, 1559-1639)\n    │ code: null\n    ├─0 description[1] (80:8-80:33, 1570-1595)\n    │   └─0 paragraph[1] (80:8-80:33, 1570-1595)\n    │       └─0 text \"Temporary sequence value.\" (80:8-80:33, 1570-1595)\n    └─1 blockTag\u003c@const\u003e[2] (82:8-82:29, 1610-1631)\n        ├─0 typeExpression \"number\" (82:15-82:23, 1617-1625)\n        └─1 text \"value\" (82:24-82:29, 1626-1631)\n```\n\n## API\n\nThis package exports the following identifiers:\n\n- [`fromDocs`](#fromdocsvalue-options)\n- [`parseMarkdown`](#parsemarkdowntvalue-options)\n\nThere is no default export.\n\n### `fromDocs(value[, options])`\n\nTurn docblocks into a syntax tree.\n\n#### Parameters\n\n- `value` ([`VFile`][vfile] | `string`) \u0026mdash; source document or file containing docblocks to parse\n- `options` ([`Options`](#options), optional) \u0026mdash; configuration options\n\n#### Returns\n\ndocast tree ([`Root`][docast-tree])\n\n### `parseMarkdown\u003cT\u003e(value, options)`\n\nTurn markdown into [`mdast`][mdast] child nodes, with respect for comment delimiters.\n\n#### Type Parameters\n\n- `T` ([`RootContent`][mdast-content]) \u0026mdash; `mdast` child node type\n\n#### Parameters\n\n- `value` ([`VFile`][vfile] | `string`) \u0026mdash; markdown to parse\n- `options` ([`ParseMarkdownOptions`](#parsemarkdownoptions)) \u0026mdash; configuration options\n\n#### Returns\n\n`mdast` child node array (`T[]`)\n\n### `MarkdownOptions`\n\nMarkdown configuration options (TypeScript type).\n\n#### Properties\n\n- `mdastExtensions` ([`mdast.Extension[]`][mdast-extension], optional) \u0026mdash; markdown extensions to change how\n  micromark tokens are converted to nodes\n- `micromarkExtensions` ([`micromark.Extension[]`][micromark-extension], optional) \u0026mdash; micromark extensions to\n  change how markdown is parsed\n\n### `Options`\n\nConfiguration options (TypeScript type).\n\n#### Extends\n\n- [`MarkdownOptions`](#markdownoptions)\n\n#### Properties\n\n- `codeblocks` (`OneOrMany\u003cRegExp | string\u003e`, optional) \u0026mdash; block tag names, or regular expressions, matching block\n  tags that should have their text converted to [`Code`][mdast-code] when parsed as markdown\n  - **default**: `'@example'`\n- `from` ([`docast.Point`][docast-point], optional) \u0026mdash; parser start point. node positions will be relative to this\n  point\n  - **default**: `{ column: 1, line: 1, offset: 0 }`\n- `transforms` ([`Transform[]`](#transform), optional) \u0026mdash; tree transforms\n\n### `ParseMarkdownOptions`\n\nOptions for parsing markdown with respect for comment delimiters (TypeScript type).\n\n#### Extends\n\n- [`MarkdownOptions`](#markdownoptions)\n\n#### Properties\n\n- `code` (`boolean`, optional) \u0026mdash; parse markdown value as fenced code\n- `multiline` (`boolean`, optional) \u0026mdash; parse multiline comments\n- `position` ([`Position`][docast-position]) \u0026mdash; position of markdown value\n\n### `Transform`\n\nChange the AST after parsing is complete (TypeScript type).\n\n#### Parameters\n\n- `tree` ([`Root`][docast-tree]) \u0026mdash; tree to transform\n\n#### Returns\n\nnothing (`void`)\n\n## Syntax\n\n### Docblock\n\n**TODO**: docblock syntax\n\n### Markdown\n\nMarkdown is parsed according to CommonMark. Extensions can add support for other syntax and nodes. If you’re interested\nin extending markdown, more information is available in the [`mdast-util-from-markdown`][mdast-util-from-markdown] and\n[`micromark`][micromark] readmes.\n\n## Syntax tree\n\nThe syntax tree is [docast][docast].\n\n## Types\n\nThis package is fully typed with [TypeScript][typescript].\n\n## Contribute\n\nSee [`CONTRIBUTING.md`](CONTRIBUTING.md).\n\n[docast-parse]: https://github.com/flex-development/docast-parse\n[docast-point]: https://github.com/flex-development/docast#point\n[docast-position]: https://github.com/flex-development/docast#position\n[docast-tree]: https://github.com/flex-development/docast#root\n[docast]: https://github.com/flex-development/docast\n[docblock]: https://github.com/flex-development/docast#docblock-comment\n[esm]: https://gist.github.com/sindresorhus/a39789f98801d908bbc7ff3ecc99d99c\n[esmsh]: https://esm.sh/\n[mdast-code]: https://github.com/syntax-tree/mdast#code\n[mdast-content]: https://github.com/syntax-tree/mdast#content-model\n[mdast-extension]: https://github.com/syntax-tree/mdast-util-from-markdown#extension\n[mdast-util-from-markdown]: https://github.com/syntax-tree/mdast-util-from-markdown\n[mdast]: https://github.com/syntax-tree/mdast\n[micromark-extension]: https://github.com/micromark/micromark#extensions\n[micromark]: https://github.com/micromark/micromark\n[typescript]: https://www.typescriptlang.org\n[unified]: https://github.com/unifiedjs/unified\n[vfile]: https://github.com/vfile/vfile#api\n[yarn]: https://yarnpkg.com\n","funding_links":["https://github.com/sponsors/flex-development"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Fdocast-util-from-docs","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflex-development%2Fdocast-util-from-docs","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflex-development%2Fdocast-util-from-docs/lists"}