@origints/markdown 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,214 @@
+# @origints/markdown
+
+> Markdown parsing and manipulation for Origins with full lineage tracking.
+
+---
+
+## 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
+- YAML frontmatter extraction
+- Source position tracking for all nodes
+- Type-safe navigation and extraction
+- Convert to HTML
+- Support for tables, task lists, and footnotes
+- Integrates with Origins transform registry
+
+---
+
+## Quick Start
+
+```bash
+npm install @origints/markdown @origints/core
+```
+
+```ts
+import { parseMarkdown } from "@origints/markdown";
+
+const md = `
+# Hello World
+
+This is a paragraph.
+`;
+
+const result = parseMarkdown(md);
+
+if (result.ok) {
+  const heading = result.value.find("heading");
+  console.log(heading?.text());
+}
+```
+
+Expected output:
+
+```
+Hello World
+```
+
+---
+
+## Installation
+
+- Supported platforms:
+  - macOS / Linux / Windows
+- Runtime requirements:
+  - Node.js >= 18
+- Package managers:
+  - npm, pnpm, yarn
+- Peer dependencies:
+  - @origints/core ^0.1.0
+
+```bash
+npm install @origints/markdown @origints/core
+# or
+pnpm add @origints/markdown @origints/core
+```
+
+---
+
+## Usage
+
+### Basic parsing
+
+```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;
+
+  // Find all headings
+  const headings = doc.findAll("heading");
+
+  // Find all links
+  const links = doc.findAll("link");
+
+  // Get text content
+  const text = doc.text();
+}
+```
+
+### Frontmatter extraction
+
+```ts
+import { parseMarkdown, extractFrontmatter } from "@origints/markdown";
+
+const result = parseMarkdown(`
+---
+title: My Post
+date: 2024-01-15
+tags:
+  - typescript
+  - origins
+---
+
+# Content here
+`);
+
+if (result.ok) {
+  const frontmatter = extractFrontmatter(result.value);
+  console.log(frontmatter?.title);
+}
+```
+
+### Converting to HTML
+
+```ts
+import { parseMarkdown, toHtml } from "@origints/markdown";
+
+const result = parseMarkdown("# Hello\n\nWorld");
+
+if (result.ok) {
+  const html = toHtml(result.value);
+  // <h1>Hello</h1>\n<p>World</p>
+}
+```
+
+### Using with Origins plans
+
+```ts
+import { Planner, loadFile, globalRegistry } from "@origints/core";
+import { parseMarkdown, registerMarkdownTransforms } from "@origints/markdown";
+
+registerMarkdownTransforms(globalRegistry);
+
+const plan = Planner.in(loadFile("README.md"))
+  .mapIn(parseMarkdown())
+  .emit((out, $) => {
+    const title = $.find("heading")?.text() ?? "Untitled";
+    out.add("title", title);
+  })
+  .compile();
+```
+
+### 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.
+
+  // Get link with typed data
+  const link = result.value.find("link");
+  const linkData: LinkData | undefined = link?.data();
+  console.log(linkData?.url);
+}
+```
+
+---
+
+## Project Status
+
+- **Experimental** - APIs may change
+
+---
+
+## Non-Goals
+
+- Not a Markdown renderer/serializer
+- Not a Markdown editor
+- Not a full MDX parser
+
+---
+
+## Documentation
+
+- See `@origints/core` for Origins concepts
+- See [remark](https://github.com/remarkjs/remark) for underlying parser
+
+---
+
+## Contributing
+
+- Open an issue before large changes
+- Keep PRs focused
+- Tests required for new features
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@origints/markdown",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Markdown parsing and manipulation for Origins with full lineage tracking",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -13,6 +13,13 @@
       "require": "./dist/index.cjs"
     }
   },
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint src"
+  },
   "dependencies": {
     "unified": "^11.0.0",
     "remark-parse": "^11.0.0",
@@ -29,6 +36,8 @@
     "@origints/core": "^0.1.0"
   },
   "devDependencies": {
+    "@origints/core": "workspace:*",
+    "@origints/yaml": "workspace:*",
     "@types/mdast": "^4.0.0",
     "@types/node": "^25.0.0",
     "@vitest/coverage-v8": "^4.0.0",
@@ -36,9 +45,7 @@
     "typescript": "^5.9.0",
     "vite": "^7.0.0",
     "vite-plugin-dts": "^4.0.0",
-    "vitest": "^4.0.0",
-    "@origints/core": "0.1.0",
-    "@origints/yaml": "0.1.0"
+    "vitest": "^4.0.0"
   },
   "files": [
     "dist"
@@ -48,15 +55,8 @@
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/anthropics/origins.git",
+    "url": "https://github.com/fponticelli/origints.git",
     "directory": "packages/markdown"
   },
-  "license": "MIT",
-  "scripts": {
-    "build": "vite build",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "lint": "eslint src"
-  }
-}
+  "license": "MIT"
+}