From cceddc92d8d96571d3cf5f932d36fe67c6144bc9 Mon Sep 17 00:00:00 2001
From: Andreas Motl <andreas.motl@crate.io>
Date: Fri, 24 Jan 2025 22:25:40 +0100
Subject: [PATCH] oEmbed: Add dedicated page

---
 docs/myst/oembed.md | 38 ++++++++++++++++++++++++++++++++++++++
 docs/rst/oembed.rst | 42 ++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)
 create mode 100644 docs/myst/oembed.md
 create mode 100644 docs/rst/oembed.rst

diff --git a/docs/myst/oembed.md b/docs/myst/oembed.md
new file mode 100644
index 00000000..b281ff1d
--- /dev/null
+++ b/docs/myst/oembed.md
@@ -0,0 +1,38 @@
+(oembed-md)=
+
+# oEmbed widgets
+
+
+## About
+
+[oEmbed] is a format for allowing an embedded representation of a URL on
+third party sites. The simple API allows a website to display embedded
+content (such as photos or videos) when a user posts a link to that
+resource, without having to parse the resource directly.
+
+Client-side implementations of oEmbed, like [oEmbedPy], can render
+[oEmbed] information provided by any HTML page, for example Bluesky,
+Reddit, Twitter/X, and many more. Registered oEmbed providers can be
+explored per [providers.json].
+
+
+## Examples
+
+### Bluesky
+:::{oembed} https://bsky.app/profile/simonprickett.dev/post/3lgizsidy722u
+:::
+
+### Twitter/X
+:::{oembed} https://x.com/simon_prickett/status/1882858717571641581
+:::
+
+### YouTube
+:::{oembed} https://www.youtube.com/watch?v=YE7VzlLtp-4
+:maxwidth: 480
+:maxheight: 320
+:::
+
+
+[oEmbed]: https://oembed.com/
+[oEmbedPy]: https://oembedpy.readthedocs.io/
+[providers.json]: https://oembed.com/providers.json
diff --git a/docs/rst/oembed.rst b/docs/rst/oembed.rst
new file mode 100644
index 00000000..7693edc0
--- /dev/null
+++ b/docs/rst/oembed.rst
@@ -0,0 +1,42 @@
+.. _oembed-rst:
+
+##############
+oEmbed widgets
+##############
+
+=====
+About
+=====
+
+`oEmbed`_ is a format for allowing an embedded representation of a URL on
+third party sites. The simple API allows a website to display embedded
+content (such as photos or videos) when a user posts a link to that
+resource, without having to parse the resource directly.
+
+Client-side implementations of oEmbed, like `oEmbedPy`_, can render
+`oEmbed`_ information provided by any HTML page, for example Bluesky,
+Reddit, Twitter/X, and many more. Registered oEmbed providers can be
+explored per [providers.json].
+
+========
+Examples
+========
+
+Bluesky
+=======
+.. oembed:: https://bsky.app/profile/simonprickett.dev/post/3lgizsidy722u
+
+Twitter/X
+=========
+.. oembed:: https://x.com/simon_prickett/status/1882858717571641581
+
+YouTube
+=======
+.. oembed:: https://www.youtube.com/watch?v=YE7VzlLtp-4
+    :maxwidth: 480
+    :maxheight: 320
+
+
+.. _oEmbed: https://oembed.com/
+.. _oEmbedPy: https://oembedpy.readthedocs.io/
+.. _providers.json: https://oembed.com/providers.json