feat: add solid meta docs (#670)

solidjs · Apr 23, 2024 · 548bbce · 548bbce
1 parent 7c94149
commit 548bbce
Show file tree

Hide file tree

Showing 19 changed files with 391 additions and 14 deletions.
diff --git a/app.config.ts b/app.config.ts
@@ -17,8 +17,10 @@ import tree from "./.solid/tree";
 import entries from "./.solid/flat-entries";
 import solidstartEntries from "./.solid/solid-start-flat-entries";
 import solidrouterEntries from "./.solid/solid-router-flat-entries";
+import solidMetaEntries from "./.solid/solid-meta-flat-entries";
 import solidrouterTree from "./.solid/solid-router-tree";
 import solidStartTree from "./.solid/solid-start-tree";
+import solidMetaTree from "./.solid/solid-meta-tree";
 
 function docsData() {
 	const virtualModuleId = "solid:collection";
@@ -37,9 +39,11 @@ function docsData() {
 				export const coreEntries = ${JSON.stringify(entries, null, 2)}
 				export const routerEntries = ${JSON.stringify(solidrouterEntries, null, 2)}
 				export const startEntries = ${JSON.stringify(solidstartEntries, null, 2)}
+				export const metaEntries = ${JSON.stringify(solidMetaEntries, null, 2)}
 				export const coreTree = ${JSON.stringify(tree, null, 2)}
 				export const routerTree = ${JSON.stringify(solidrouterTree, null, 2)}
 				export const startTree = ${JSON.stringify(solidStartTree, null, 2)}
+				export const metaTree = ${JSON.stringify(solidMetaTree, null, 2)}
 				`;
 			}
 		},
@@ -54,7 +58,7 @@ export default defineConfig({
 			crawlLinks: true,
 			autoSubfolderIndex: false,
 			failOnError: true,
-			ignore: [/\{\getPath}/],
+			ignore: [/\{\getPath}/, /.*?emojiSvg\(.*/],
 		},
 	},
 	extensions: ["mdx", "md", "tsx"],

diff --git a/global.d.ts b/global.d.ts
@@ -2,16 +2,20 @@ declare module "solid:collection" {
 	import coreTree from ".solid/tree";
 	import startTree from ".solid/solid-router-tree";
 	import routerTree from ".solid/solid-start-tree";
+	import metaTree from ".solid/solid-meta-tree";
 	import coreEntries from ".solid/flat-entries";
 	import routerEntries from ".solid/solid-start-flat-entries";
 	import startEntries from ".solid/solid-router-flat-entries";
+	import metaEntries from ".solid/solid-meta-flat-entries";
 
 	export {
 		coreEntries,
 		routerEntries,
 		startEntries,
+		metaEntries,
 		coreTree,
 		routerTree,
 		startTree,
+		metaTree,
 	};
 }
diff --git a/scripts/collections/index.mjs b/scripts/collections/index.mjs
@@ -6,7 +6,7 @@ import { createI18nEntries } from "../create-i18n-entries.mjs";
 import { createI18nTree } from "../create-i18n-tree.mjs";
 
 export const languages = ["pt-br"];
-const projects = ["solid-router", "solid-start"];
+const projects = ["solid-router", "solid-start", "solid-meta"];
 export const COLLECTIONS_ROOT = "src/routes";
 
 (async () => {

diff --git a/src/routes/solid-meta/data.json b/src/routes/solid-meta/data.json
@@ -0,0 +1,4 @@
+{
+	"title": "root",
+	"pages": ["index.mdx", "getting-started"]
+}
diff --git a/src/routes/solid-meta/getting-started/client-setup.mdx b/src/routes/solid-meta/getting-started/client-setup.mdx
@@ -0,0 +1,22 @@
+---
+title: Client setup
+order: 2
+---
+
+You can inject a tag into the `<head />` by rendering one of the head tag components when necessary.
+No special requirements are needed on the client side.
+
+```js
+import { MetaProvider, Title, Link, Meta } from "@solidjs/meta";
+
+const App = () => (
+	<MetaProvider>
+		<div class="Home">
+			<Title>Title of page</Title>
+			<Link rel="canonical" href="http://solidjs.com/" />
+			<Meta name="example" content="whatever" />
+			// ...
+		</div>
+	</MetaProvider>
+);
+```
diff --git a/src/routes/solid-meta/getting-started/data.json b/src/routes/solid-meta/getting-started/data.json
@@ -0,0 +1,8 @@
+{
+	"title": "Getting Started",
+	"pages": [
+		"installation-and-setup.mdx",
+		"client-setup.mdx",
+		"server-setup.mdx"
+	]
+}
diff --git a/src/routes/solid-meta/getting-started/installation-and-setup.mdx b/src/routes/solid-meta/getting-started/installation-and-setup.mdx
@@ -0,0 +1,64 @@
+---
+title: Install and configure
+order: 1
+---
+
+<Callout title="Prerequisites">
+If using Solid `v1.0`, use version `0.27.x` or greater.
+For earlier versions (eg. `v0.x`), you must use `v0.26.x`.
+</Callout>
+
+## Installation
+
+To get started, install using your preferred package manager.
+
+<TabsCodeBlocks>
+<div id="npm">
+```bash frame="none"
+npm i @solidjs/meta
+```
+</div>
+
+<div id="yarn">
+```bash frame="none"
+yarn add @solidjs/meta
+```
+</div>
+
+<div id="pnpm">
+```bash frame="none"
+pnpm add @solidjs/meta
+```
+</div>
+</TabsCodeBlocks>
+
+## Setup
+
+1. Wrap your application with [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider)
+2. To include head tags within your application, render any of the following:
+    1. [`<Title />`](/solid-meta/reference/meta/title): Adds the `title` of the page. 
+    2. [`<Meta />`](/solid-meta/reference/meta/meta): Adds extra metadata to the page.
+    3. [`<Style />`](/solid-meta/reference/meta/style): Adds a `style` element to the page.
+    4. [`<Link />`](/solid-meta/reference/meta/link): Specifies a relationship between the page and an external resource.
+    5. [`<Base />`](/solid-meta/reference/meta/base): Specifies the base URL for all relative URLs in the document.
+- These components can be used multiple times within the application.
+3.  If using SolidJS on the server with JSX, no additional configuration is required. 
+
+Here is an example of how your code might look after this setup.
+```js
+import { MetaProvider, Title, Link, Meta } from "@solidjs/meta";
+
+const App = () => (
+	<MetaProvider>
+		<div class="Home">
+			<Title>Title of page</Title>
+			<Link rel="canonical" href="http://solidjs.com/" />
+			<Meta name="example" content="whatever" />
+		</div>
+	</MetaProvider>
+);
+```
+On the server, tags are collected, and then on the client, server-generated tags are replaced with those rendered on the client side.
+This process is important for maintaining the expected behavior, such as Single Page Applications (SPAs) when pages load that require changes to the head tags.
+
+However, you can manage asset insertion using `getAssets` from `solid-js/web`. 
diff --git a/src/routes/solid-meta/getting-started/server-setup.mdx b/src/routes/solid-meta/getting-started/server-setup.mdx
@@ -0,0 +1,33 @@
+---
+title: Server setup
+order: 3
+---
+
+For server setup, wrap your application with [`MetaProvider`](/solid-meta/reference/meta/metaprovider) on the server.
+This component uses a `tags[]` array to pass down your head tags as part of your server-rendered payload.
+Once rendered on the server, the component updates this array to include the tags.
+
+```js
+import { renderToString, getAssets } from "solid-js/web";
+import { MetaProvider } from "@solidjs/meta";
+import App from "./App";
+
+// ... within the context of a request ...
+const app = renderToString(() => (
+	<MetaProvider>
+		<App />
+	</MetaProvider>
+));
+
+res.send(`
+  <!doctype html>
+  <html>
+    <head>
+      ${getAssets()}
+    </head>
+    <body>
+      <div id="root">${app}</div>
+    </body>
+  </html>
+`);
+```
diff --git a/src/routes/solid-meta/index.mdx b/src/routes/solid-meta/index.mdx
@@ -0,0 +1,13 @@
+---
+title: Overview
+mainNavExclude: true
+---
+
+# Overview
+
+Solid Meta offers asynchronous SSR-ready Document Head management for Solid Applications, based on [React Head](https://github.com/tizmagik/react-head)
+
+With Solid Meta, you can define `document.head` tags at any level of your component hierarchy.
+This helps you to manage tags conveniently, especially when contextual information for specific tags are buried deep within your component hierarchy.
+
+This library has no dependencies and is designed to seamlessly integrate with asynchronous rendering.
diff --git a/src/routes/solid-meta/reference/data.json b/src/routes/solid-meta/reference/data.json
@@ -0,0 +1,4 @@
+{
+	"title": "Reference",
+	"pages": ["meta"]
+}
diff --git a/src/routes/solid-meta/reference/meta/base.mdx b/src/routes/solid-meta/reference/meta/base.mdx
@@ -0,0 +1,29 @@
+---
+title: Base
+order: 5
+---
+
+`Base` is a component that specifies the base URL for all relative URLs in the document.
+This provides a way to define the [`base`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/base) element of your document's `head`.
+
+```tsx twoslash
+import { Base } from "@solidjs/meta";
+
+<Base target="_blank" href="https://docs.solidjs.com/" />;
+```
+
+## Usage
+
+### Adding `base` tag
+
+```tsx twoslash
+import { MetaProvider, Base } from "@solidjs/meta";
+
+export default function Root() {
+	return (
+		<MetaProvider>
+			<Base target="_blank" href="https://docs.solidjs.com/" />
+		</MetaProvider>
+	);
+}
+```
diff --git a/src/routes/solid-meta/reference/meta/data.json b/src/routes/solid-meta/reference/meta/data.json
@@ -0,0 +1,11 @@
+{
+	"title": "Meta Reference",
+	"pages": [
+		"title.mdx",
+		"link.mdx",
+		"meta.mdx",
+		"style.mdx",
+		"base.mdx",
+		"metaprovider.mdx"
+	]
+}
diff --git a/src/routes/solid-meta/reference/meta/link.mdx b/src/routes/solid-meta/reference/meta/link.mdx
@@ -0,0 +1,59 @@
+---
+title: Link
+order: 2
+---
+
+The Link component establishes a connection between the page and an external resource.
+Commonly, this is used for linking stylesheets and other associations.
+
+This component renders a [`link`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element within the document's `<head>`.
+
+```tsx twoslash
+import { Link } from "@solidjs/meta";
+<Link rel="icon" href="/favicon.ico" />;
+```
+
+## Usage
+
+### Adding a favicon
+
+To add a favicon in an app, `<Link>` can be used to point to the asset:
+
+```tsx twoslash
+import { MetaProvider, Link } from "@solidjs/meta";
+
+export default function Root() {
+	return (
+		<MetaProvider>
+			<Link rel="icon" href="/favicon.ico" />
+		</MetaProvider>
+	);
+}
+```
+
+### Using an emoji as a favicon
+
+To use an emoji as a favicon, first create a function that returns a data URI containing an SVG image:
+
+```jsx
+const emojiSvg = (emoji) => {
+	return (
+		`data:image/svg+xml` +
+		`<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text y=%22.9em%22 font-size=%2290%22>${emoji}</text></svg>`
+	);
+};
+```
+
+Following this, include the emoji as an argument within that function in the `href` property of the Link component:
+
+```jsx
+import { MetaProvider, Link } from "@solidjs/meta";
+
+export default function Root() {
+	return (
+		<MetaProvider>
+			<Link rel="icon" href={emojiSvg("😎")} />
+		</MetaProvider>
+	);
+}
+```
diff --git a/src/routes/solid-meta/reference/meta/meta.mdx b/src/routes/solid-meta/reference/meta/meta.mdx
@@ -0,0 +1,34 @@
+---
+title: Meta
+order: 3
+---
+
+The `<Meta>` component represents metadata that cannot be represented by other HTML elements.
+It is a wrapper for the native [`meta`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/meta) element and has the same properties.
+
+```tsx twoslash
+import { Meta } from "@solidjs/meta";
+
+<Meta name="description" content="My site description" />;
+```
+
+
+`Meta` components can be placed in the [`MetaProvider`](/solid-meta/reference/meta/metaprovider) or added throughout the application for additional metadata or override parents.
+`Meta` tags are considered the same and will be overridden if `name` attributes match.
+## Usage
+
+### Adding `meta` tag
+
+```tsx twoslash {6-8}
+import { MetaProvider, Meta } from "@solidjs/meta";
+
+export default function Root() {
+	return (
+		<MetaProvider>
+			<Meta charset="utf-8" />
+			<Meta name="viewport" content="width=device-width, initial-scale=1" />
+			<Meta name="description" content="Hacker News Clone built with Solid" />
+		</MetaProvider>
+	);
+}
+```
diff --git a/src/routes/solid-meta/reference/meta/metaprovider.mdx b/src/routes/solid-meta/reference/meta/metaprovider.mdx
@@ -0,0 +1,13 @@
+---
+title: MetaProvider
+order: 6
+---
+
+`MetaProvider` is a parent component responsible for wrapping all the metadata components.
+All components that are contained within this will be added to the application `<head/>`
+
+```tsx twoslash
+import { MetaProvider } from "@solidjs/meta";
+
+<MetaProvider>// add meta components</MetaProvider>;
+```