Workflow guide

Convert documents to Markdown for RAG ingestion

Retrieval-augmented generation works better when source material is readable, traceable, and split at meaningful boundaries. Markdown is a useful interchange format because its headings, lists, links, and tables remain visible as plain text. Conversion is only the extraction stage: To-Markdown does not chunk documents, create embeddings, or operate a vector database.

Last updated: August 12, 2026
Test environment: To-Markdown web converter and API; Firecrawl AnyDoc for Word and PowerPoint; youtube-transcript-api 1.2.4 for public YouTube transcripts

1. Choose sources you are allowed to index

Start with documents your team owns or has permission to process. Remove duplicate exports, obsolete versions, and files that should not enter the retrieval system. Keep a source URL, file name, revision date, and access policy beside each item; Markdown alone does not preserve an authorization model.

Use the converter that matches the source. The Word page includes a tested DOCX sample with headings, a list, a link, and a table. The PowerPoint page includes a small two-slide sample and explains how positioned slide content becomes a linear outline. The Image page provides a reproducible OCR sample for screenshots and scans. Public YouTube videos work only when a transcript track is available.

Prefer the editable Word or PowerPoint source over a screenshot when both exist.
Keep the original file as the audit source; treat generated Markdown as a derivative.
Do not ingest secrets, personal data, or licensed material without an explicit policy.

2. Convert, then verify semantic boundaries

Upload one supported file of up to 10 MB, paste text, or submit a supported URL. After conversion, compare heading order, lists, link destinations, table cells, names, dates, and code with the source. These checks matter because downstream chunkers often use headings and blank lines as boundaries.

Visual meaning needs special attention. Slide position, chart relationships, Word comments, embedded images, and OCR layout do not always have direct Markdown equivalents. Add a short human-written explanation when a diagram or layout carries information that extracted text cannot express.

Resolve tracked changes and comments before converting a Word document.
Check the reading order of text boxes and tables in a converted deck.
Proofread OCR names, numbers, symbols, and table columns against the image.
For YouTube, confirm the selected transcript language and whether it is auto-generated.

3. Add provenance before chunking

Add stable metadata in your ingestion record rather than inventing facts inside the document body. Useful fields include a source identifier, canonical source URL, file revision, conversion date, content owner, and access group. If your pipeline reads YAML front matter, add it after conversion and validate it with the destination parser.

Chunk downstream, after review. A practical baseline is to split on meaningful headings, retain the heading path with every chunk, and overlap only enough text to preserve context. Tables, procedures, and code blocks should usually remain intact. There is no universal chunk size: evaluate retrieval on representative questions from your own users.

Store the unmodified converted Markdown for reproducibility.
Store normalized or chunked text as a separate artifact.
Record conversion and embedding versions so an index can be rebuilt.
Treat retrieved source text as untrusted input and defend against prompt injection.

Observed YouTube conversion snapshot

In an earlier August 12, 2026 observation, the source below exposed a manually created English transcript. A later production smoke test on the same date returned TRANSCRIPT_UNAVAILABLE, so this raw output excerpt is an historical snapshot rather than a currently reproducible external example. Source availability and outbound access can change at any time.

Observed source URL

https://www.youtube.com/watch?v=jNQXAC9IVRw

Observed Markdown

# YouTube Transcript

- **Video:** https://www.youtube.com/watch?v=jNQXAC9IVRw
- **Language:** English (`en`)

## Transcript

All right, so here we are, in front of the elephants ...

Next step: The output and failure contracts are reproducibly tested with mocked transcript tracks and upstream errors. For ingestion, add the video ID, transcript language, generated/manual flag, and retrieval permissions before chunking.

Review checklist

Complete these checks against the original source and the real destination before treating the Markdown as finished.

Check	Acceptance criterion
Source identity	Every chunk can be traced back to the original URL or file revision.
Heading path	The document outline is correct and travels with each downstream chunk.
Tables and code	Rows, columns, and fenced blocks are not split into misleading fragments.
Visual-only meaning	Important charts, slide layouts, and screenshots have reviewed descriptions.
Access control	Retrieval permissions are enforced outside the Markdown body.
Evaluation	Representative questions retrieve the correct source and expose citations.

Use a tested source converter

Word to Markdown Use the tested DOCX outline, link, list, and table example. PowerPoint to Markdown Review the tested slide-order example before indexing a deck. Image to Markdown Use OCR for visible screenshot or scan content, then proofread it. YouTube transcript to Markdown Extract a transcript track when a public video exposes one.

Related workflow guides

Import documents into Obsidian as Markdown Convert Word, PowerPoint, and images to Markdown for Obsidian, then review links, attachments, properties, and note structure before adding it to your vault. Prepare converted Markdown for GitHub documentation Turn Word or PowerPoint content into reviewed Markdown for GitHub, MkDocs, or Docusaurus, including links, assets, front matter, navigation, and build checks.