Documentation: add grids, tables to make intro info easier to digest

[sydney-runkle]

• More engaging "why PydanticAI" section with icons and headings
• Move glossary on agents page to tabular format

Before:

After:

Before:

After:

[hyperlint-ai]

The style guide flagged several spelling errors that seemed like false positives. We skipped posting inline suggestions for the following words:

• Pydantic
• Groq
• Logfire
• [Vv]alidators
• Ollama

[cloudflare-workers-and-pages]

Deploying pydantic-ai with    Cloudflare Pages

Latest commit:	e83d21e
Status:	✅  Deploy successful!
Preview URL:	https://1bd6e3f5.pydantic-ai.pages.dev
Branch Preview URL:	https://docs-update-ease-of-use.pydantic-ai.pages.dev

View logs

[sydney-runkle]

TODO in a future PR, wanted to go ahead and get this across the line :)

• Break up complicated example into more digestible parts
• Provide more context for each example, moving some information out of code annotations
• Add admonitions giving context to agent framework terminology + linking to the relevant conceptual section
• Add more Pydantic Logfire context

[summerscope]

Looking good, let's try to make this list a bit tighter still

[samuelcolvin]

The logfire logo isn't working

I'm personally still not convinced the colored icons add anything, but happy to accept that.

We should also update the root README.md.

[sydney-runkle]

I think it's just not working on the docs preview, it's working locally? I can dig into this though...

[summerscope]

@sydney-runkle I'm not super attached to the icons either, if getting rid of them helps get this across the line faster I think that's fine :)

[sydney-runkle]

I think this should be ready now, I say we merge, if the icons are an issue, I'll remove 👍

[samuelcolvin]

the reason this isn't working in the preview but is locally is you haven't updated markdown_extensions in mkdocs.insiders.yml.

if you run make docs-insiders-serve you should see the problem, generally you should always use that in development, buy you'll neeed the pppr token set.

[samuelcolvin]

is there a reason this can't just go in img?

[samuelcolvin]

or in docs/img/.icons

[sydney-runkle]

Yeah, custom icons have to go in a folder you add as the custom_dir in mkdocs.yml, and I didn't want to make img that folder...

[sydney-runkle]

But I can do that if you want!

[sydney-runkle]

https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/#additional-icons

[sydney-runkle]

Ah, thanks for the tip re insiders. Hadn't been building locally with those

[sydney-runkle]

Interesting, not getting a warning, but I am getting the failure to render on the local serve now:

(pydantic-ai) (base) programming@Sydneys-MacBook-Pro pydantic-ai % make docs-serve-insiders
insiders packages already installed
uv run --no-sync mkdocs serve -f mkdocs.insiders.yml
INFO    -  Building documentation...
INFO    -  Cleaning site directory
INFO    -  Documentation built in 4.07 seconds
INFO    -  [10:03:43] Watching paths for changes: 'docs', 'mkdocs.insiders.yml', 'pydantic_ai_slim',
           'pydantic_ai_examples'
INFO    -  [10:03:43] Serving on http://127.0.0.1:8000/

[sydney-runkle]

Fixed, thanks for the tip! Forgot about mkdocs.insiders.yml