@origints/markdown 0.1.1 → 0.3.2

package/README.md

@@ -4,14 +4,6 @@
 
 ---
 
-## Why
-
-Parsing Markdown is easy. Knowing exactly where each heading, link, or code block came from in the source is harder. When you're extracting structured data from Markdown documents, you need that connection.
-
-This package parses Markdown into a navigable tree while maintaining source positions for every node. Extract frontmatter, query by node type, and convert to HTML - all with full provenance.
-
----
-
 ## Features
 
 - Parse Markdown with GFM (GitHub Flavored Markdown) support
@@ -24,188 +16,205 @@ This package parses Markdown into a navigable tree while maintaining source posi
 
 ---
 
-## Quick Start
+## Installation
 
 ```bash
 npm install @origints/markdown @origints/core
 ```
 
-```ts
-import { parseMarkdown } from "@origints/markdown";
-
-const md = `
-# Hello World
+---
 
-This is a paragraph.
-`;
+## Usage with Planner
 
-const result = parseMarkdown(md);
+### Extract content from a Markdown file
 
-if (result.ok) {
-  const heading = result.value.find("heading");
-  console.log(heading?.text());
-}
-```
+```ts
+import { Planner, loadFile, run } from '@origints/core'
+import { parseMarkdown } from '@origints/markdown'
 
-Expected output:
+const plan = new Planner()
+  .in(loadFile('README.md'))
+  .mapIn(parseMarkdown())
+  .emit((out, $) => out.add('title', $.select('heading').text()))
+  .compile()
 
+const result = await run(plan, { readFile, registry })
+// result.value: { title: 'My Project' }
 ```
-Hello World
-```
-
----
 
-## Installation
+### Extract collections with selectAll
 
-- Supported platforms:
-  - macOS / Linux / Windows
-- Runtime requirements:
-  - Node.js >= 18
-- Package managers:
-  - npm, pnpm, yarn
-- Peer dependencies:
-  - @origints/core ^0.1.0
+Use `selectAll()` to extract data from all matching nodes as an array:
 
-```bash
-npm install @origints/markdown @origints/core
-# or
-pnpm add @origints/markdown @origints/core
+```ts
+// Extract all heading texts from a document
+const plan = new Planner()
+  .in(loadFile('README.md'))
+  .mapIn(parseMarkdown())
+  .emit((out, $) =>
+    out.add(
+      'headings',
+      $.selectAll('heading', node => node.text())
+    )
+  )
+  .compile()
+
+const result = await run(plan, { readFile, registry })
+// result.value: { headings: ['Introduction', 'Getting Started', 'API'] }
 ```
 
----
-
-## Usage
-
-### Basic parsing
+### Extract structured data from repeated nodes
 
 ```ts
-import { parseMarkdown } from "@origints/markdown";
-
-const result = parseMarkdown(`
-# Title
-
-A paragraph with **bold** and *italic*.
-
-- Item 1
-- Item 2
-`);
-
-if (result.ok) {
-  const doc = result.value;
+// Extract all link URLs and labels
+const plan = new Planner()
+  .in(loadFile('README.md'))
+  .mapIn(parseMarkdown())
+  .emit((out, $) =>
+    out.add(
+      'links',
+      $.selectAll('link', node => node.text())
+    )
+  )
+  .compile()
+```
 
-  // Find all headings
-  const headings = doc.findAll("heading");
+### Extract top-level children
 
-  // Find all links
-  const links = doc.findAll("link");
+Use `children()` to extract each direct child of a node:
 
-  // Get text content
-  const text = doc.text();
-}
+```ts
+const plan = new Planner()
+  .in(loadFile('README.md'))
+  .mapIn(parseMarkdown())
+  .emit((out, $) =>
+    out.add(
+      'blocks',
+      $.children(node => node.text())
+    )
+  )
+  .compile()
 ```
 
-### Frontmatter extraction
+### Extract frontmatter fields
 
 ```ts
-import { parseMarkdown, extractFrontmatter } from "@origints/markdown";
-
-const result = parseMarkdown(`
----
-title: My Post
-date: 2024-01-15
-tags:
-  - typescript
-  - origins
----
+// doc.md:
+// ---
+// title: My Post
+// date: 2024-01-15
+// tags:
+//   - typescript
+//   - origins
+// ---
+// # Content here
+
+const plan = new Planner()
+  .in(loadFile('doc.md'))
+  .mapIn(parseMarkdown())
+  .emit((out, $) => out.add('title', $.select('yaml').text()))
+  .compile()
+```
 
-# Content here
-`);
+### Combine Markdown with other sources
 
