)
""")
assert (site / first).read_text(encoding="utf-8") == "# First\n\nOne.\n"
assert (site / second).read_text(encoding="utf-8") == "# Second\n\nTwo.\n"
assert not (site / "excluded" / "index.md").exists()
assert not (site / "excluded.md").exists()
full = (site / "ai" / "full.txt").read_text(encoding="utf-8")
assert full.count("# First\n") == 2
assert full.index("# Z first") < full.index("# A second")
# A cached build must still emit the page Markdown and both aggregate files.
(site / first).unlink()
(site / "llms.txt").unlink()
(site / "ai" / "full.txt").unlink()
build(tmp_path, config)
assert (site / first).read_text(encoding="utf-8") == "# First\n\nOne.\n"
assert (site / "llms.txt").read_text(encoding="utf-8") == index
assert (site / "ai" / "full.txt").read_text(encoding="utf-8") == full
def test_rebuilds_gfm_from_generated_html_with_search_disabled(
tmp_path: Path,
) -> None:
docs = tmp_path / "docs"
docs.mkdir()
(docs / "index.md").write_text(
dedent("""\
# {{ config.site_name }}
!!! note "A note"
Generated **content**.
```python
value = "```"
```
| Name | Value |
| ---- | ----- |
| one | two |
- Parent
- Child
- [x] Done
- [ ] Todo
Old content with a note.[^example]
[^example]: A **formatted** footnote.
"""),
encoding="utf-8",
)
site = build(
tmp_path,
dedent("""\
plugins:
- search: {enabled: false}
- macros
- llmstxt:
sections: {Pages: [index.md]}
"""),
)
markdown = (site / "index.md").read_text(encoding="utf-8")
assert markdown.startswith("# LLM test\n")
assert (
dedent("""\
> [!NOTE]
>
> **A note**
>
> Generated **content**.
""")
in markdown
)
assert '````python\nvalue = "```"\n````' in markdown
assert (
dedent("""\
| Name | Value |
| --- | --- |
| one | two |
""")
in markdown
)
assert "- Parent\n\n - Child" in markdown
assert "- [x] Done\n- [ ] Todo" in markdown
assert "~~Old content~~ with a note.[^/docs/#example]\n" in markdown
assert "[^/docs/#example]: A **formatted** footnote." in markdown
assert "footnote-backref" not in markdown
assert "headerlink" not in markdown
assert "{{" not in markdown
assert "!!!" not in markdown
assert not (site / "llms-full.txt").exists()
@pytest.mark.parametrize("autoclean", [True, False])
def test_converts_admonitions_details_and_callouts_to_github_alerts(
tmp_path: Path, autoclean: bool
) -> None:
docs = tmp_path / "docs"
docs.mkdir()
(docs / "index.md").write_text(
dedent("""\
# Alerts
!!! warning "Before you start"
Save your **work**.
??? tip "Try `fast=True`"
Use the faster mode.
???+ danger
This deletes data.
!!! important
Read the instructions.
!!! caution ""
Handle with care.
!!! custom "Project policy"
Follow these rules.
> [!NOTE] From a callout
> The body remains readable.
"""),
encoding="utf-8",
)
config = dedent(f"""\
plugins:
- callouts
- llmstxt:
autoclean: {str(autoclean).lower()}
sections:
Pages: [index.md]
""")
site = build(tmp_path, config)
markdown = (site / "index.md").read_text(encoding="utf-8")
assert (
dedent("""\
> [!WARNING]
>
> **Before you start**
>
> Save your **work**.
> [!TIP]
>
> **Try `fast=True`**
>
> Use the faster mode.
> [!CAUTION]
>
> **Danger**
>
> This deletes data.
> [!IMPORTANT]
>
> Read the instructions.
> [!CAUTION]
>
> Handle with care.
> [!NOTE]
>
> **Project policy**
>
> Follow these rules.
> [!NOTE]
>
> **From a callout**
>
> The body remains readable.
""")
in markdown
)
# The HTML site keeps its original admonitions and disclosure controls.
html = (site / "index.html").read_text(encoding="utf-8")
assert '' in html
assert '' in html
assert '' in html
@pytest.mark.parametrize("autoclean", [True, False])
def test_omits_mkdocstrings_source_and_empty_icons_from_llmstxt(
tmp_path: Path, autoclean: bool
) -> None:
docs = tmp_path / "docs"
docs.mkdir()
source = tmp_path / "src"
source.mkdir()
(source / "sample_api.py").write_text(
dedent('''\
def greet(name: str) -> str:
"""Return a greeting.
Examples:
```python
greet("reader")
```
"""
return f"Hello, {name}!"
'''),
encoding="utf-8",
)
(docs / "index.md").write_text(
dedent("""\
# API
::: sample_api.greet
## Example
```python
from sample_api import greet
print(greet("reader"))
```
"""),
encoding="utf-8",
)
config = dedent(f"""\
plugins:
- mkdocstrings:
handlers:
python:
paths: [src]
options:
docstring_style: google
heading_level: 2
show_root_heading: true
show_root_full_path: false
show_symbol_type_heading: true
separate_signature: true
show_signature_annotations: true
show_source: true
- llmstxt:
autoclean: {str(autoclean).lower()}
full_output: llms-full.txt
sections:
Pages: [index.md]
""")
site = build(tmp_path, config)
# Both LLM outputs keep the API documentation and examples
# without the implementation (source code).
for name in ("index.md", "llms-full.txt"):
markdown = (site / name).read_text(encoding="utf-8")
assert "## greet" in markdown
assert markdown.count("Return a greeting.") == 1
assert "greet(name: str) -> str" in markdown
assert (
dedent("""\
```python
greet("reader")
```
""")
in markdown
)
assert (
dedent("""\
```python
from sample_api import greet
print(greet("reader"))
```
""")
in markdown
)
assert "