### Install Marklassian

Source: https://github.com/jamsinclair/marklassian/blob/main/README.md

Install the marklassian package using npm.

```bash
npm install marklassian
```

--------------------------------

### Convert Markdown to ADF using Atlassian Libraries

Source: https://github.com/jamsinclair/marklassian/blob/main/README.md

Use the official Atlassian libraries (@atlaskit/editor-json-transformer and @atlaskit/editor-markdown-transformer) for Markdown to ADF conversion. This approach requires installing additional dependencies and may be more suitable for complex requirements or strict ADF conformance.

```javascript
import { defaultSchema } from '@atlaskit/adf-schema';
import { JSONTransformer } from '@atlaskit/editor-json-transformer';
import { MarkdownTransformer } from '@atlaskit/editor-markdown-transformer';

const jsonTransformer = new JSONTransformer();
const markdownTransformer = new MarkdownTransformer(defaultSchema);

const markdownDocument = '';
const adfDocument = jsonTransformer.encode(markdownTransformer.parse(markdownDocument));
```

--------------------------------

### Convert GFM Task Lists to ADF Task Nodes

Source: https://context7.com/jamsinclair/marklassian/llms.txt

Converts GitHub-Flavoured Markdown task lists (e.g., `- [ ]` and `- [x]`) into ADF `taskList` and `taskItem` nodes. Each task item includes a `localId` and a `state` (DONE/TODO). Nested tasks are also supported. Mixed lists of regular and task items are converted to `bulletList`.

```typescript
import { markdownToAdf } from 'marklassian';

const markdown = `- [x] Completed task
- [ ] Incomplete task
  - [x] Nested completed
  - [ ] Nested incomplete`;

const adf = markdownToAdf(markdown);
console.log(JSON.stringify(adf, null, 2));
```

```typescript
// Mixed regular + task items → treated as a regular bulletList
const mixed = markdownToAdf(`- Regular item
- [ ] Task item
- Another regular`);
console.log(mixed.content[0]?.type); // "bulletList"
```

--------------------------------

### Embed Raw ADF Nodes in Markdown with `<adf>` Tags

Source: https://context7.com/jamsinclair/marklassian/llms.txt

Use `<adf>...</adf>` tags to embed raw ADF JSON nodes directly within Markdown. The content must be valid JSON representing a single ADF node or an array of nodes. Malformed JSON or missing 'type' properties will result in errors.

```typescript
import { markdownToAdf } from 'marklassian';

// Single ADF node (Confluence status macro)
const markdown = `# My page

<adf>
{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"status","parameters":{"macroParams":{"title":{"value":"Done"},"colour":{"value":"Green"}}}}}}
</adf>

More content after the macro.`;

const adf = markdownToAdf(markdown);
console.log(JSON.stringify(adf, null, 2));
/* Output:
{
  "version": 1,
  "type": "doc",
  "content": [
    { "type": "heading", "attrs": { "level": 1 }, "content": [{ "type": "text", "text": "My page" }] },
    {
      "type": "extension",
      "attrs": {
        "extensionType": "com.atlassian.confluence.macro.core",
        "extensionKey": "status",
        "parameters": { "macroParams": { "title": { "value": "Done" }, "colour": { "value": "Green" } } }
      }
    },
    { "type": "paragraph", "content": [{ "type": "text", "text": "More content after the macro." }] }
  ]
}
*/

// Array of ADF nodes interleaved with markdown
const multiNode = markdownToAdf(`A paragraph.\n\n<adf>\n[{"type":"rule"},{"type":"rule"}]
</adf>\n\nAnother paragraph.`);
console.log(multiNode.content.length);          // 4
console.log(multiNode.content.map(n => n.type)); // ["paragraph", "rule", "rule", "paragraph"]

// Error handling
try {
  markdownToAdf('<adf>\nnot valid json\n</adf>');
} catch (err) {
  console.error(err.message); // "Invalid JSON in <adf> tag: not valid json"
}

try {
  markdownToAdf('<adf>\n{"attrs":{"level":1}}\n</adf>');
} catch (err) {
  console.error(err.message); // 'ADF node must have a "type" string property'
}
```

