Skip to content

Commit 548bbce

Browse files
danieljcafonsodanieljcafonso
authored
feat: add solid meta docs (#670)
1 parent 7c94149 commit 548bbce

19 files changed

+391
-14
lines changed

‎app.config.ts

Lines changed: 5 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -17,8 +17,10 @@ import tree from "./.solid/tree";
1717
import entries from "./.solid/flat-entries";
1818
import solidstartEntries from "./.solid/solid-start-flat-entries";
1919
import solidrouterEntries from "./.solid/solid-router-flat-entries";
20+
import solidMetaEntries from "./.solid/solid-meta-flat-entries";
2021
import solidrouterTree from "./.solid/solid-router-tree";
2122
import solidStartTree from "./.solid/solid-start-tree";
23+
import solidMetaTree from "./.solid/solid-meta-tree";
2224

2325
function docsData() {
2426
const virtualModuleId = "solid:collection";
@@ -37,9 +39,11 @@ function docsData() {
3739
export const coreEntries = ${JSON.stringify(entries, null, 2)}
3840
export const routerEntries = ${JSON.stringify(solidrouterEntries, null, 2)}
3941
export const startEntries = ${JSON.stringify(solidstartEntries, null, 2)}
42+
export const metaEntries = ${JSON.stringify(solidMetaEntries, null, 2)}
4043
export const coreTree = ${JSON.stringify(tree, null, 2)}
4144
export const routerTree = ${JSON.stringify(solidrouterTree, null, 2)}
4245
export const startTree = ${JSON.stringify(solidStartTree, null, 2)}
46+
export const metaTree = ${JSON.stringify(solidMetaTree, null, 2)}
4347
`;
4448
}
4549
},
@@ -54,7 +58,7 @@ export default defineConfig({
5458
crawlLinks: true,
5559
autoSubfolderIndex: false,
5660
failOnError: true,
57-
ignore: [/\{\getPath}/],
61+
ignore: [/\{\getPath}/, /.*?emojiSvg\(.*/],
5862
},
5963
},
6064
extensions: ["mdx", "md", "tsx"],

‎global.d.ts

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,20 @@ declare module "solid:collection" {
22
import coreTree from ".solid/tree";
33
import startTree from ".solid/solid-router-tree";
44
import routerTree from ".solid/solid-start-tree";
5+
import metaTree from ".solid/solid-meta-tree";
56
import coreEntries from ".solid/flat-entries";
67
import routerEntries from ".solid/solid-start-flat-entries";
78
import startEntries from ".solid/solid-router-flat-entries";
9+
import metaEntries from ".solid/solid-meta-flat-entries";
810

911
export {
1012
coreEntries,
1113
routerEntries,
1214
startEntries,
15+
metaEntries,
1316
coreTree,
1417
routerTree,
1518
startTree,
19+
metaTree,
1620
};
1721
}

‎scripts/collections/index.mjs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import { createI18nEntries } from "../create-i18n-entries.mjs";
66
import { createI18nTree } from "../create-i18n-tree.mjs";
77

88
export const languages = ["pt-br"];
9-
const projects = ["solid-router", "solid-start"];
9+
const projects = ["solid-router", "solid-start", "solid-meta"];
1010
export const COLLECTIONS_ROOT = "src/routes";
1111

1212
(async () => {

‎src/routes/solid-meta/data.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"title": "root",
3+
"pages": ["index.mdx", "getting-started"]
4+
}

‎src/routes/solid-meta/getting-started/client-setup.mdx

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
---
2+
title: Client setup
3+
order: 2
4+
---
5+
6+
You can inject a tag into the `<head />` by rendering one of the head tag components when necessary.
7+
No special requirements are needed on the client side.
8+
9+
```js
10+
import { MetaProvider, Title, Link, Meta } from "@solidjs/meta";
11+
12+
const App = () => (
13+
<MetaProvider>
14+
<div class="Home">
15+
<Title>Title of page</Title>
16+
<Link rel="canonical" href="http://solidjs.com/" />
17+
<Meta name="example" content="whatever" />
18+
// ...
19+
</div>
20+
</MetaProvider>
21+
);
22+
```

‎src/routes/solid-meta/getting-started/data.json

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{
2+
"title": "Getting Started",
3+
"pages": [
4+
"installation-and-setup.mdx",
5+
"client-setup.mdx",
6+
"server-setup.mdx"
7+
]
8+
}

‎src/routes/solid-meta/getting-started/installation-and-setup.mdx

Lines changed: 64 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,64 @@
1+
---
2+
title: Install and configure
3+
order: 1
4+
---
5+
6+
<Callout title="Prerequisites">
7+
If using Solid `v1.0`, use version `0.27.x` or greater.
8+
For earlier versions (eg. `v0.x`), you must use `v0.26.x`.
9+
</Callout>
10+
11+
## Installation
12+
13+
To get started, install using your preferred package manager.
14+
15+
<TabsCodeBlocks>
16+
<div id="npm">
17+
```bash frame="none"
18+
npm i @solidjs/meta
19+
```
20+
</div>
21+
22+
<div id="yarn">
23+
```bash frame="none"
24+
yarn add @solidjs/meta
25+
```
26+
</div>
27+
28+
<div id="pnpm">
29+
```bash frame="none"
30+
pnpm add @solidjs/meta
31+
```
32+
</div>
33+
</TabsCodeBlocks>
34+
35+
## Setup
36+
37+
1. Wrap your application with [`<MetaProvider />`](/solid-meta/reference/meta/metaprovider)
38+
2. To include head tags within your application, render any of the following:
39+
1. [`<Title />`](/solid-meta/reference/meta/title): Adds the `title` of the page.
40+
2. [`<Meta />`](/solid-meta/reference/meta/meta): Adds extra metadata to the page.
41+
3. [`<Style />`](/solid-meta/reference/meta/style): Adds a `style` element to the page.
42+
4. [`<Link />`](/solid-meta/reference/meta/link): Specifies a relationship between the page and an external resource.
43+
5. [`<Base />`](/solid-meta/reference/meta/base): Specifies the base URL for all relative URLs in the document.
44+
- These components can be used multiple times within the application.
45+
3. If using SolidJS on the server with JSX, no additional configuration is required.
46+
47+
Here is an example of how your code might look after this setup.
48+
```js
49+
import { MetaProvider, Title, Link, Meta } from "@solidjs/meta";
50+
51+
const App = () => (
52+
<MetaProvider>
53+
<div class="Home">
54+
<Title>Title of page</Title>
55+
<Link rel="canonical" href="http://solidjs.com/" />
56+
<Meta name="example" content="whatever" />
57+
</div>
58+
</MetaProvider>
59+
);
60+
```
61+
On the server, tags are collected, and then on the client, server-generated tags are replaced with those rendered on the client side.
62+
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.
63+
64+
However, you can manage asset insertion using `getAssets` from `solid-js/web`.

‎src/routes/solid-meta/getting-started/server-setup.mdx

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,33 @@
1+
---
2+
title: Server setup
3+
order: 3
4+
---
5+
6+
For server setup, wrap your application with [`MetaProvider`](/solid-meta/reference/meta/metaprovider) on the server.
7+
This component uses a `tags[]` array to pass down your head tags as part of your server-rendered payload.
8+
Once rendered on the server, the component updates this array to include the tags.
9+
10+
```js
11+
import { renderToString, getAssets } from "solid-js/web";
12+
import { MetaProvider } from "@solidjs/meta";
13+
import App from "./App";
14+
15+
// ... within the context of a request ...
16+
const app = renderToString(() => (
17+
<MetaProvider>
18+
<App />
19+
</MetaProvider>
20+
));
21+
22+
res.send(`
23+
<!doctype html>
24+
<html>
25+
<head>
26+
${getAssets()}
27+
</head>
28+
<body>
29+
<div id="root">${app}</div>
30+
</body>
31+
</html>
32+
`);
33+
```

‎src/routes/solid-meta/index.mdx

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: Overview
3+
mainNavExclude: true
4+
---
5+
6+
# Overview
7+
8+
Solid Meta offers asynchronous SSR-ready Document Head management for Solid Applications, based on [React Head](https://github.com/tizmagik/react-head)
9+
10+
With Solid Meta, you can define `document.head` tags at any level of your component hierarchy.
11+
This helps you to manage tags conveniently, especially when contextual information for specific tags are buried deep within your component hierarchy.
12+
13+
This library has no dependencies and is designed to seamlessly integrate with asynchronous rendering.

‎src/routes/solid-meta/reference/data.json

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,4 @@
1+
{
2+
"title": "Reference",
3+
"pages": ["meta"]
4+
}

‎src/routes/solid-meta/reference/meta/base.mdx

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
---
2+
title: Base
3+
order: 5
4+
---
5+
6+
`Base` is a component that specifies the base URL for all relative URLs in the document.
7+
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`.
8+
9+
```tsx twoslash
10+
import { Base } from "@solidjs/meta";
11+
12+
<Base target="_blank" href="https://docs.solidjs.com/" />;
13+
```
14+
15+
## Usage
16+
17+
### Adding `base` tag
18+
19+
```tsx twoslash
20+
import { MetaProvider, Base } from "@solidjs/meta";
21+
22+
export default function Root() {
23+
return (
24+
<MetaProvider>
25+
<Base target="_blank" href="https://docs.solidjs.com/" />
26+
</MetaProvider>
27+
);
28+
}
29+
```

‎src/routes/solid-meta/reference/meta/data.json

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
"title": "Meta Reference",
3+
"pages": [
4+
"title.mdx",
5+
"link.mdx",
6+
"meta.mdx",
7+
"style.mdx",
8+
"base.mdx",
9+
"metaprovider.mdx"
10+
]
11+
}

‎src/routes/solid-meta/reference/meta/link.mdx

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
---
2+
title: Link
3+
order: 2
4+
---
5+
6+
The Link component establishes a connection between the page and an external resource.
7+
Commonly, this is used for linking stylesheets and other associations.
8+
9+
This component renders a [`link`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/link) element within the document's `<head>`.
10+
11+
```tsx twoslash
12+
import { Link } from "@solidjs/meta";
13+
<Link rel="icon" href="/favicon.ico" />;
14+
```
15+
16+
## Usage
17+
18+
### Adding a favicon
19+
20+
To add a favicon in an app, `<Link>` can be used to point to the asset:
21+
22+
```tsx twoslash
23+
import { MetaProvider, Link } from "@solidjs/meta";
24+
25+
export default function Root() {
26+
return (
27+
<MetaProvider>
28+
<Link rel="icon" href="/favicon.ico" />
29+
</MetaProvider>
30+
);
31+
}
32+
```
33+
34+
### Using an emoji as a favicon
35+
36+
To use an emoji as a favicon, first create a function that returns a data URI containing an SVG image:
37+
38+
```jsx
39+
const emojiSvg = (emoji) => {
40+
return (
41+
`data:image/svg+xml` +
42+
`<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>`
43+
);
44+
};
45+
```
46+
47+
Following this, include the emoji as an argument within that function in the `href` property of the Link component:
48+
49+
```jsx
50+
import { MetaProvider, Link } from "@solidjs/meta";
51+
52+
export default function Root() {
53+
return (
54+
<MetaProvider>
55+
<Link rel="icon" href={emojiSvg("😎")} />
56+
</MetaProvider>
57+
);
58+
}
59+
```

‎src/routes/solid-meta/reference/meta/meta.mdx

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,34 @@
1+
---
2+
title: Meta
3+
order: 3
4+
---
5+
6+
The `<Meta>` component represents metadata that cannot be represented by other HTML elements.
7+
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.
8+
9+
```tsx twoslash
10+
import { Meta } from "@solidjs/meta";
11+
12+
<Meta name="description" content="My site description" />;
13+
```
14+
15+
16+
`Meta` components can be placed in the [`MetaProvider`](/solid-meta/reference/meta/metaprovider) or added throughout the application for additional metadata or override parents.
17+
`Meta` tags are considered the same and will be overridden if `name` attributes match.
18+
## Usage
19+
20+
### Adding `meta` tag
21+
22+
```tsx twoslash {6-8}
23+
import { MetaProvider, Meta } from "@solidjs/meta";
24+
25+
export default function Root() {
26+
return (
27+
<MetaProvider>
28+
<Meta charset="utf-8" />
29+
<Meta name="viewport" content="width=device-width, initial-scale=1" />
30+
<Meta name="description" content="Hacker News Clone built with Solid" />
31+
</MetaProvider>
32+
);
33+
}
34+
```

‎src/routes/solid-meta/reference/meta/metaprovider.mdx

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
---
2+
title: MetaProvider
3+
order: 6
4+
---
5+
6+
`MetaProvider` is a parent component responsible for wrapping all the metadata components.
7+
All components that are contained within this will be added to the application `<head/>`
8+
9+
```tsx twoslash
10+
import { MetaProvider } from "@solidjs/meta";
11+
12+
<MetaProvider>// add meta components</MetaProvider>;
13+
```

0 commit comments

Comments
 (0)