From 834a57a15810e07ec8d72131e5347899e00cae24 Mon Sep 17 00:00:00 2001
From: Jared Dillard <jared.dillard@gmail.com>
Date: Sun, 18 May 2025 20:54:55 -0700
Subject: [PATCH] add missing file

---
 docs/source/advanced-configuration.rst | 168 +++++++++++++++++++++++++
 1 file changed, 168 insertions(+)
 create mode 100644 docs/source/advanced-configuration.rst

diff --git a/docs/source/advanced-configuration.rst b/docs/source/advanced-configuration.rst
new file mode 100644
index 0000000..592162a
--- /dev/null
+++ b/docs/source/advanced-configuration.rst
@@ -0,0 +1,168 @@
+Advanced Configuration
+======================
+
+This page covers advanced configuration options for the sphinx-llms-txt extension.
+
+.. _customizing_llms_files:
+
+Customizing the LLMs Files
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+By default, the extension generates two files:
+
+1. ``llms.txt`` - A summary file in Markdown format
+2. ``llms-full.txt`` - A complete documentation file in reStructuredText format
+
+You can customize these files in several ways:
+
+.. _changing_filenames:
+
+Changing Filenames
+~~~~~~~~~~~~~~~~~~
+
+You can change the default filenames by setting these values in your ``conf.py``:
+
+.. code-block:: python
+
+   llms_txt_filename = "custom-summary.txt"
+   llms_txt_full_filename = "custom-docs.txt"
+
+.. _disabling_file_generation:
+
+Disabling File Generation
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+If you only want one of the files, you can disable generation of the other:
+
+.. code-block:: python
+
+   # Disable summary file
+   llms_txt_file = False
+   
+   # Disable full documentation file
+   llms_txt_full_file = False
+
+.. _custom_summary:
+
+Adding a Custom Summary
+~~~~~~~~~~~~~~~~~~~~~~~
+
+The summary file can include a custom description of your project:
+
+.. code-block:: python
+
+   llms_txt_summary = """
+   This documentation explains how to use MyProject to build amazing
+   applications. The project provides a comprehensive API for handling
+   data processing and visualization.
+   """
+
+.. note:: The summary can span multiple lines and will be properly formatted in the output file.
+
+.. _custom_title:
+
+Custom Title
+~~~~~~~~~~~~
+
+By default, the project name from Sphinx is used as the title in ``llms.txt``. You can override this:
+
+.. code-block:: python
+
+   llms_txt_title = "My Custom Project Documentation"
+
+.. _handling_large_documentation:
+
+Handling Large Documentation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+For very large documentation sets, generating the full documentation file might exceed reasonable size limits. You can set a maximum line count:
+
+.. code-block:: python
+
+   llms_txt_full_max_size = 10000  # Maximum 10,000 lines
+
+If the generated file would exceed this limit, the extension will skip its generation and show a warning, allowing the build to complete.
+
+.. tip:: Use :ref:`excluding_content` to remove less relevant pages.
+
+.. _custom_directive_handling:
+
+Custom Directive Handling
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _path_resolution:
+
+Path Resolution
+~~~~~~~~~~~~~~~
+
+The extension resolves paths in common directives like ``image`` and ``figure``. You can add custom directives to this list:
+
+.. code-block:: python
+
+   llms_txt_directives = [
+       "my-custom-image-directive",
+       "another-directive-with-paths",
+   ]
+
+This ensures that paths in your custom directives are properly resolved in the generated files.
+
+.. _excluding_content:
+
+Excluding Content
+^^^^^^^^^^^^^^^^^
+
+You can exclude specific pages from being included in the generated files:
+
+.. code-block:: python
+
+   llms_txt_exclude = [
+       "search",  # Exclude the search page
+       "genindex",  # Exclude the index page
+       "private_*",  # Exclude all pages starting with 'private_'
+   ]
+
+This is useful for excluding auto-generated pages, indexes, or content that isn't relevant for LLM consumption.
+
+.. _using_html_baseurl:
+
+Using HTML Base URL
+^^^^^^^^^^^^^^^^^^^
+
+If you want to include absolute URLs for resources in your documentation, you can use Sphinx's built-in ``html_baseurl`` configuration:
+
+.. code-block:: python
+
+   html_baseurl = "https://example.com/docs/"
+
+When this option is set, all resolved paths in directives will be prefixed with this URL, creating absolute paths in the generated files.
+
+.. _integration_examples:
+
+Integration Examples
+^^^^^^^^^^^^^^^^^^^^
+
+Complete Configuration Example
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Here's a complete example showing multiple configuration options:
+
+.. code-block:: python
+
+   # File names and generation options
+   llms_txt_filename = "ai-summary.txt"
+   llms_txt_full_filename = "ai-full-docs.txt"
+   llms_txt_full_max_size = 50000
+   
+   # Content customization
+   llms_txt_title = "Project Documentation for AI Assistants"
+   llms_txt_summary = """
+   This is a comprehensive documentation set for our project.
+   It includes API references, usage examples, and tutorials.
+   """
+   
+   # Path handling
+   html_baseurl = "https://docs.example.com/"
+   llms_txt_directives = ["custom-image", "custom-include"]
+   
+   # Content filtering
+   llms_txt_exclude = ["search", "genindex", "404", "private_*"]