Skip to content

refactor(markdown-toolkit): build and read nodes only in mdast/ - #200

Draft
Jason3S wants to merge 1 commit into
mainfrom
claude/md-node-constructors
Draft

Jason3S wants to merge 1 commit into
mainfrom
claude/md-node-constructors

Conversation

@Jason3S

@Jason3S Jason3S commented Nov 11, 2026

Copy link
Copy Markdown
Contributor

Summary

Builders, element/ and the template helpers now build and read Markdown nodes through functions in mdast/, such as strongNode(children), instead of writing node objects by hand. This is one step toward keeping all tree code in that one folder.

Waits on the parser move: the build fails until the parser is in mdast/. Other layers now name node types from mdast/index.ts, so the public type bundle reaches the folder's declarations:

  • The folder's index still re-exports htmlEntityFromMarkdown for template/parse.ts.
  • Its type comes from mdast-util-from-markdown, whose own types augment micromark-util-types.
  • The bundle keeps that augmentation, and the dependency check stops the build.

Once the parser is in mdast/, the extension is private to the folder, and the build passes. A local trial confirmed this: dist/index.d.ts came out as on main.

Node constructors and readers (mdast/nodes.ts)

  • One constructor for each node type the other layers build, such as paragraphNode, headingNode, listNode and tableNode.
  • listNode numbers the list when given a start. listItemNode makes a task when given checked. tableNode takes the content of each cell, row by row.
  • Readers for what other layers checked by hand: frontmatterOf, withoutFrontmatter and paragraphContent.
  • Other layers name node types such as RootContent through the folder's index, not from mdast.

Node helpers moved into the folder

  • textNodes, stringNodes and joinLines go to mdast/text.ts, and inLists to mdast/lists.ts.
  • isFormatting moves from blanks.ts to nodes.ts.

The mdast augmentations, in one file that nothing imports

The four declare module 'mdast' blocks move to mdast/customNodes.ts. In declaration files they're side effects, so a type import from the folder pulled them, and all of @types/mdast, into the public types. In a file with no importers, they apply only when the package's own source is type-checked.

Layer test

src/layers.test.ts fails when a file outside mdast/ imports a tree package: mdast, remark-*, unified, unist-*, micromark* or mdast-util-*. It lists the five files that still do, and the next steps empty that list.

Builders, element/ and the template helpers build and read nodes through
mdast/'s functions instead of writing node objects by hand, so tree code
stays in one folder. The mdast augmentations move to a file nothing
imports, so the public types can't reach them.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant