# Quick Start Guide

Get started with Marked in minutes.

## Installation

```bash
npm install marked
```

## Basic Usage

### Simple Parsing

```javascript { .api }
import { marked } from "marked";

const markdown = '# Hello World\n\nThis is **markdown**.';
const html = marked.parse(markdown);

console.log(html);
// Output: <h1>Hello World</h1>\n<p>This is <strong>markdown</strong>.</p>\n
```

### Inline Parsing

Parse inline markdown without wrapping `<p>` tags:

```javascript { .api }
import { marked } from "marked";

const inline = marked.parseInline('This is **bold** text');
console.log(inline);
// Output: This is <strong>bold</strong> text
```

**Use cases**: Tooltips, short descriptions, inline content

## Imports

### ES Modules (Recommended)

```javascript { .api }
import { marked } from "marked";
```

Specific imports:

```javascript { .api }
import {
  marked,           // Main parse function
  parse,            // Alias for marked
  parseInline,      // Parse inline markdown only
  Lexer,            // Tokenizer class
  Parser,           // Parser class
  Renderer,         // HTML renderer class
  Tokenizer,        // Low-level tokenizer class
  Hooks,            // Processing hooks class
  Marked            // Instance class for isolated configs
} from "marked";
```

### CommonJS

```javascript { .api }
const { marked } = require("marked");
```

### UMD (Browser)

```html
<script src="https://cdn.jsdelivr.net/npm/marked/lib/marked.umd.js"></script>
<script>
  const html = marked.parse('# Hello');
</script>
```

### TypeScript

```typescript { .api }
import { marked, MarkedOptions, Token, Tokens } from "marked";

const options: MarkedOptions = {
  gfm: true,
  breaks: true
};

marked.setOptions(options);
```

## Configuration

### Global Options

```javascript { .api }
import { marked } from "marked";

marked.setOptions({
  gfm: true,        // Enable GitHub Flavored Markdown
  breaks: true,     // Convert \n to <br>
  pedantic: false,  // Don't fix markdown bugs
  silent: false     // Throw on errors
});

const html = marked.parse(markdown);
```

### Per-Parse Options

```javascript { .api }
import { marked } from "marked";

// Override global options for specific parse
const html = marked.parse(markdown, {
  breaks: false,  // Override global setting
  gfm: true
});
```

### Isolated Instances

```javascript { .api }
import { Marked } from "marked";

// Create instance for GitHub Flavored Markdown
const gfmMarked = new Marked({
  gfm: true,
  breaks: true
});

// Create instance for strict CommonMark
const strictMarked = new Marked({
  gfm: false,
  pedantic: false
});

// Each instance has independent configuration
const html1 = gfmMarked.parse('Line 1\nLine 2'); // Has <br>
const html2 = strictMarked.parse('Line 1\nLine 2'); // No <br>
```

## Security

**Critical**: Marked does NOT sanitize HTML output.

```javascript { .api }
import { marked } from "marked";
import DOMPurify from "dompurify";

// UNSAFE - vulnerable to XSS
const unsafeHtml = marked.parse(userInput);

// SAFE - sanitized output
const dirty = marked.parse(userInput);
const clean = DOMPurify.sanitize(dirty);

// Use clean HTML in your application
document.getElementById('content').innerHTML = clean;
```

**Recommended sanitization libraries**:
- [DOMPurify](https://www.npmjs.com/package/dompurify) - Most comprehensive
- [sanitize-html](https://www.npmjs.com/package/sanitize-html) - Configurable
- [js-xss](https://www.npmjs.com/package/xss) - Lightweight

## Error Handling

### Throw Errors (Default)

```javascript { .api }
import { marked } from "marked";

try {
  const html = marked.parse(malformedMarkdown);
} catch (err) {
  console.error('Parse error:', err.message);
}
```

### Silent Mode

```javascript { .api }
import { marked } from "marked";

marked.setOptions({ silent: true });
const html = marked.parse(malformedMarkdown);
// Returns: <p>An error occurred:</p><pre>Error message</pre>
```

**Use silent mode for**: User-generated content, preview functionality

## Common Options

### GitHub Flavored Markdown

```javascript { .api }
import { marked } from "marked";

marked.setOptions({
  gfm: true,
  breaks: true
});

const html = marked.parse(`
# Title

Line 1
Line 2

| A | B |
|---|---|
| 1 | 2 |

~~strikethrough~~

- [ ] Task 1
- [x] Task 2
`);
```

### Strict CommonMark

```javascript { .api }
import { marked } from "marked";

marked.setOptions({
  gfm: false,
  breaks: false,
  pedantic: false
});
```

### Original markdown.pl Compatibility

```javascript { .api }
import { marked } from "marked";

marked.setOptions({
  pedantic: true,
  gfm: false
});
```

## Async Parsing

```javascript { .api }
import { marked } from "marked";

// Enable async mode
marked.setOptions({ async: true });

const html = await marked.parse('# Async Markdown');

// Or pass async option directly
const html2 = await marked.parse('# Title', { async: true });
```

**When to use async**: Required for async `walkTokens` callbacks, async hooks, or extensions that perform async operations.

## CLI Usage

```bash
# Install globally
npm install -g marked

# Parse file
marked input.md -o output.html

# Parse with options
marked input.md --gfm --breaks

# From stdin
echo "# Hello" | marked

# Multiple files
marked file1.md file2.md --output-dir dist/
```

## Next Steps

- [Extensions Guide](./extensions.md) - Add custom syntax and rendering
- [Rendering Guide](./rendering.md) - Customize HTML output
- [Token Manipulation](./token-manipulation.md) - Work with token trees
- [Real-World Examples](../examples/real-world-scenarios.md) - Complete usage examples
- [API Reference](../reference/api.md) - Complete API documentation

## Common Patterns

### Document Parsing

```javascript { .api }
import { marked } from "marked";
import fs from "fs";

const markdown = fs.readFileSync('README.md', 'utf-8');
const html = marked.parse(markdown, { gfm: true });
fs.writeFileSync('README.html', html);
```

### User Comments

```javascript { .api }
import { marked } from "marked";
import DOMPurify from "dompurify";

function renderComment(userComment) {
  const html = marked.parse(userComment);
  return DOMPurify.sanitize(html);
}
```

### Blog Posts

```javascript { .api }
import { marked } from "marked";

marked.setOptions({
  gfm: true,
  breaks: false
});

const postHtml = marked.parse(blogPost);
```

### Tooltips and Short Text

```javascript { .api }
import { marked } from "marked";

const tooltipHtml = marked.parseInline('This is **important**');
// Use parseInline for short content without <p> wrapper
```

## Edge Cases

### Empty Input

```javascript { .api }
marked.parse('');              // Returns: ''
marked.parse(null);            // Throws: TypeError
marked.parse(undefined);       // Throws: TypeError
```

### Large Input

```javascript { .api }
// Very large inputs (>10MB) may have performance implications
const largeMarkdown = '...'; // 10MB+

console.time('parse');
const html = marked.parse(largeMarkdown);
console.timeEnd('parse');
// Typical: < 1 second for 10MB
```

## Troubleshooting

See [Troubleshooting Guide](./troubleshooting.md) for common issues and solutions.
