feature: mkdocs-llmstxt compatibility issue with mkdocstrings show_source #299
Description
mkdocs-llmstxt compatibility issue with mkdocstrings show_source
Problem Description
When using mkdocstrings with show_source: true to include Python source code in documentation, the mkdocs-llmstxt plugin generates suboptimal output in the generated llms-full.txt file. Instead of preserving clean, readable Python code blocks, the source code is converted into confusing table format with line numbers and compressed code on a single line.
Environment
- mkdocstrings[python]: 0.29.1
- mkdocs-llmstxt: 0.3.0
- mkdocs-material: 9.6.15
Steps to Reproduce
- Set up a MkDocs project with both mkdocstrings and mkdocs-llmstxt plugins
- Use mkdocstrings with
show_source: truein documentation:::: module.Class options: heading_level: 3 show_source: true
- Build the documentation with
mkdocs build - Examine the generated
llms-full.txtfile
Current Behavior (Problematic)
In the generated llms-full.txt, Python source code appears as a confusing table format:
Source code in `src/balatrobot/enums.py`
| | |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| ` 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27` | `@unique class State(Enum): """Game state values representing different phases of gameplay in Balatro, from menu navigation to active card play and shop interactions.""" SELECTING_HAND = 1 HAND_PLAYED = 2 DRAW_TO_HAND = 3 GAME_OVER = 4 SHOP = 5 PLAY_TAROT = 6 BLIND_SELECT = 7 ROUND_EVAL = 8 TAROT_PACK = 9 PLANET_PACK = 10 MENU = 11 TUTORIAL = 12 SPLASH = 13 SANDBOX = 14 SPECTRAL_PACK = 15 DEMO_CTA = 16 STANDARD_PACK = 17 BUFFOON_PACK = 18 NEW_ROUND = 19 ` |
Expected Behavior
For optimal LLM consumption, Python source code should be preserved as clean markdown code blocks:
Source code in `src/balatrobot/enums.py`
```python
@unique
class State(Enum):
"""Game state values representing different phases of gameplay in Balatro,
from menu navigation to active card play and shop interactions."""
SELECTING_HAND = 1
HAND_PLAYED = 2
DRAW_TO_HAND = 3
GAME_OVER = 4
SHOP = 5
PLAY_TAROT = 6
BLIND_SELECT = 7
ROUND_EVAL = 8
TAROT_PACK = 9
PLANET_PACK = 10
MENU = 11
TUTORIAL = 12
SPLASH = 13
SANDBOX = 14
SPECTRAL_PACK = 15
DEMO_CTA = 16
STANDARD_PACK = 17
BUFFOON_PACK = 18
NEW_ROUND = 19
```
Impact
This formatting issue significantly reduces the readability and usefulness of the generated LLM-optimized documentation. The compressed table format makes it difficult for both humans and LLMs to understand the code structure, defeating the purpose of including source code in the documentation.
Potential Solutions
- mkdocstrings enhancement: Add an option to output source code in a format that's more compatible with LLM-focused tools
- Better HTML structure: Ensure that when
show_source: trueis used, the HTML output uses semantic markup that mkdocs-llmstxt can better interpret - Plugin coordination: Collaborate with mkdocs-llmstxt maintainers to improve how code blocks from mkdocstrings are processed
Example Project
This issue can be reproduced using the balatrobot project, which uses both plugins and demonstrates the problem in its generated documentation.