--------------------------------

### Fenced Code Blocks

Source: https://context7.com/jamsinclair/marklassian/llms.txt

Demonstrates how fenced code blocks in Markdown are converted into ADF `codeBlock` nodes, preserving the language identifier.

```APIDOC
## Fenced Code Blocks

### Description
Fenced code blocks in Markdown are converted to ADF `codeBlock` nodes. The language identifier specified in the fence (e.g., `typescript`, `bash`) is stored in the `attrs.language` property of the ADF node. If no language is specified, it defaults to `"text"`.

### Parameters
- None

### Request Example
```typescript
import { markdownToAdf } from 'marklassian';

const markdown = `\
\
```typescript\nconst hello = \"world\";\nconsole.log(hello);\n\
\
```bash\necho \"Hello World\"\n\
\
```\nSome text\n\
\
```
`;

const adf = markdownToAdf(markdown);
console.log(JSON.stringify(adf, null, 2));
```

### Response Example
```json
{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "codeBlock",
      "attrs": { "language": "typescript" },
      "content": [{ "type": "text", "text": "const hello = \"world\";\nconsole.log(hello);" }]
    },
    {
      "type": "codeBlock",
      "attrs": { "language": "bash" },
      "content": [{ "type": "text", "text": "echo \"Hello World\"" }]
    },
    {
      "type": "codeBlock",
      "attrs": { "language": "text" },
      "content": [{ "type": "text", "text": "Some text" }]
    }
  ]
}
```
```

--------------------------------

### Convert Markdown to ADF

Source: https://github.com/jamsinclair/marklassian/blob/main/README.md

Import and use the markdownToAdf function to convert a Markdown string to an ADF document object. Ensure the markdown string is valid.

```javascript
import { markdownToAdf } from 'marklassian';

const markdown = '# Hello World';
const adf = markdownToAdf(markdown);
```

--------------------------------

### Convert Markdown Table to ADF Table

Source: https://context7.com/jamsinclair/marklassian/llms.txt

Converts a pipe-style Markdown table, including headers, content cells, images, and inline formatting, into an ADF table structure. Empty cells are automatically handled.

```typescript
import { markdownToAdf } from 'marklassian';

const markdown = `| **First Header** | Second Header |
| ------------- | ------------- |
| Content Cell  | ![Example Image](https://picsum.photos/400/300) Image with text in cell |
| ~~Content Cell~~  | Content Cell  |
| | |`;

const adf = markdownToAdf(markdown);
console.log(JSON.stringify(adf.content[0], null, 2));
```

--------------------------------

### Convert Markdown to ADF

Source: https://context7.com/jamsinclair/marklassian/llms.txt

Converts a Markdown string containing headings, emphasis, links, inline code, strikethrough, images, lists, and blockquotes into an ADF document object. Ensure the input Markdown is valid.

```typescript
import { markdownToAdf } from 'marklassian';

// --- Headings, emphasis, links, inline code, strikethrough, images, lists, blockquotes ---
const markdown = `# Hello World

This is a **bold** and *italic* text.

This is a [link](https://example.org).

This is 	inline code	

This is ~~striked~~ text

Below is an image
![Example Image](https://picsum.photos/400/300)

## Lists
- Item 1
- Item 2
  - Nested item

1. Ordered item 1
2. Ordered item 2

> This is a blockquote`;

