feat: Add base_url config option

PR-25: #25

Author: stichbury

README.md

@@ -63,6 +63,18 @@ plugins:
       - usage/*.md
 ```
 
+## Override `site_url`
+
+Use `base_url` to point `llms.txt` to documentation in a specific directory. For example, when using [Read the Docs](https://github.com/readthedocs/), use `base_url` to indicate the path to the hosted docs built for a specific language or version.
+
+The resulting `llms.txt` uses `base_url` when it is specified, instead of the canonical `site_url`.  
+
+```yaml title="mkdocs.yml"
+plugins:
+- llmstxt: 
+    base_url: https://productname.hostname.io/en/0.1.34
+```
+
 ## Full output
 
 Although not explicitly written out in the https://llmstxt.org/ guidelines, it is common to output a `llms-full.txt` file with every page content expanded. This file can be generated by setting the `full_output` configuration value:

src/mkdocs_llmstxt/_internal/config.py

@@ -11,6 +11,7 @@ class _PluginConfig(BaseConfig):
 
     autoclean = mkconf.Type(bool, default=True)
     preprocess = mkconf.Optional(mkconf.File(exists=True))
+    base_url = mkconf.Optional(mkconf.Type(str))
     markdown_description = mkconf.Optional(mkconf.Type(str))
     full_output = mkconf.Optional(mkconf.Type(str))
     sections = mkconf.DictOfItems(

src/mkdocs_llmstxt/_internal/plugin.py

@@ -135,8 +135,11 @@ def on_page_content(self, html: str, *, page: Page, **kwargs: Any) -> str | None
             if md_url in (".", "./"):
                 md_url = ""
 
-            # Guaranteed to exist as we require `site_url` to be configured.
-            base = cast("str", self.mkdocs_config.site_url)
+            # Use `base_url` if it exists.
+            if self.config.base_url is not None:
+                base = cast("str", self.config.base_url)
+            else: # use a url that is guaranteed to exist as we require `site_url` to be configured.
+                base = cast("str", self.mkdocs_config.site_url)
             if not base.endswith("/"):
                 base += "/"
             md_url = urljoin(base, md_url)

tests/test_plugin.py

@@ -16,6 +16,7 @@
                     {
                         "llmstxt": {
                             "full_output": "llms-full.txt",
+                            "base_url": "https://example.org/en/0.1.34",
                             "sections": {
                                 "Index": ["index.md"],
                                 "Usage": [{"page1.md": "Some usage docs."}],