Metadata-Version: 2.4
Name: mkdocs-link-cards
Version: 0.1.0
Summary: Discord-style link previews (Material cards) for MkDocs at build time.
License: MIT
License-File: LICENSE
Keywords: mkdocs,material,cards,opengraph,oembed,arxiv,youtube
Author: markeyser
Author-email: marcosak@gmail.com
Requires-Python: >=3.10
Classifier: Development Status :: 3 - Alpha
Classifier: Framework :: MkDocs
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Site Management
Provides-Extra: oembed
Provides-Extra: summarize
Requires-Dist: beautifulsoup4 (>=4.12)
Requires-Dist: extruct (>=0.16)
Requires-Dist: micawber (>=0.5.5) ; extra == "oembed"
Requires-Dist: mkdocs (>=1.5)
Requires-Dist: requests (>=2.31)
Requires-Dist: sumy (>=0.11.0) ; extra == "summarize"
Requires-Dist: trafilatura (>=1.8.0) ; extra == "summarize"
Requires-Dist: w3lib (>=2.1)
Project-URL: Homepage, https://github.com/markeyser/mkdocs-link-cards
Project-URL: Issues, https://github.com/markeyser/mkdocs-link-cards/issues
Project-URL: Repository, https://github.com/markeyser/mkdocs-link-cards
Description-Content-Type: text/markdown

# 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

![demo](https://user-images.githubusercontent.com/placeholder/demo.gif)

## 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

