Repository guide · getting started · v2
microsoft / markitdown · Getting started
A Python repository whose platform description calls it a file-to-Markdown converter. It is MIT-licensed and split into four packages, each with a pyproject.toml dependency record set. One listed non-test __main__ guard (markitdown-mcp) calls main(); the other listed guards run tests. This analysis does not verify install or run commands.
- Original repository
- microsoft/markitdown
- License
- MIT · open-source license
- Analyzed revision · last verified
- ed178952a6672abdfd35b5f9e76a80b6cefc086e ·
Getting started with microsoft/markitdown: manifests and entrypoints
Terms used on this page
- Entrypoint record
- A file the analyzer marks as a place where execution can start. When it carries a __main__ guard excerpt, the file contains an if __name__ == "__main__": block and the excerpt shows what that block calls; without an excerpt, the file was flagged by its name only.
- Bounded static execution path
- A call chain reconstructed from the source code without running it, stopped after a fixed number of steps. It shows how far the code can be followed on paper, not what happens at run time.
- Unresolved boundary
- Where a static path stops because the next call goes into an external library or cannot be resolved without running the code. It marks the edge of this analysis, not a defect in the repository.
- Static relations
- Calls and imports found in the source. "External or unresolved" relations point outside the analyzed files.
- Module role
- The analyzer's label for a file, inferred from how many calls go in and out (for example core, entry/orchestration, leaf). It describes a position in the call graph, not the authors' design.
- Test-like files
- Files whose names or locations look like tests. This analysis counts them; it does not run them.
- Observed · inferred · author-claimed · unresolved
- How each statement is supported: read directly from the analyzed files; derived by the analyzer from them; stated by the repository's authors (metadata, README); or not established by this analysis.
- Verified
- Two uses on these pages. In an analyzer record ("verified provenance", "a verified entrypoint") it means the record was read directly from the analyzed files, which these guides call observed; for an entrypoint, the __main__ guard text is present. Since the analyzer fix of 2026-10-04, a file that only has an entrypoint-like name such as cli.py or main.py is recorded as inferred; guides analyzed before that still call such a file verified, and it is still only a guess about how the file is used. It does not mean the code was run or tested. "Last verified" is the date the guide last passed the lab's checks against the analysis record of the stated revision; it is not a review of the repository itself.
What you are looking at
The repository's GitHub description presents it as a Python tool for converting files and office documents to Markdown. That is the project's own account, not something this analysis checked.
- Primary language: Python. Language byte counts are about 799 kB of Python and about 1.3 kB of Dockerfile.
- License: MIT, with a
LICENSEfile at the root. - Latest platform release: v0.1.9, published 2026-10-21.
- Stargazers at collection time: 195,516. This is a popularity figure, not a quality signal.
The analyzer counted 197 files, 112 of them test-like, and 4 manifest files. Its own summary reads the layout as a Python project organised around a packages/ directory, with tests.
What the project says about itself
The platform topic labels are autogen, autogen-extension, langchain, markdown, microsoft-office, openai and pdf. These labels are set on the repository and do not by themselves show which integrations exist in the code. The homepage field is empty.
README text reaches this analysis only through line-based extraction. Anything it says about scope or security therefore remains the project's own account.
What it needs
Dependency records come from four pyproject.toml files, one per package under packages/:
- markitdown: runtime
beautifulsoup4,requests,certifi(>=2026.10.19),markdownify,magika(>=0.6.1,<2),charset-normalizer,defusedxml. Optional:python-pptx,mammoth,pandas,openpyxl,xlrd,lxml,pdfminer.six,pdfplumber,olefile,pydub,SpeechRecognition,youtube-transcript-apiand threeazure-*packages. - markitdown-mcp: runtime
mcp(>=2.1.1,<3.0.0) andmarkitdown(>=0.1.9,<0.2.0). - markitdown-ocr: runtime
markitdown(>=0.1.9,<0.2.0),pdfminer.six,pdfplumber,PyMuPDF,mammoth,python-docx,python-pptx,pandas,openpyxl,Pillow. Optional:openai(>=1.0.0). - markitdown-sample-plugin: runtime
markitdown(>=0.1.0a1) andstriprtf.
The optional names in the markitdown manifest are recorded more than once. Which optional groups they belong to is not established. Version constraints are recorded as written. setup.py, setup.cfg, Pipfile and lock files are not parsed.
How it starts
packages/markitdown-mcp/src/markitdown_mcp/__main__.py carries a __main__ guard whose body calls main().
Every other listed guard is in a test file under a package's tests/ directory. Most of them pass the file to pytest.main. A few call test functions directly or import test vectors. The analyzer reports 24 entrypoint records in total, and 20 are listed here.
packages/markitdown/src/markitdown/__main__.py is flagged as a likely entrypoint, but no guard record for it is listed, so how it starts is not established.
The analyzer reports 155 bounded execution paths; 5 are listed, all from the markitdown-mcp __main__.py. Three go through the local main and stop at the unresolved boundaries argparse.ArgumentParser and parser.add_argument. Two stop at logging.getLogger and MCPServer from module level, without passing through main.
Runtime behaviour beyond these records is not established. That includes the available command-line options, what the server does and how conversions actually run.
Where to look first
The analyzer marks README.md and LICENSE as project-level important files. It marks five more as likely entrypoints: the markitdown-mcp and markitdown __main__.py files, plus test_stdio_protocols.py, test_sample_plugin.py and test_cli_misc.py.
Its learning-path claim suggests this order: start with manifests and important symbols, trace the bounded execution path, then inspect unresolved boundaries before changing code.
Its modify-guide claim points to packages/markitdown/tests/test_cli_vectors.py as the place to begin and asks for downstream effects to be checked manually. That file is a test file, not library source.
Top-level layout: packages/ holds 181 of the 197 files. The root holds 10, .github 5 and .devcontainer 1.
Tests exist. The analyzer counts 112 test-like files. The entrypoint records show test directories in the markitdown, markitdown-mcp and markitdown-sample-plugin packages.
What this analysis cannot tell you
- Installation, build and run commands are not verified.
- Dependency parsing covers requirements files, package.json and pyproject.toml tables. setup.py, setup.cfg, Pipfile and lock files are not parsed.
- README content is extracted line by line and remains author-claimed.
- The analysis is static and bounded. Reflection, dynamic imports, framework wiring and dynamic dispatch are not resolved. Very large, minified or vendored files are inventoried but not parsed.
The packet also contains two inconsistencies:
- One analyzer teaching claim says no bounded execution path is available, yet 155 paths are reported and five are listed.
- The analyzer's summary names the markitdown-mcp
__main__.pyas the main starting place, while another teaching claim namespackages/markitdown/tests/test_cli_vectors.py.
What this analysis could not establish
The writing model's own notes on the analysis record. Identifiers such as lim_3, exec_* or claim_… name records of that analysis; the claims table cites the same records.
- The analyzer's limitation record for this run states that PEP 621 dependencies and optional dependencies in pyproject.toml are parsed; this asset follows that record.
- Optional dependency records for packages/markitdown/pyproject.toml repeat names at identical lines (for example pandas three times and azure-identity three times); the optional group names are not in the packet.
- No Python version requirement appears in any dependency record, so the supported Python version is not established.
- The inventory and language statistics include Dockerfile content, but no dependency records come from Dockerfiles and their contents are not described in the packet.
- 4 of the 24 entrypoint records are not listed; whether packages/markitdown/src/markitdown/__main__.py has a guard, and what it calls, is not established.
- The analyzer reports 5812 static relations that remain external or unresolved.
- The test sample includes .docx data files under markitdown-ocr test data, so the 112 test-like file count likely includes fixtures, not only test code.
- Whether any of these packages is published on a package registry, or exposes a documented command-line interface, is not established by the packet.
Claims and evidence — 36 claims, 36 supported by an independent verifier
Every substantive statement above is a claim bound to grounding IDs of the analyzed revision. Global grounding IDs are namespaced by the analysis run.
| Claim | Epistemic status | Verifier | Grounding (global IDs) |
|---|---|---|---|
| c1 The repository's platform description presents it as a Python tool for converting files and office documents to Markdown; this is the project's own account and was not checked by this analysis. | author_claimed | supported | analysis_5d9c9ae9a129bff5:meta_description |
| c2 Platform metadata gives Python as the primary language; language byte counts are 798912 bytes of Python and 1267 bytes of Dockerfile. | observed | supported | analysis_5d9c9ae9a129bff5:meta_primary_language, analysis_5d9c9ae9a129bff5:meta_language_bytes |
| c3 The license is recorded as MIT, and LICENSE is a project-level important file at the repository root. | observed | supported | analysis_5d9c9ae9a129bff5:meta_license, analysis_5d9c9ae9a129bff5:important_2 |
| c4 The latest platform release is v0.1.9, published 2026-10-21. | observed | supported | analysis_5d9c9ae9a129bff5:meta_latest_release |
| c5 Platform metadata records 195516 stargazers at collection time; this is a popularity count, not a quality signal. | observed | supported | analysis_5d9c9ae9a129bff5:meta_stars |
| c6 The analyzer counts 197 files, 112 test-like files and 4 manifest files, and its summary reads the repository as a Python project organised around packages, with tests. | inferred | supported | analysis_5d9c9ae9a129bff5:summary_repository |
| c7 The repository's topic labels are autogen, autogen-extension, langchain, markdown, microsoft-office, openai and pdf; these labels do not by themselves show which integrations exist in code. | author_claimed | supported | analysis_5d9c9ae9a129bff5:meta_topics |
| c8 The platform homepage field for the repository is empty. | author_claimed | supported | analysis_5d9c9ae9a129bff5:meta_homepage |
| c9 README claim extraction is line-based and every README claim remains author-claimed at best. | observed | supported | analysis_5d9c9ae9a129bff5:lim_4a |
| c10 Dependency records come from four pyproject.toml files: packages/markitdown, packages/markitdown-mcp, packages/markitdown-ocr and packages/markitdown-sample-plugin. | observed | supported | analysis_5d9c9ae9a129bff5:dep_1, analysis_5d9c9ae9a129bff5:dep_3, analysis_5d9c9ae9a129bff5:dep_14, analysis_5d9c9ae9a129bff5:dep_16 |
| c11 The markitdown manifest lists runtime dependencies beautifulsoup4, requests, certifi (>=2026.10.19), markdownify, magika (>=0.6.1,<2), charset-normalizer and defusedxml. | observed | supported | analysis_5d9c9ae9a129bff5:dep_16, analysis_5d9c9ae9a129bff5:dep_17, analysis_5d9c9ae9a129bff5:dep_18, analysis_5d9c9ae9a129bff5:dep_19, analysis_5d9c9ae9a129bff5:dep_20, analysis_5d9c9ae9a129bff5:dep_21, analysis_5d9c9ae9a129bff5:dep_22 |
| c12 The markitdown manifest lists optional dependencies python-pptx, mammoth, pandas, openpyxl, xlrd, lxml, pdfminer.six, pdfplumber, olefile, pydub, SpeechRecognition, youtube-transcript-api, azure-ai-documentintelligence, azure-ai-contentunderstanding and azure-identity. | observed | supported | analysis_5d9c9ae9a129bff5:dep_23, analysis_5d9c9ae9a129bff5:dep_24, analysis_5d9c9ae9a129bff5:dep_25, analysis_5d9c9ae9a129bff5:dep_26, analysis_5d9c9ae9a129bff5:dep_27, analysis_5d9c9ae9a129bff5:dep_28, analysis_5d9c9ae9a129bff5:dep_29, analysis_5d9c9ae9a129bff5:dep_30, analysis_5d9c9ae9a129bff5:dep_31, analysis_5d9c9ae9a129bff5:dep_32, analysis_5d9c9ae9a129bff5:dep_33, analysis_5d9c9ae9a129bff5:dep_34, analysis_5d9c9ae9a129bff5:dep_35, analysis_5d9c9ae9a129bff5:dep_36, analysis_5d9c9ae9a129bff5:dep_37 |
| c13 The markitdown-mcp manifest lists runtime dependencies mcp (>=2.1.1,<3.0.0) and markitdown (>=0.1.9,<0.2.0). | observed | supported | analysis_5d9c9ae9a129bff5:dep_1, analysis_5d9c9ae9a129bff5:dep_2 |
| c14 The markitdown-ocr manifest lists runtime markitdown (>=0.1.9,<0.2.0), pdfminer.six, pdfplumber, PyMuPDF, mammoth, python-docx, python-pptx, pandas, openpyxl and Pillow, plus optional openai (>=1.0.0). | observed | supported | analysis_5d9c9ae9a129bff5:dep_3, analysis_5d9c9ae9a129bff5:dep_4, analysis_5d9c9ae9a129bff5:dep_5, analysis_5d9c9ae9a129bff5:dep_6, analysis_5d9c9ae9a129bff5:dep_7, analysis_5d9c9ae9a129bff5:dep_8, analysis_5d9c9ae9a129bff5:dep_9, analysis_5d9c9ae9a129bff5:dep_10, analysis_5d9c9ae9a129bff5:dep_11, analysis_5d9c9ae9a129bff5:dep_12, analysis_5d9c9ae9a129bff5:dep_13 |
| c15 The markitdown-sample-plugin manifest lists runtime dependencies markitdown (>=0.1.0a1) and striprtf. | observed | supported | analysis_5d9c9ae9a129bff5:dep_14, analysis_5d9c9ae9a129bff5:dep_15 |
| c16 Optional dependency names in the markitdown manifest are recorded more than once at the same lines; which optional groups they belong to is not established by the packet. | unresolved | supported | analysis_5d9c9ae9a129bff5:dep_38, analysis_5d9c9ae9a129bff5:dep_39, analysis_5d9c9ae9a129bff5:dep_40, analysis_5d9c9ae9a129bff5:dep_41, analysis_5d9c9ae9a129bff5:dep_42, analysis_5d9c9ae9a129bff5:dep_43, analysis_5d9c9ae9a129bff5:dep_44, analysis_5d9c9ae9a129bff5:dep_45, analysis_5d9c9ae9a129bff5:dep_46, analysis_5d9c9ae9a129bff5:dep_47, analysis_5d9c9ae9a129bff5:dep_48, analysis_5d9c9ae9a129bff5:dep_49, analysis_5d9c9ae9a129bff5:dep_50, analysis_5d9c9ae9a129bff5:dep_51, analysis_5d9c9ae9a129bff5:dep_52, analysis_5d9c9ae9a129bff5:dep_53, analysis_5d9c9ae9a129bff5:dep_54 |
| c17 Version constraints are recorded as written; setup.py, setup.cfg, Pipfile and lock files are not parsed. | observed | supported | analysis_5d9c9ae9a129bff5:lim_3a |
| c18 packages/markitdown-mcp/src/markitdown_mcp/__main__.py has a __main__ guard whose body calls main(). | observed | supported | analysis_5d9c9ae9a129bff5:py_entry_2f852a8015d4 |
| c19 Every other listed __main__ guard sits in a test file under a package tests directory; most pass the file to pytest.main, while test_sample_plugin.py, test_cli_vectors.py and test_module_vectors.py call test functions or import test vectors. | observed | supported | analysis_5d9c9ae9a129bff5:py_entry_1fa8ac31a8f1, analysis_5d9c9ae9a129bff5:py_entry_a63fdf323f3b, analysis_5d9c9ae9a129bff5:py_entry_f44307e3b0be, analysis_5d9c9ae9a129bff5:py_entry_007b88c947c9, analysis_5d9c9ae9a129bff5:py_entry_48d5677c0b8c, analysis_5d9c9ae9a129bff5:py_entry_6da5faf654d3, analysis_5d9c9ae9a129bff5:py_entry_e1644548438f, analysis_5d9c9ae9a129bff5:py_entry_fd2581a2a85a, analysis_5d9c9ae9a129bff5:py_entry_c1e9a0696ede, analysis_5d9c9ae9a129bff5:py_entry_4001ed8b5544, analysis_5d9c9ae9a129bff5:py_entry_2eddfb03d1cb, analysis_5d9c9ae9a129bff5:py_entry_791d98438517, analysis_5d9c9ae9a129bff5:py_entry_3c032b18438d, analysis_5d9c9ae9a129bff5:py_entry_32796e5c789a, analysis_5d9c9ae9a129bff5:py_entry_d48046c8aa24, analysis_5d9c9ae9a129bff5:py_entry_f19b18e9138b, analysis_5d9c9ae9a129bff5:py_entry_de1243d2bd26, analysis_5d9c9ae9a129bff5:py_entry_fc521ad126e1, analysis_5d9c9ae9a129bff5:py_entry_1f6c94e0f30f |
| c20 The analyzer reports 24 entrypoint records in total; 20 are listed here, so statements about guards are scoped to the listed records. | inferred | supported | analysis_5d9c9ae9a129bff5:architecture_reconstruction |
| c21 packages/markitdown/src/markitdown/__main__.py is flagged as important because it is likely an entrypoint, but no guard record for it is listed, so how it starts is not established. | unresolved | supported | analysis_5d9c9ae9a129bff5:important_6 |
| c22 The analyzer reports 155 bounded execution paths; 5 are listed, all from the markitdown-mcp __main__.py. Three reach the local main and stop at argparse.ArgumentParser or parser.add_argument; two stop directly at logging.getLogger and MCPServer from module level. | inferred | supported | analysis_5d9c9ae9a129bff5:summary_repository, analysis_5d9c9ae9a129bff5:exec_67998e701fae, analysis_5d9c9ae9a129bff5:exec_b68e1f5a7c8a, analysis_5d9c9ae9a129bff5:exec_11e5ff5e359f, analysis_5d9c9ae9a129bff5:exec_51ee1388edd7, analysis_5d9c9ae9a129bff5:exec_b64608cd49a8 |
| c23 Runtime behaviour beyond these records, such as available command-line options, what the server does or how conversions run, is not established by this static analysis. | unresolved | supported | analysis_5d9c9ae9a129bff5:lim_1, analysis_5d9c9ae9a129bff5:lim_2 |
| c24 README.md and LICENSE are classified as project-level important files. | observed | supported | analysis_5d9c9ae9a129bff5:important_1, analysis_5d9c9ae9a129bff5:important_2 |
| c25 Five files are classified as important because they are likely entrypoints: the markitdown-mcp and markitdown __main__.py files, test_stdio_protocols.py, test_sample_plugin.py and test_cli_misc.py. | observed | supported | analysis_5d9c9ae9a129bff5:important_3, analysis_5d9c9ae9a129bff5:important_4, analysis_5d9c9ae9a129bff5:important_5, analysis_5d9c9ae9a129bff5:important_6, analysis_5d9c9ae9a129bff5:important_7 |
| c26 The analyzer's learning-path claim suggests starting with manifests and important symbols, then tracing the bounded execution path and inspecting unresolved boundaries before changing code. | inferred | supported | analysis_5d9c9ae9a129bff5:claim_e56db45165bf |
| c27 The analyzer's modify-guide claim points to packages/markitdown/tests/test_cli_vectors.py as the place to begin and asks for manual checking of downstream effects; that file is a test file, not library source. | inferred | supported | analysis_5d9c9ae9a129bff5:claim_cb8d18fd5293, analysis_5d9c9ae9a129bff5:py_entry_007b88c947c9 |
| c28 Top-level layout: packages/ holds 181 of 197 files, the root 10, .github 5 and .devcontainer 1. | inferred | supported | analysis_5d9c9ae9a129bff5:summary_repository |
| c29 The analyzer counts 112 test-like files in the repository. | inferred | supported | analysis_5d9c9ae9a129bff5:summary_repository |
| c30 Entrypoint records show test directories in the markitdown, markitdown-mcp and markitdown-sample-plugin packages. | observed | supported | analysis_5d9c9ae9a129bff5:py_entry_1fa8ac31a8f1, analysis_5d9c9ae9a129bff5:py_entry_a63fdf323f3b, analysis_5d9c9ae9a129bff5:py_entry_f44307e3b0be |
| c31 Install, run and build inference is partial, and installation commands are not verified by this analysis. | observed | supported | analysis_5d9c9ae9a129bff5:lim_2 |
| c32 Dependency records come from requirements files, package.json and pyproject.toml tables; setup.py, setup.cfg, Pipfile and lock files are not parsed. | observed | supported | analysis_5d9c9ae9a129bff5:lim_3a |
| c33 README content is extracted line by line and stays author-claimed. | observed | supported | analysis_5d9c9ae9a129bff5:lim_4a |
| c34 The analysis is static and bounded: reflection, dynamic imports, framework wiring and dynamic dispatch are not resolved, and files over 400 kB, minified bundles and vendored directories are inventoried but not parsed. | observed | supported | analysis_5d9c9ae9a129bff5:lim_1, analysis_5d9c9ae9a129bff5:lim_6 |
| c35 One analyzer teaching claim says no bounded execution path is available, yet the analyzer reports 155 bounded paths and five are listed. | inferred | supported | analysis_5d9c9ae9a129bff5:claim_4d30ade3e21e, analysis_5d9c9ae9a129bff5:summary_repository, analysis_5d9c9ae9a129bff5:exec_67998e701fae |
| c36 The analyzer's summary names the markitdown-mcp __main__.py as the main starting place, while another teaching claim names packages/markitdown/tests/test_cli_vectors.py as a detected starting point. | inferred | supported | analysis_5d9c9ae9a129bff5:summary_repository, analysis_5d9c9ae9a129bff5:claim_34d2322830c1 |
Sources, rights and disclosure · attribution-license-templates/v0.1
Rights notice. Original repository hosted on GitHub. Repository source code, documentation, names, media, and related project materials remain subject to the rights of their respective authors, contributors, and other rights holders and to applicable repository license terms.
Platform notice. GitHub is the source hosting platform for the linked repository. GitHub and related marks are trademarks of GitHub, Inc. EVEMISS Technology is not affiliated with or endorsed by GitHub unless explicitly stated otherwise.
How this page is produced. This page was produced using revision-aware repository analysis and AI-assisted editorial tooling. Technical claims are tied to the analyzed repository revision and may be revalidated when the source repository changes.
AI-assisted analysis. Reviewed by EVEMISS Technology through human–AI collaborative review. · Report a rights concern · Back to the overview