Add a Starlight-powered docs site (#96)

.eslintrc.cjs

@@ -15,5 +15,13 @@ module.exports = {
 		'no-console': ['error', { allow: ['warn', 'error'] }],
 		'@typescript-eslint/no-explicit-any': ['warn'],
 	},
-	ignorePatterns: ['demo/dist/**'],
+	ignorePatterns: ['demo/dist/**', 'docs/dist/**'],
+	overrides: [
+		{
+			files: ['**/*.d.ts'],
+			rules: {
+				'@typescript-eslint/triple-slash-reference': 0,
+			},
+		},
+	],
 };

.vscode/settings.json

@@ -1,7 +1,7 @@
 {
   "editor.formatOnSave": true,
   "editor.codeActionsOnSave": {
-    "source.fixAll": true
+    "source.fixAll": "explicit"
   },
   "cSpell.words": ["Astro"],
   "prettier.documentSelectors": ["**/*.astro"]

docs/.gitignore

@@ -0,0 +1,21 @@
+# build output
+dist/
+# generated types
+.astro/
+
+# dependencies
+node_modules/
+
+# logs
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+
+
+# environment variables
+.env
+.env.production
+
+# macOS-specific files
+.DS_Store

docs/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

docs/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

docs/README.md

@@ -0,0 +1,18 @@
+# Astro Embed docs
+
+[![Built with Starlight](https://astro.badg.es/v2/built-with-starlight/tiny.svg)](https://starlight.astro.build)
+
+This is the docs website for Astro Embed.
+
+Content can be found in [`src/content/docs/`](./src/content/docs/).
+
+## 🧞 Commands
+
+All commands are run from the root of the project, from a terminal:
+
+| Command           | Action                                       |
+| :---------------- | :------------------------------------------- |
+| `npm install`     | Installs dependencies                        |
+| `npm run dev`     | Starts local dev server at `localhost:4321`  |
+| `npm run build`   | Build your production site to `./dist/`      |
+| `npm run preview` | Preview your build locally, before deploying |

docs/astro.config.mjs

@@ -0,0 +1,36 @@
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import embeds from 'astro-embed/integration';
+
+// https://astro.build/config
+export default defineConfig({
+	site: 'https://astro-embed.netlify.app/',
+	integrations: [
+		starlight({
+			title: 'Astro Embed',
+			logo: {
+				light: './src/assets/logo-light.svg',
+				dark: './src/assets/logo-dark.svg',
+				replacesTitle: true,
+			},
+			social: {
+				github: 'https://github.com/delucis/astro-embed',
+			},
+			sidebar: [
+				{
+					label: 'Getting started',
+					link: '/getting-started/',
+				},
+				{
+					label: 'Components',
+					autogenerate: { directory: 'components' },
+				},
+			],
+			customCss: ['./src/assets/theme.css'],
+			components: {
+				Head: './src/overrides/Head.astro',
+			},
+		}),
+		embeds(),
+	],
+});

docs/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "docs",
+  "type": "module",
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
+  },
+  "dependencies": {
+    "@astrojs/starlight": "^0.21.2",
+    "astro": "^4.5.12",
+    "astro-og-canvas": "^0.4.2",
+    "sharp": "^0.32.5",
+    "starlight-package-managers": "^0.4.0"
+  }
+}

docs/src/assets/theme.css

@@ -0,0 +1,44 @@
+/* Dark mode colors. */
+:root {
+	--sl-color-accent-low: #36113e;
+	--sl-color-accent: #a400c0;
+	--sl-color-accent-high: #e3b6ed;
+	--sl-color-white: #ffffff;
+	--sl-color-gray-1: #efecf2;
+	--sl-color-gray-2: #c3c0c7;
+	--sl-color-gray-3: #8e8996;
+	--sl-color-gray-4: #5b5561;
+	--sl-color-gray-5: #3a3641;
+	--sl-color-gray-6: #29242f;
+	--sl-color-black: #19171c;
+
+	--tc-border-color: var(--sl-color-gray-5);
+}
+/* Light mode colors. */
+:root[data-theme='light'] {
+	--sl-color-accent-low: #ebc9f3;
+	--sl-color-accent: #a700c3;
+	--sl-color-accent-high: #4e0e5b;
+	--sl-color-white: #19171c;
+	--sl-color-gray-1: #29242f;
+	--sl-color-gray-2: #3a3641;
+	--sl-color-gray-3: #5b5561;
+	--sl-color-gray-4: #8e8996;
+	--sl-color-gray-5: #c3c0c7;
+	--sl-color-gray-6: #efecf2;
+	--sl-color-gray-7: #f7f6f8;
+	--sl-color-black: #ffffff;
+}
+
+main {
+	font-family: Charter, 'Bitstream Charter', 'Sitka Text', Cambria, serif;
+	text-underline-offset: 0.25em;
+}
+
+.hero .tagline {
+	text-wrap: balance;
+}
+
+.hero > img {
+	filter: drop-shadow(0 0 8rem var(--sl-color-accent));
+}

docs/src/content/config.ts

@@ -0,0 +1,13 @@
+import { defineCollection, z } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({
+		schema: docsSchema({
+			extend: z.object({
+				// Require a description for every page.
+				description: z.string(),
+			}),
+		}),
+	}),
+};

