docs: add mastodon

delucis · Aug 16, 2024 · 6617808 · 6617808
1 parent ae7e5b5
commit 6617808
Show file tree

Hide file tree

Showing 5 changed files with 138 additions and 2 deletions.
diff --git a/docs/src/assets/theme.css b/docs/src/assets/theme.css
@@ -13,6 +13,7 @@
 	--sl-color-black: #19171c;
 
 	--tc-border-color: var(--sl-color-gray-5);
+	--mc-border-color: var(--sl-color-gray-5);
 }
 /* Light mode colors. */
 :root[data-theme='light'] {

diff --git a/docs/src/content/docs/components/_examples/StyledToot.astro b/docs/src/content/docs/components/_examples/StyledToot.astro
@@ -0,0 +1,22 @@
+---
+import { Toot } from '@astro-community/astro-embed-mastodon';
+---
+
+<div class="styled-toot">
+	<Toot id="https://m.webtoo.ls/@astro/112616562969236130" />
+</div>
+
+<style>
+	.styled-toot :global(.mastodon-toot) {
+		background: floralwhite;
+		color: darkblue;
+		font-family: cursive;
+		font-size: 1.25rem;
+		border: 0;
+	}
+
+	.styled-toot :global(.mastodon-toot a) {
+		color: purple;
+		font-weight: bold;
+	}
+</style>
diff --git a/docs/src/content/docs/components/mastodon.mdx b/docs/src/content/docs/components/mastodon.mdx
@@ -0,0 +1,98 @@
+---
+title: Toot
+description: Learn how to use the Astro Embed Toot component to embed Mastodon posts in your website
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { Tweet } from '@astro-community/astro-embed-twitter';
+import { Toot } from '@astro-community/astro-embed-mastodon';
+
+The `<Toot>` component embeds posts from Mastodon in Astro projects.
+
+## Usage
+
+The `<Toot>` component generates a static Mastodon card for a single Toot using [Mastodon’s API](https://docs.joinmastodon.org/client/intro/).
+
+<Tabs>
+<TabItem label="Astro" icon="astro">
+```astro
+---
+import { Toot } from 'astro-embed';
+---
+
+<Toot id="https://m.webtoo.ls/@astro/112966069629573422" />
+```
+</TabItem>
+<TabItem label="MDX" icon="seti:markdown">
+```mdx
+import { Toot } from 'astro-embed';
+
+<Toot id="https://m.webtoo.ls/@astro/112966069629573422" />
+```
+</TabItem>
+</Tabs>
+
+The above code produces the following result:
+
+<div>
+	<Toot id="https://m.webtoo.ls/@astro/112966069629573422" />
+</div>
+
+:::note
+The `<Toot>` component styles are intentionally minimal.
+They will match the font styles of your surrounding content. See [“Styling the Toot component”](#styling-the-toot-component) below for more details.
+:::
+
+## Styling the Toot component
+
+By default the `<Toot>` card has minimal styling, which should adapt to your site’s font settings etc.
+
+You can customise it by targeting the `.mastodon-toot` class, for example:
+
+```css
+.mastodon-toot {
+	background: floralwhite;
+	color: darkblue;
+	font-family: cursive;
+	font-size: 1.25rem;
+	border: 0;
+}
+
+.mastodon-toot a {
+	color: purple;
+	font-weight: bold;
+}
+```
+
+The above styles would render `<Toot>` like this:
+
+import StyledToot from './_examples/StyledToot.astro';
+
+<StyledToot />
+
+### Custom properties API
+
+The `<Toot>` component also supports a minimal API for controlling its styles by setting some CSS custom properties.
+
+```css
+:root {
+	/* Control the padding inside the Mastodon card. */
+	--mc-padding: 1em;
+	/* Set the border color of the Mastodon card. */
+	--mc-border-color: #cfd9de;
+}
+```
+
+## Standalone installation
+
+If you only need the `<Toot>` component, you can install the package directly instead of the main `astro-embed` package:
+
+import { PackageManagers } from 'starlight-package-managers';
+
+<PackageManagers pkg="@astro-community/astro-embed-mastodon" />
+
+The `<Toot>` component can then be imported as:
+
+```js
+import { Toot } from '@astro-community/astro-embed-mastodon';
+```
diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx
@@ -24,14 +24,16 @@ To use components in `.astro` files, import them in the component script and the
 ```astro
 ---
 // src/components/Example.astro
-import { Tweet, Vimeo, YouTube } from 'astro-embed';
+import { Toot, Tweet, Vimeo, YouTube } from 'astro-embed';
 ---
 
 <Tweet id="https://twitter.com/astrodotbuild/status/1512144306898976768" />
 
 <Vimeo id="https://vimeo.com/32001208" />
 
 <YouTube id="https://youtu.be/xtTy5nKay_Y" />
+
+<Toot id="https://mastodon.social/@sarah11918/112954791910873136" />
 ```
 
 ### In MDX files
@@ -44,7 +46,7 @@ When using the [Astro MDX integration](https://docs.astro.build/en/guides/integr
 title: My MDX page with embed components
 ---
 
-import { Tweet, Vimeo, YouTube } from 'astro-embed';
+import { Toot, Tweet, Vimeo, YouTube } from 'astro-embed';
 
 Hey look! I can embed a tweet _in Markdown_!
 
@@ -54,6 +56,10 @@ Vimeo and YouTube videos work too :-)
 
 <Vimeo id="https://vimeo.com/32001208" />
 <YouTube id="https://youtu.be/xtTy5nKay_Y" />
+
+And even Mastodon toots!
+
+<Toot id="https://mastodon.social/@sarah11918/112954791910873136" />
 ```
 
 ### Auto-embed URLs in MDX
@@ -67,6 +73,7 @@ Learn how to set up the integration in the [“Auto-embed URLs”](/integration/
 Astro Embed currently supports the following services:
 
 <CardGrid>
+	<LinkCard title="Mastodon" href="/components/mastodon/" />
 	<LinkCard title="Open Graph" href="/components/link-preview/" />
 	<LinkCard title="Twitter" href="/components/twitter/" />
 	<LinkCard title="Vimeo" href="/components/vimeo/" />

diff --git a/docs/src/content/docs/index.mdx b/docs/src/content/docs/index.mdx
@@ -46,6 +46,14 @@ import { Icon, Card, CardGrid } from '@astrojs/starlight/components';
 
     </Card>
 
+    <Card title="Mastodon" icon="mastodon">
+
+    	Embed the contents of a Toot without client-side JavaScript.
+
+    	[Toot docs](/components/mastodon/)
+
+    </Card>
+
     <Card title="Link Preview" icon="seti:html">
 
     	Embed the Open Graph media and metadata for any URL in your page.