From f1a3963a0d1c30af46f7ee70410d5bc31b3aa196 Mon Sep 17 00:00:00 2001
From: Jared Dillard <jared.dillard@gmail.com>
Date: Wed, 3 Dec 2025 13:51:09 -0800
Subject: [PATCH] [docs] Discuss output formats in the docs (#55)

---
 docs/source/getting-started.rst | 42 +++++++++++++++++++++++++++++++--
 1 file changed, 40 insertions(+), 2 deletions(-)

diff --git a/docs/source/getting-started.rst b/docs/source/getting-started.rst
index 52451b1..e5335cd 100644
--- a/docs/source/getting-started.rst
+++ b/docs/source/getting-started.rst
@@ -34,7 +34,45 @@ After the HTML finishes building, **sphinx-llms-txt** will output the location o
     sphinx-llms-txt: Created /path/to/_build/html/llms-full.txt with 45 sources and 6879 lines
     sphinx-llms-txt: created /path/to/_build/html/llms.txt
 
+Choosing an Output Format
+-------------------------
 
-.. tip:: Make sure to confirm the accuracy of the output files after installs and upgrades.
+By default, **sphinx-llms-txt** requires no additional configuration and links to raw reStructuredText source files in :confval:`_sources/ <sphinx:html_copy_source>`.
+For optimal LLM support, you can use `sphinx-markdown-builder`_ and/or `sphinxcontrib-restbuilder`_, set up in parallel builds using CMake .
+
+.. list-table:: Output Format Comparison
+   :header-rows: 1
+   :widths: 18 27 27 27
+
+   * -
+     - Default (no config)
+     - Markdown (CMake)
+     - RST (CMake)
+   * - **Format**
+     - Raw RST source
+     - Rendered Markdown
+     - Rendered RST
+   * - **LLM Readability**
+     - Good - preserves structure for simple syntax
+     - Excellent - native LLM format
+     - Good - Can provide more structured content
+   * - **Key Advantage**
+     - Zero setup required
+     - More compact (less input tokens)
+     - Can preserve Sphinx semantics
+   * - **Key Disadvantage**
+     - Raw directives (e.g., autodoc) won't be parsed
+     - Loses structure from complex directives
+     - Can lose structure from complex directives
+   * - **llms-full.txt support**
+     - Suported with above caveats
+     - Pending `support <https://github.com/liran-funaro/sphinx-markdown-builder/pull/37>`_
+     - Pending `support <https://github.com/sphinx-contrib/restbuilder/pull/35>`_
+
+
+See the project's `CMake setup <https://github.com/jdillard/sphinx-llms-txt/tree/main/cmake>`_ for an example of building HTML, Markdown, and RST in parallel.
+Use :confval:`llms_txt_uri_template` to configure links to point to your preferred format.
+
+.. _sphinx-markdown-builder: https://pypi.org/project/sphinx-markdown-builder/
+.. _sphinxcontrib-restbuilder: https://pypi.org/project/sphinxcontrib-restbuilder/
 
-See :doc:`advanced-configuration` for more information about how to use **sphinx-llms-txt**.