TextNLPClassifierApp/specs/005-convert-json-markdown/quickstart.md

Quickstart: Convert Article JSON to Markdown

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

1. Prerequisites & Setup

Ensure the environment has dependencies installed:

pip install -r requirements.txt

Verify that markdownify is installed:

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:

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:

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

pytest tests/test_convert_article_to_markdown.py -v

Run Linter & Type Checker

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