@principal-ade/argdown-parser

Server-side Argdown parsing utilities using @argdown/core.

Overview

This package provides utilities for parsing Argdown content on the server side. It wraps @argdown/core and exposes a simple API for processing Argdown text into structured data that can be consumed by visualization components.

Note: The parsing functions only work in Node.js environments. The @argdown/core library has dependencies (Chevrotain parser, etc.) that are not browser-compatible.

Installation

npm install @principal-ade/argdown-parser

Usage

Processing Argdown (Server-side only)

import { processArgdown } from '@principal-ade/argdown-parser';

const argdownSource = `
# Climate Debate

[Climate Change is Real]: Scientific consensus supports this.
  + <Scientific Evidence>: Multiple studies confirm warming trends.
  - <Skeptic View>: Natural cycles could explain changes.
`;

const result = await processArgdown(argdownSource);

// result.response contains:
// - arguments: Map of argument objects
// - statements: Map of statement objects
// - relations: Array of relations between nodes
// - ast: The abstract syntax tree

Importing Types Only (Browser-safe)

For browser/UI code that only needs the type definitions:

import type { ArgdownMapData, ArgdownResponse } from '@principal-ade/argdown-parser/types';

// Use these types to define props, etc.
interface MyComponentProps {
  data: ArgdownMapData;
}

Validating Argdown

import { validateArgdown } from '@principal-ade/argdown-parser';

const result = await validateArgdown(argdownSource);

if (result.valid) {
  console.log('Argdown syntax is valid');
} else {
  console.error('Errors:', result.errors);
}

Extracting Metadata

import { extractMetadata } from '@principal-ade/argdown-parser';

const metadata = extractMetadata(argdownSource);

// metadata contains:
// - title: First heading text
// - speakers: Array of speaker IDs from #speaker-* tags
// - tags: Array of all tags found

API

processArgdown(source, options?)

Parses Argdown source text and returns structured data.

• source: Raw Argdown text
• options: Optional request options
• Returns: Promise<ArgdownMapData>

validateArgdown(source)

Validates Argdown syntax.

• source: Raw Argdown text
• Returns: Promise<ArgdownValidationResult>

extractMetadata(source)

Extracts metadata without full parsing.

• source: Raw Argdown text
• Returns: ArgdownMetadata

Exports

Main export (@principal-ade/argdown-parser)

• processArgdown - Parse Argdown text (Node.js only)
• validateArgdown - Validate syntax (Node.js only)
• extractMetadata - Extract metadata (Node.js only)
• All types

Types-only export (@principal-ade/argdown-parser/types)

• ArgdownMapData - Output of parsing
• ArgdownResponse - Parsed response structure
• ArgdownArgument - Argument node
• ArgdownStatement - Statement node
• ArgdownRelation - Relation between nodes
• ArgdownMetadata - Extracted metadata
• ArgdownValidationResult - Validation result

Integration with argdown-renderer

This package is designed to work with @principal-ade/argdown-renderer:

// Server-side (API route, build script, etc.)
import { processArgdown } from '@principal-ade/argdown-parser';

const data = await processArgdown(argdownSource);
// Send `data` to the client as JSON

// Client-side (React component)
import { ArgdownRenderer } from '@principal-ade/argdown-renderer';

<ArgdownRenderer data={data} />

License

MIT