# mkdocs-link-cards
Discord-style **link previews** for MkDocs, rendered as **Material** cards at build time.
- ✅ Static HTML output (GitHub Pages friendly)
- ✅ YouTube, arXiv, X/Twitter adapters
- ✅ Generic OpenGraph/Twitter/JSON-LD fallback
- ✅ Cache with TTL, polite UA/timeouts
- ✅ Typed, linted (Ruff), MyPy-clean, tested
## Install
```bash
poetry add mkdocs-link-cards
# or: pip install mkdocs-link-cards
```
## Configure (`mkdocs.yml`)
```yaml
plugins:
- search
- link-cards:
ttl: 604800 # 7 days
timeout: 8
allow_domains: [] # optional safelist
deny_domains: [] # optional blocklist
```
## Use in Markdown
```md
[[card https://arxiv.org/abs/2501.01234]]
[[card https://www.youtube.com/watch?v=dQw4w9WgXcQ title="Optional override"]]
[[card https://x.com/trydaily/status/1840107...]]
[[card https://example.com/interesting-article]]
```
The plugin outputs Material’s card markup, so your site inherits all theme styles:
```html
<div class="grid cards" markdown>
- <img ... class="linkcard-img">
<strong>Title</strong>
<small>Site</small>
---
Description...
<a class="md-button" href="...">Open</a>
</div>
```
### Notes
* **Static**: previews update when you rebuild (or when cache TTL expires).
* **Privacy/Robustness**: Icons are data-URIs. Thumbnails are remote (YouTube); others are taken from page metadata if available.
* **CI**: tests mock the network; builds are deterministic.
## Extras
Optional extras (not required):
```bash
poetry add mkdocs-link-cards[oembed]
poetry add mkdocs-link-cards[summarize]
```
## Roadmap
* Provider adapters for GitHub repos, Substack, arXiv PDF direct links
* Async fetch with `httpx` + concurrency controls
* CLI: `mkcards warm docs/` to pre-cache links
* Jinja templates for custom card layouts
## License
MIT © Contributors
Raw data
{
"_id": null,
"home_page": "https://github.com/markeyser/mkdocs-link-cards",
"name": "mkdocs-link-cards",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mkdocs, material, cards, opengraph, oembed, arxiv, youtube",
"author": "markeyser",
"author_email": "marcosak@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/bb/63/555c74a4ccb106f1666bb880eae7036c0d07bbd413449df60418f6472a88/mkdocs_link_cards-0.1.0.tar.gz",
"platform": null,
"description": "# mkdocs-link-cards\n\nDiscord-style **link previews** for MkDocs, rendered as **Material** cards at build time.\n\n- \u2705 Static HTML output (GitHub Pages friendly)\n- \u2705 YouTube, arXiv, X/Twitter adapters\n- \u2705 Generic OpenGraph/Twitter/JSON-LD fallback\n- \u2705 Cache with TTL, polite UA/timeouts\n- \u2705 Typed, linted (Ruff), MyPy-clean, tested\n\n\n\n## Install\n\n```bash\npoetry add mkdocs-link-cards\n# or: pip install mkdocs-link-cards\n```\n\n## Configure (`mkdocs.yml`)\n\n```yaml\nplugins:\n - search\n - link-cards:\n ttl: 604800 # 7 days\n timeout: 8\n allow_domains: [] # optional safelist\n deny_domains: [] # optional blocklist\n```\n\n## Use in Markdown\n\n```md\n[[card https://arxiv.org/abs/2501.01234]]\n[[card https://www.youtube.com/watch?v=dQw4w9WgXcQ title=\"Optional override\"]]\n[[card https://x.com/trydaily/status/1840107...]]\n[[card https://example.com/interesting-article]]\n```\n\nThe plugin outputs Material\u2019s card markup, so your site inherits all theme styles:\n\n```html\n<div class=\"grid cards\" markdown>\n- <img ... class=\"linkcard-img\">\n <strong>Title</strong>\n <small>Site</small>\n ---\n Description...\n\n <a class=\"md-button\" href=\"...\">Open</a>\n</div>\n```\n\n### Notes\n\n* **Static**: previews update when you rebuild (or when cache TTL expires).\n* **Privacy/Robustness**: Icons are data-URIs. Thumbnails are remote (YouTube); others are taken from page metadata if available.\n* **CI**: tests mock the network; builds are deterministic.\n\n## Extras\n\nOptional extras (not required):\n\n```bash\npoetry add mkdocs-link-cards[oembed]\npoetry add mkdocs-link-cards[summarize]\n```\n\n## Roadmap\n\n* Provider adapters for GitHub repos, Substack, arXiv PDF direct links\n* Async fetch with `httpx` + concurrency controls\n* CLI: `mkcards warm docs/` to pre-cache links\n* Jinja templates for custom card layouts\n\n## License\n\nMIT \u00a9 Contributors\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Discord-style link previews (Material cards) for MkDocs at build time.",
"version": "0.1.0",
"project_urls": {
"Homepage": "https://github.com/markeyser/mkdocs-link-cards",
"Issues": "https://github.com/markeyser/mkdocs-link-cards/issues",
"Repository": "https://github.com/markeyser/mkdocs-link-cards"
},
"split_keywords": [
"mkdocs",
" material",
" cards",
" opengraph",
" oembed",
" arxiv",
" youtube"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "12f1172db4bfc087b419c5d9cc64680b843fb96b492bd1925290016cedfabc13",
"md5": "d89b92983eee8159bf3cae55b87f2d0a",
"sha256": "acb9f0645ee7903a6e339e4b13c390254a0cd2dac94f8ef83dfcfa4dce11006a"
},
"downloads": -1,
"filename": "mkdocs_link_cards-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d89b92983eee8159bf3cae55b87f2d0a",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 8283,
"upload_time": "2025-10-22T13:27:19",
"upload_time_iso_8601": "2025-10-22T13:27:19.663934Z",
"url": "https://files.pythonhosted.org/packages/12/f1/172db4bfc087b419c5d9cc64680b843fb96b492bd1925290016cedfabc13/mkdocs_link_cards-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "bb63555c74a4ccb106f1666bb880eae7036c0d07bbd413449df60418f6472a88",
"md5": "c399c10b16575386cea8c40218d47bca",
"sha256": "1c3e946e1d1275b2eca8c8b56eedfa8a565405a04634f4e3856c77abb5779dd6"
},
"downloads": -1,
"filename": "mkdocs_link_cards-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "c399c10b16575386cea8c40218d47bca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 7460,
"upload_time": "2025-10-22T13:27:20",
"upload_time_iso_8601": "2025-10-22T13:27:20.669624Z",
"url": "https://files.pythonhosted.org/packages/bb/63/555c74a4ccb106f1666bb880eae7036c0d07bbd413449df60418f6472a88/mkdocs_link_cards-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 13:27:20",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "markeyser",
"github_project": "mkdocs-link-cards",
"github_not_found": true,
"lcname": "mkdocs-link-cards"
}
JSON