const adf = markdownToAdf(markdown);
console.log(JSON.stringify(adf, null, 2));
/* Output:
{
  "version": 1,
  "type": "doc",
  "content": [
    { "type": "heading", "attrs": { "level": 1 }, "content": [{ "type": "text", "text": "Hello World" }] },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "This is a " },
        { "type": "text", "text": "bold", "marks": [{ "type": "strong" }] },
        { "type": "text", "text": " and " },
        { "type": "text", "text": "italic", "marks": [{ "type": "em" }] },
        { "type": "text", "text": " text." }
      ]
    },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "link", "marks": [{ "type": "link", "attrs": { "href": "https://example.org" } }] },
        ...
      ]
    },
    { "type": "mediaSingle", "attrs": { "layout": "center" }, "content": [{ "type": "media", "attrs": { "type": "external", "url": "https://picsum.photos/400/300", "alt": "Example Image" } }] },
    { "type": "bulletList", "content": [ ... ] },
    { "type": "orderedList", "attrs": { "order": 1 }, "content": [ ... ] },
    { "type": "blockquote", "content": [ ... ] }
  ]
}
*/
```

--------------------------------

### markdownToAdf

Source: https://github.com/jamsinclair/marklassian/blob/main/README.md

Converts a Markdown string to an ADF document object (JSON serialisable).

```APIDOC
## markdownToAdf(markdown: string): AdfDocument

### Description
Converts a Markdown string to an ADF document object (JSON serialisable).

### Parameters
#### Path Parameters
- **markdown** (string) - Required - The Markdown content to convert.

### Response
#### Success Response (AdfDocument)
- **AdfDocument** - The converted Atlassian Document Format object.

### Types
```typescript
type AdfNode = {
    type: string;
    attrs?: Record<string, any>;
    content?: AdfNode[];
    marks?: AdfMark[];
    text?: string;
};

type AdfMark = {
    type: string;
    attrs?: Record<string, any>;
};

type AdfDocument = {
    version: 1;
    type: 'doc';
    content: AdfNode[];
};
```
```

--------------------------------

### Convert Fenced Code Blocks to ADF

Source: https://context7.com/jamsinclair/marklassian/llms.txt

Converts fenced code blocks in Markdown to ADF `codeBlock` nodes, preserving the language identifier. If no language is specified, it defaults to 'text'.

```typescript
import { markdownToAdf } from 'marklassian';

const markdown = `\
\	\	\	typescript
const hello = "world";
console.log(hello);
\	\	\	

\	\	\	bash
echo "Hello World"
\	\	\	

\	\	\	
Some text
\	\	\		`;

const adf = markdownToAdf(markdown);
console.log(JSON.stringify(adf, null, 2));
/* Output:
{
  "version": 1,
  "type": "doc",
  "content": [
    {
      "type": "codeBlock",
      "attrs": { "language": "typescript" },
      "content": [{ "type": "text", "text": "const hello = \"world\";\nconsole.log(hello);" }]
    },
    {
      "type": "codeBlock",
      "attrs": { "language": "bash" },
      "content": [{ "type": "text", "text": "echo \"Hello World\"" }]
    },
    {
      "type": "codeBlock",
      "attrs": { "language": "text" },
      "content": [{ "type": "text", "text": "Some text" }]
    }
  ]
}
*/
```

--------------------------------

### markdownToAdf

Source: https://context7.com/jamsinclair/marklassian/llms.txt

The primary function of the Marklassian library. It accepts a Markdown string and returns a JSON-serialisable AdfDocument object. It handles various Markdown elements including headings, emphasis, links, images, lists, and blockquotes.

```APIDOC
## markdownToAdf(markdown: string): AdfDocument

### Description
Converts a Markdown string into an Atlassian Document Format (ADF) object. This function is synchronous and handles common Markdown syntax, mapping it to corresponding ADF nodes. It also supports raw ADF passthrough via `<adf>...</adf>` tags.

### Parameters
#### Path Parameters
- None

#### Query Parameters
- None

#### Request Body
- **markdown** (string) - Required - The Markdown string to convert.

### Request Example
```typescript
import { markdownToAdf } from 'marklassian';

const markdown = "# Hello World\n\nThis is a **bold** and *italic* text.";
const adf = markdownToAdf(markdown);
console.log(JSON.stringify(adf, null, 2));
```

### Response
#### Success Response (AdfDocument)
- **version** (number) - The ADF document version, typically 1.
- **type** (string) - The document type, always 'doc'.
- **content** (Array<AdfNode>) - An array of ADF nodes representing the document content.