-if (result.ok) {
-  const frontmatter = extractFrontmatter(result.value);
-  console.log(frontmatter?.title);
-}
+```ts
+const plan = new Planner()
+  .in(loadFile('README.md'))
+  .mapIn(parseMarkdown())
+  .emit((out, $) => out.add('title', $.select('heading').text()))
+  .in(loadFile('package.json'))
+  .mapIn(parseJson())
+  .emit((out, $) =>
+    out
+      .add('version', $.get('version').string())
+      .add('name', $.get('name').string())
+  )
+  .compile()
 ```
 
-### Converting to HTML
+### Standalone usage (without Planner)
+
+For direct Markdown navigation:
 
 ```ts
-import { parseMarkdown, toHtml } from "@origints/markdown";
+import { parseMarkdownImpl, MarkdownNode } from '@origints/markdown'
 
-const result = parseMarkdown("# Hello\n\nWorld");
+const node = parseMarkdownImpl.execute(markdownString) as MarkdownNode
 
-if (result.ok) {
-  const html = toHtml(result.value);
-  // <h1>Hello</h1>\n<p>World</p>
+// Select nodes using CSS-like selectors
+const headingResult = node.select('heading')
+if (headingResult.ok) {
+  console.log(headingResult.value.text())
 }
-```
 
-### Using with Origins plans
+// Select by attribute
+const h1Result = node.select('heading[depth=1]')
+const codeResult = node.select('code[lang="typescript"]')
 
-```ts
-import { Planner, loadFile, globalRegistry } from "@origints/core";
-import { parseMarkdown, registerMarkdownTransforms } from "@origints/markdown";
-
-registerMarkdownTransforms(globalRegistry);
+// Nested selectors
+const listItems = node.selectAll('list > listItem')
 
-const plan = Planner.in(loadFile("README.md"))
-  .mapIn(parseMarkdown())
-  .emit((out, $) => {
-    const title = $.find("heading")?.text() ?? "Untitled";
-    out.add("title", title);
-  })
-  .compile();
+// Get all text content
+console.log(node.text())
 ```
 
 ### Typed node extraction
 
 ```ts
-import { parseMarkdown } from "@origints/markdown";
-import type { HeadingData, LinkData } from "@origints/markdown";
-
-const result = parseMarkdown(content);
-
-if (result.ok) {
-  // Get heading with typed data
-  const heading = result.value.find("heading");
-  const data: HeadingData | undefined = heading?.data();
-  console.log(data?.depth); // 1, 2, 3, etc.
+const headingResult = node.select('heading')
+if (headingResult.ok) {
+  const data = headingResult.value.asHeading()
+  if (data.ok) {
+    console.log(data.value.depth) // 1, 2, 3, etc.
+  }
+}
 
-  // Get link with typed data
-  const link = result.value.find("link");
-  const linkData: LinkData | undefined = link?.data();
-  console.log(linkData?.url);
+const linkResult = node.select('link')
+if (linkResult.ok) {
+  const data = linkResult.value.asLink()
+  if (data.ok) {
+    console.log(data.value.url)
+  }
 }
 ```
 
----
-
-## Project Status
-
-- **Experimental** - APIs may change
-
----
+### Converting to HTML
 
-## Non-Goals
+```ts
+import { parseMarkdownImpl, toHtml } from '@origints/markdown'
 
-- Not a Markdown renderer/serializer
-- Not a Markdown editor
-- Not a full MDX parser
+const node = parseMarkdownImpl.execute('# Hello\n\nWorld') as MarkdownNode
+const html = toHtml(node)
+// <h1>Hello</h1>\n<p>World</p>
+```
 
----
+### Frontmatter extraction (standalone)
 
-## Documentation
+```ts
+import { parseMarkdownImpl, extractFrontmatter } from '@origints/markdown'
 
-- See `@origints/core` for Origins concepts
-- See [remark](https://github.com/remarkjs/remark) for underlying parser
+const node = parseMarkdownImpl.execute(markdownWithFrontmatter) as MarkdownNode
+const frontmatter = extractFrontmatter(node)
+if (frontmatter) {
+  console.log(frontmatter.title)
+}
+```
 
 ---
 
-## Contributing
-
-- Open an issue before large changes
-- Keep PRs focused
-- Tests required for new features
+## API
+
+| Export                                 | Description                                           |
+| -------------------------------------- | ----------------------------------------------------- |
+| `parseMarkdown(options?)`              | Create a transform AST for use with `Planner.mapIn()` |
+| `parseMarkdownImpl`                    | Sync transform implementation (string input)          |
+| `parseMarkdownAsyncImpl`               | Async transform implementation (string or stream)     |
+| `registerMarkdownTransforms(registry)` | Register all Markdown transforms with a registry      |
+| `MarkdownNode`                         | Navigable wrapper with selector support               |
+| `toHtml(node)`                         | Convert Markdown to HTML                              |
+| `toJson(node, options?)`               | Convert MarkdownNode to JSON                          |
+| `extractFrontmatter(node)`             | Extract YAML frontmatter                              |
 
 ---