# Quickstart: Convert Article JSON to Markdown

**Feature**: `005-convert-json-markdown` | **Date**: 2026-08-21

## 1. Prerequisites & Setup

Ensure the environment has dependencies installed:

```bash
pip install -r requirements.txt
```

Verify that `markdownify` is installed:

```bash
python -c "import markdownify; print(markdownify.__version__)"
```

---

## 2. Running the CLI Tool

### Basic Conversion (Default Output Path)

Convert a single article JSON to `<stem>.md` in the same directory:

```bash
python scripts/convert_article_to_markdown.py -i out/river_plate_extracted_selected_001.json
```

Output generated: `out/river_plate_extracted_selected_001.md`.

### Custom Destination Path

Specify an explicit output path:

```bash
python scripts/convert_article_to_markdown.py \
  -i out/river_plate_extracted_selected_001.json \
  -o out/markdown/river_plate_article_001.md
```

---

## 3. Verification & Testing

### Run All Unit & Integration Tests

```bash
pytest tests/test_convert_article_to_markdown.py -v
```

### Run Linter & Type Checker

```bash
ruff check scripts/convert_article_to_markdown.py src/ tests/
mypy scripts/convert_article_to_markdown.py
```