From 68272b987a1d5f3cf54f12a2e8615c6c27e5449b Mon Sep 17 00:00:00 2001
From: Panos Vagenas <35837085+vagenas@users.noreply.github.com>
Date: Mon, 27 Jan 2025 17:23:39 +0100
Subject: [PATCH] docs: document Docling JSON parsing

Also:
- factored out and expanded supported formats
- reorged feature list

Signed-off-by: Panos Vagenas <35837085+vagenas@users.noreply.github.com>
---
 README.md                 | 16 +++++++++++-----
 docs/index.md             | 16 +++++++++++-----
 docs/supported_formats.md | 33 +++++++++++++++++++++++++++++++++
 docs/usage.md             | 14 --------------
 mkdocs.yml                |  3 ++-
 5 files changed, 57 insertions(+), 25 deletions(-)
 create mode 100644 docs/supported_formats.md

diff --git a/README.md b/README.md
index 78acb5929..dbbbba455 100644
--- a/README.md
+++ b/README.md
@@ -26,11 +26,13 @@ Docling parses documents and exports them to the desired format with ease and sp
 
 ## Features
 
-* ๐Ÿ—‚๏ธ Reads popular document formats (PDF, DOCX, PPTX, XLSX, Images, HTML, AsciiDoc & Markdown) and exports to HTML, Markdown and JSON (with embedded and referenced images)
-* ๐Ÿ“‘ Advanced PDF document understanding including page layout, reading order & table structures
-* ๐Ÿงฉ Unified, expressive [DoclingDocument](https://ds4sd.github.io/docling/concepts/docling_document/) representation format
-* ๐Ÿค– Plug-and-play [integrations](https://ds4sd.github.io/docling/integrations/) incl. LangChain, LlamaIndex, Crew AI & Haystack for agentic AI
-* ๐Ÿ” OCR support for scanned PDFs
+* ๐Ÿ—‚๏ธ Parsing of [multiple documents formats][supported_formats] incl. PDF, DOCX, XLSX, HTML, images, & more
+* ๐Ÿ“‘ Advanced PDF understanding including page layout, reading order & table structure
+* ๐Ÿงฌ Unified, expressive [DoclingDocument][docling_document] representation format
+* โ†ช๏ธ Various [export formats][supported_formats] and options, including Markdown, HTML, and lossless JSON
+* ๐Ÿ”’ Local execution capabilities for sensitive data and air-gapped environments
+* ๐Ÿค– Plug-and-play [integrations][integrations] incl. LangChain, LlamaIndex, Crew AI & Haystack for agentic AI
+* ๐Ÿ” OCR support for scanned PDFs and images
 * ๐Ÿ’ป Simple and convenient CLI
 
 Explore the [documentation](https://ds4sd.github.io/docling/) to discover plenty examples and unlock the full power of Docling!
@@ -120,3 +122,7 @@ For individual model usage, please refer to the model licenses found in the orig
 ## IBM โค๏ธ Open Source AI
 
 Docling has been brought to you by IBM.
+
+[supported_formats]: https://ds4sd.github.io/docling/supported_formats/
+[docling_document]: https://ds4sd.github.io/docling/concepts/docling_document/
+[integrations]: https://ds4sd.github.io/docling/integrations/
diff --git a/docs/index.md b/docs/index.md
index c88ee7c64..9f782dc19 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -18,11 +18,13 @@ Docling parses documents and exports them to the desired format with ease and sp
 
 ## Features
 
-* ๐Ÿ—‚๏ธ Reads popular document formats (PDF, DOCX, PPTX, XLSX, Images, HTML, AsciiDoc & Markdown) and exports to HTML, Markdown and JSON (with embedded and referenced images)
-* ๐Ÿ“‘ Advanced PDF document understanding incl. page layout, reading order & table structures
-* ๐Ÿงฉ Unified, expressive [DoclingDocument](./concepts/docling_document.md) representation format
-* ๐Ÿค– Plug-and-play [integrations](https://ds4sd.github.io/docling/integrations/) incl. LangChain, LlamaIndex, Crew AI & Haystack for agentic AI
-* ๐Ÿ” OCR support for scanned PDFs
+* ๐Ÿ—‚๏ธ Parsing of [multiple documents formats][supported_formats] incl. PDF, DOCX, XLSX, HTML, images, & more
+* ๐Ÿ“‘ Advanced PDF understanding including page layout, reading order & table structure
+* ๐Ÿงฌ Unified, expressive [DoclingDocument][docling_document] representation format
+* โ†ช๏ธ Various [export formats][supported_formats] and options, including Markdown, HTML, and lossless JSON
+* ๐Ÿ”’ Local execution capabilities for sensitive data and air-gapped environments
+* ๐Ÿค– Plug-and-play [integrations][integrations] incl. LangChain, LlamaIndex, Crew AI & Haystack for agentic AI
+* ๐Ÿ” OCR support for scanned PDFs and images
 * ๐Ÿ’ป Simple and convenient CLI
 
 ### Coming soon
@@ -42,3 +44,7 @@ Docling parses documents and exports them to the desired format with ease and sp
 ## IBM โค๏ธ Open Source AI
 
 Docling has been brought to you by IBM.
+
+[supported_formats]: ./supported_formats.md
+[docling_document]: ./concepts/docling_document.md
+[integrations]: ./integrations/index.md
diff --git a/docs/supported_formats.md b/docs/supported_formats.md
new file mode 100644
index 000000000..d3e66b057
--- /dev/null
+++ b/docs/supported_formats.md
@@ -0,0 +1,33 @@
+Docling can parse various documents formats into a unified representation (Docling
+document), which it can export to different formats too โ€” check out
+[Architecture](./concepts/architecture.md) for more details.
+
+Below you can find a listing of all supported input and output formats.
+
+## Supported input formats
+
+| Format | Description |
+|--------|-------------|
+| PDF | |
+| DOCX, XLSX, PPTX | Default formats in MS Office 2007+, based on Office Open XML |
+| Markdown | |
+| AsciiDoc | |
+| HTML, XHTML | |
+| PNG, JPEG, TIFF, BMP | Image formats |
+
+Schema-specific support:
+
+| Format | Description |
+|--------|-------------|
+| USPTO XML | XML format followed by [USPTO](https://www.uspto.gov/patents) patents |
+| PMC XML | XML format followed by [PubMed Centralยฎ](https://pmc.ncbi.nlm.nih.gov/) articles |
+| Docling JSON | JSON-serialized [Docling Document](./concepts/docling_document.md) |
+
+## Supported output formats
+
+| Format | Description |
+|--------|-------------|
+| HTML | Docling supports both image embedding and referencing |
+| Markdown | |
+| JSON | Lossless serialization of Docling Document |
+| Doctags | |
diff --git a/docs/usage.md b/docs/usage.md
index 824f0f22d..490f7cc5b 100644
--- a/docs/usage.md
+++ b/docs/usage.md
@@ -24,20 +24,6 @@ docling https://arxiv.org/pdf/2206.01062
 
 To see all available options (export formats etc.) run `docling --help`. More details in the [CLI reference page](./reference/cli.md).
 
-### Supported formats
-
-The document conversion in Docling supports several popular formats, including:
-
-- **PDF** (Portable Document Format): the format developed by Adobe to present documents compatible across application software, hardware, and operating systems.
-- **.docx**, **.xlsx**, **.pptx** (Word, Excel, and PowerPoint): the Open XML formats suppored by Microsof Office.
-- **Markdown**:  a lightweight markup language to add formatting elements to plain text documents.
-- **AsciiDoc**: a plain text markup language for writing technical content.
-- **HTML** (Hypertext Markup Language): the standard markup language for creating web pages.
-- **XHTML** (Extensible Hypertext Markup Language): the XML-based version of HTML.
-- **XML** (Extensible Markup Language): a markup format for storing and transmitting data. Due to its flexibility, Docling requires custom implementations to identify the
-semantics of the data. Currently, Docling supports the parsing of [USPTO](https://www.uspto.gov/patents) patents and [PubMed Centralยฎ (PMC)](https://pmc.ncbi.nlm.nih.gov/) articles.
-
-
 ### Advanced options
 
 #### Adjust pipeline features
diff --git a/mkdocs.yml b/mkdocs.yml
index bbff382eb..0fcc2ca4f 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -56,6 +56,7 @@ nav:
     - "Docling": index.md
     - Installation: installation.md
     - Usage: usage.md
+    - Supported formats: supported_formats.md
     - FAQ: faq.md
     - Docling v2: v2.md
   - Concepts:
@@ -77,7 +78,7 @@ nav:
       - "Force full page OCR": examples/full_page_ocr.py
       - "Automatic OCR language detection with tesseract": examples/tesseract_lang_detection.py
       - "Accelerator options": examples/run_with_accelerator.py
-      - "Simple translation": examples/translate.py   
+      - "Simple translation": examples/translate.py
       - examples/backend_xml_rag.ipynb
     - โœ‚๏ธ Chunking:
       - examples/hybrid_chunking.ipynb