open-index/open-npm huggingface dataset:
npm package: @siladev/qalam
Description: Islamic content editor with Quran verse references
Latest version: 0.4.2

# @siladev/qalam

Islamic content editor with Quran verse references, hadith, poetry, and inline quotes. Built on Tiptap/React, RTL-first.

## Install

```bash
bun add @siladev/qalam
```

## Editor

```tsx
import { QalamEditor } from "@siladev/qalam";
import "@siladev/qalam/styles.css";

// Load quran data first
import { loadQuranData } from "@siladev/qalam";
const data = await fetch("/quran-data.json").then(r => r.json());
loadQuranData(data);

function App() {
  const [doc, setDoc] = useState(initialContent);
  return (
    <QalamEditor
      content={doc}        // initial content (remount with key to replace)
      onChange={setDoc}
      repeat={true}         // enable repeat controls
      dir="rtl"
    />
  );
}
```

## Renderer

```tsx
import { QalamRenderer, resolveAST } from "@siladev/qalam";

const resolved = resolveAST(doc); // needs quran data loaded
<QalamRenderer doc={resolved} dir="rtl" />
```

## Markdown

Bidirectional JSON <-> Markdown conversion.

```typescript
import { docToMarkdown, markdownToDoc, resolvedDocToMarkdown, markdownToResolvedDoc } from "@siladev/qalam";

// Source markdown (for editing, LLM pipelines)
const md = docToMarkdown(doc);
const doc = markdownToDoc(md);

// Resolved markdown (for rendering without quran data)
const compiledMd = resolvedDocToMarkdown(resolvedDoc);
const resolvedDoc = markdownToResolvedDoc(compiledMd);
```

### Markdown Syntax

#### Inline nodes

```markdown
:quran[2:البَقَرَة:255]
:quran[2:البَقَرَة:255]{basmalah nocite}
:quran[2:البَقَرَة:255:3-7x3,256]{basmalah}

:hadith[narration ^^prophetic speech^^ text]{cite="البخاري" grade="صحيح"}

:quote[quoted text]{cite="المصدر"}
```

#### Marks

```markdown
**bold**  *italic*  [link](url)
^^prophetic speech^^
{x3:repeated text}
```

#### Blocks

```markdown
# Heading 1
## Heading 2
### Heading 3

Paragraph text {x3}

> Blockquote text
> {cite="المصدر" x=2}

- Bullet list
1. Ordered list
أ. Abjad list

:::poem{cite="الشاعر"}
صدر | عجز
صدر | عجز {x3}
***
صدر | شطر ثاني | شطر ثالث
:::
```

### Escaping

- `\]` inside `:name[content]` — literal `]`
- `\"` inside `{key="value"}` — literal `"`
- `\{` at start of blockquote line — literal, not metadata

### Known Limitations

- `^^` inside propheticSpeech mark content is not safe
- `}` inside inline-repeat mark content is not safe
- `\]` in directive content loses the backslash
- Blockquote line exactly matching `{key="value"}` is consumed as metadata

These do not affect Arabic Islamic content.

## Schema Types

```typescript
import type { QalamDoc, QalamDocResolved, QalamBlock, QalamInline } from "@siladev/qalam";
```

## Standalone Markdown Manager

```typescript
import { createMarkdownManager } from "@siladev/qalam";

const manager = createMarkdownManager();
const json = manager.parse(markdown);
const md = manager.serialize(json);
```