# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

**remove-markdown** is a Node.js module that strips Markdown formatting from text, leaving only plain text. It's designed for use cases like displaying excerpts without Markdown syntax.

The entire implementation is a single-file module (`index.js`) that exports one function which applies a series of regex replacements to remove various Markdown elements.

## Development Commands

### Running Tests
```bash
npm test
```
Runs the Mocha test suite with the spec reporter.

### Running a Single Test
To run a specific test, use Mocha's grep flag:
```bash
./node_modules/.bin/mocha -R spec test/remove-markdown.js --grep "test description pattern"
```

## Code Architecture

### Core Structure
- **index.js** (97 lines): Main module that exports a single function
  - Takes markdown text and an options object as parameters
  - Applies regex replacements in a specific order to strip Markdown syntax
  - Returns plain text or original input if error occurs (unless `throwError` option is set)

### Key Implementation Details

**Regex Application Order Matters**: The order of regex replacements is critical. For example, horizontal rules must be removed before list leaders to avoid conflicts (see index.js:15).

**Options System**: All options default to specific values if not provided. The module uses `options.hasOwnProperty()` checks rather than simple truthy checks to allow `false` values to be explicitly set.

**Error Handling**: The entire regex processing is wrapped in try-catch. By default, errors are logged and the original markdown is returned. Set `options.throwError: true` to propagate errors.

**HTML Tag Filtering**: The `htmlTagsToSkip` option dynamically builds a regex to preserve specific HTML tags while removing others (see index.js:41-49).

**Link Replacement**: Two mutually exclusive link handling modes:
- `replaceLinksWithURL: true` - replaces links with URLs (note: implementation at index.js:66 references `$2` which appears to be a bug as it should extract the URL)
- `separateLinksAndTexts` - replaces `[text](url)` with `text<separator>url` format (applied first at index.js:52)

### Test Structure
- **test/remove-markdown.js** (258 lines): Comprehensive test suite using Mocha and Chai
- Tests cover all markdown elements: headers, emphasis, lists, links, images, code blocks, blockquotes, HTML tags
- Includes performance tests to prevent ReDoS vulnerabilities
- Tests edge cases like emphasis with spaces, nested brackets, indentation

## Important Considerations

### When Adding Features
- New regex patterns must be carefully positioned in the replacement chain (index.js:18-89)
- Test edge cases thoroughly, especially patterns that could conflict with existing ones
- Consider performance implications - some patterns are vulnerable to ReDoS if not carefully written

### Known Quirks
- The `replaceLinksWithURL` option appears to have a bug where it references `$2` but the capturing group setup may not work as intended (index.js:66)
- Empty or invalid markdown input is handled gracefully by returning the original input
- The module preserves code block content (including newlines) while stripping the fencing

### Testing Strategy
When modifying regex patterns:
1. Run the full test suite first
2. Add specific test cases for your changes
3. Test performance with large inputs and repeated patterns
4. Verify your changes don't break the order-dependent behavior