docs/src/content/docs/components/_examples/StyledTweet.astro

@@ -0,0 +1,22 @@
+---
+import { Tweet } from '@astro-community/astro-embed-twitter';
+---
+
+<div class="styled-tweet">
+	<Tweet id="https://twitter.com/astrodotbuild/status/1767605560671969619" />
+</div>
+
+<style>
+	.styled-tweet :global(.twitter-tweet) {
+		background: floralwhite;
+		color: darkblue;
+		font-family: cursive;
+		font-size: 1.25rem;
+		border: 0;
+	}
+
+	.styled-tweet :global(.twitter-tweet a) {
+		color: purple;
+		font-weight: bold;
+	}
+</style>

docs/src/content/docs/components/twitter.mdx

@@ -0,0 +1,111 @@
+---
+title: Tweet
+description: Learn how to use the Astro Embed Tweet component to embed Twitter posts in your website
+---
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+import { Tweet } from '@astro-community/astro-embed-twitter';
+
+The `<Tweet>` component embeds posts to Twitter (also known as X) in Astro projects.
+
+## Usage
+
+The `<Tweet>` component generates a static Twitter card for a single Tweet using [Twitter’s oEmbed API](https://developer.twitter.com/en/docs/twitter-for-websites/oembed-api).
+
+<Tabs>
+<TabItem label="Astro" icon="astro">
+```astro
+---
+import { Tweet } from 'astro-embed';
+---
+
+<Tweet id="https://twitter.com/astrodotbuild/status/1511750228428435457" />
+```
+</TabItem>
+<TabItem label="MDX" icon="seti:markdown">
+```mdx
+import { Tweet } from 'astro-embed';
+
+<Tweet id="https://twitter.com/astrodotbuild/status/1511750228428435457" />
+```
+</TabItem>
+</Tabs>
+
+The above code produces the following result:
+
+<div>
+	<Tweet id="https://twitter.com/astrodotbuild/status/1511750228428435457" />
+</div>
+
+:::note
+The `<Tweet>` component styles are intentionally minimal.
+They will match the font styles of your surrounding content. See [“Styling the Tweet component”](#styling-the-tweet-component) below for more details.
+:::
+
+## Loading Twitter’s JavaScript
+
+By design, `<Tweet>` is a minimal component and loads zero JavaScript, only rendering some static HTML content.
+However, this HTML is compatible with Twitter’s widget system.
+Loading Twitter‘s large bundle of widget JavaScript will convert each `<Tweet>` into an interactive embed.
+
+You can do this by including the following `<script>` tag in your Astro layout file:
+
+```html
+<script async src="https://platform.twitter.com/widgets.js"></script>
+```
+
+[See an example of `<Tweet>` with Twitter‘s JavaScript](/examples/tweet-with-js/)
+
+## Styling the Tweet component
+
+By default the `<Tweet>` card has minimal styling, which should adapt to your site’s font settings etc.
+
+You can customise it by targeting the `.twitter-tweet` class, for example:
+
+```css
+.twitter-tweet {
+	background: floralwhite;
+	color: darkblue;
+	font-family: cursive;
+	font-size: 1.25rem;
+	border: 0;
+}
+
+.twitter-tweet a {
+	color: purple;
+	font-weight: bold;
+}
+```
+
+The above styles would render `<Tweet>` like this:
+
+import StyledTweet from './_examples/StyledTweet.astro';
+
+<StyledTweet />
+
+### Custom properties API
+
+The `<Tweet>` component also supports a minimal API for controlling its styles by setting some CSS custom properties.
+
+```css
+:root {
+	/* Control the padding inside the Tweet card. */
+	--tc-padding: 1em;
+	/* Set the border color of the Tweet card. */
+	--tc-border-color: #cfd9de;
+}
+```
+
+## Standalone installation
+
+If you only need the `<Tweet>` 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-twitter" />
+
+The `<Tweet>` component can then be imported as:
+
+```js
+import { Tweet } from '@astro-community/astro-embed-twitter';
+```