Get started

On this page

Folders
Quick start
Options
Settings

Folders

All service files live in the .raw2md folder in your home directory:

text

~/.raw2md/
  settings.json     # models and settings; created by raw2md init
  prompts.yaml      # prompts of the LLM stages; created by raw2md init
  keywords.yaml     # words that the cleaning rules look for; created by raw2md init
  models/           # weights of raw2md-engine; downloaded by raw2md init
  state/            # queue, lock, daily request counter
  logs/raw2md.log   # log of the last run
  tmp/              # temporary conversion files

The weights take about 3.3 GB. raw2md init downloads them from the raw2md-models repository on Hugging Face. Without init, the first PDF or DjVu conversion downloads the missing files. When all the weights are in place, the tool makes no network request for them.

Quick start

Give raw2md a file, a folder, or nothing at all:

bash

raw2md book.pdf   # a single file
raw2md scans      # every pdf, djvu, docx, and md file in the folder, without subfolders
raw2md            # the current folder

Each result lands next to its source:

text

book.pdf   # source
book.md    # result
book/      # images, if the document has any

notes.md            # Markdown source
notes_cleaned.md    # result; the source stays untouched

Every result starts with a header. The status field holds the verdict of the quality evaluation, and issues lists the checks that fired:

yaml

---
raw2md_version: 0.1.0
source: book.pdf
engine: raw2md-engine
inspection: none
post: none
converted_at: 2026-10-03
source_hash: 9rZ2...
status: ok
issues:
- headings
---

Options

These are the flags you will reach for most often:

Flag	What it does
`-o DIR`	puts the results into `DIR` instead of next to the source
`-e <model>`	recognizes PDF and DjVu with a model instead of `raw2md-engine`
`-i <model>`	turns on inspection, which checks the text against the source
`-p <model>`	turns on post-processing
`-s`	keeps a finished result and does not convert the file again
`-d`	saves the text after each stage into the `<name>.debug` folder
`-h`	prints the list of all flags
`--disable-image-extraction`	skips the images but keeps their captions

The model in -e, -i, and -p is a key from settings.json, such as gemini_api. The reference covers every flag, along with the resume, init, settings, prompts, and keywords commands.

Settings

Without a settings file, raw2md falls back on its built-in settings, which know two models:

Key	Model	Stages	What you need
`gemini_api`	Gemini through the API	`-e`, `-i`, `-p`	an API key in the `GOOGLE_API_KEY` variable
`claude_cli`	Claude Code through `claude -p`	`-p`	`claude` installed, signed in, and on `PATH`

To turn on the LLM stages, put your key into GOOGLE_API_KEY and name the model in the flag:

bash

raw2md book.pdf -i gemini_api -p gemini_api

The built-in gemini_api model and its limits, 15 requests per minute and 500 per day, target the free tier of Google AI Studio, so a free API key is enough to start. Google sets the actual quotas for each project and can change them. With a paid key, you can pick a larger model and raise the limits.

To change a model or its limits, create the settings file and open it:

bash

raw2md init
raw2md settings edit

These are the fields you are most likely to change:

Field	What it sets
`models.<key>.model`	the model name at the provider
`models.<key>.rpm`, `rpd`	the request limits per minute and per day
`models.<key>.pages_per_request`	how many source pages go into one request
`raw2md-engine.recognition_batch_size`	the batch size of the engine recognition; a smaller number uses less video memory

The reference describes every field, as well as prompts.yaml and keywords.yaml.