#### Response Example
```json
{
  "version": 1,
  "type": "doc",
  "content": [
    { "type": "heading", "attrs": { "level": 1 }, "content": [{ "type": "text", "text": "Hello World" }] },
    {
      "type": "paragraph",
      "content": [
        { "type": "text", "text": "This is a " },
        { "type": "text", "text": "bold", "marks": [{ "type": "strong" }] },
        { "type": "text", "text": " and " },
        { "type": "text", "text": "italic", "marks": [{ "type": "em" }] },
        { "type": "text", "text": " text." }
      ]
    }
  ]
}
```

### Error Handling
- Throws a descriptive `Error` if an `<adf>` tag contains invalid or non-conforming JSON.
```

--------------------------------

### TypeScript Types for ADF Documents

Source: https://context7.com/jamsinclair/marklassian/llms.txt

Marklassian provides TypeScript definitions for `AdfDocument`, `AdfNode`, and `AdfMark`. These types can be used for type-checking ADF content generated by `markdownToAdf` before posting to Atlassian APIs.

```typescript
import { markdownToAdf } from 'marklassian';

type AdfMark = {
  type: string;
  attrs?: Record<string, any>;
};

type AdfNode = {
  type: string;
  attrs?: Record<string, any>;
  content?: AdfNode[];
  marks?: AdfMark[];
  text?: string;
};

type AdfDocument = {
  version: 1;
  type: 'doc';
  content: AdfNode[];
};

// The inferred return type is AdfDocument — no cast needed
const doc: AdfDocument = markdownToAdf('# Hello\n\nWorld');

// Post to Confluence REST API
async function createConfluencePage(spaceKey: string, title: string, markdownBody: string) {
  const adf = markdownToAdf(markdownBody);

  const response = await fetch('https://your-domain.atlassian.net/wiki/rest/api/content', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Basic ${btoa('user@example.com:API_TOKEN')}`,
    },
    body: JSON.stringify({
      type: 'page',
      title,
      space: { key: spaceKey },
      body: {
        atlas_doc_format: {
          value: JSON.stringify(adf),
          representation: 'atlas_doc_format',
        },
      },
    }),
  });

  if (!response.ok) throw new Error(`Confluence API error: ${response.statusText}`);
  return response.json();
}

// Post to Jira issue description
async function createJiraIssue(projectKey: string, summary: string, markdownDescription: string) {
  const adf = markdownToAdf(markdownDescription);

  const response = await fetch('https://your-domain.atlassian.net/rest/api/3/issue', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Basic ${btoa('user@example.com:API_TOKEN')}`,
    },
    body: JSON.stringify({
      fields: {
        project: { key: projectKey },
        summary,
        description: adf,
        issuetype: { name: 'Task' },
      },
    }),
  });

  if (!response.ok) throw new Error(`Jira API error: ${response.statusText}`);
  return response.json();
}
```

--------------------------------

### Embed Raw ADF Nodes in Markdown

Source: https://github.com/jamsinclair/marklassian/blob/main/README.md

Embed raw ADF nodes within `<adf>...</adf>` tags in your Markdown content. The content inside the tags must be a valid JSON object or array representing an ADF node. Ensure `<adf>` tags are block-level elements.

```markdown
# My page

<adf>
{"type":"extension","attrs":{"extensionType":"com.atlassian.confluence.macro.core","extensionKey":"status","parameters":{"macroParams":{"title":{"value":"Done"},"colour":{"value":"Green"}}}}}}
</adf>

More content here.
```

--------------------------------

### Define ADF Types

Source: https://github.com/jamsinclair/marklassian/blob/main/README.md

TypeScript type definitions for ADF nodes, marks, and documents. These types are useful for understanding the structure of ADF objects.

```typescript
type AdfNode = {
    type: string;
    attrs?: Record<string, any>;
    content?: AdfNode[];
    marks?: AdfMark[];
    text?: string;
};

type AdfMark = {
    type: string;
    attrs?: Record<string, any>;
};

type AdfDocument = {
    version: 1;
    type: 'doc';
    content: AdfNode[];
};
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.