diff --git a/app.config.ts b/app.config.ts index b5f4e06e4..aebf26861 100644 --- 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 index 1530e577e..fd182f46a 100644 --- 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 index ffc3f40c9..9edb96298 100644 --- 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 new file mode 100644 index 000000000..c1b741048 --- /dev/null +++ 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 new file mode 100644 index 000000000..32bc50c83 --- /dev/null +++ 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 `` 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 = () => ( + +
+ Title of page + + + // ... +
+ +); +``` diff --git a/src/routes/solid-meta/getting-started/data.json b/src/routes/solid-meta/getting-started/data.json new file mode 100644 index 000000000..43b423e96 --- /dev/null +++ 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 new file mode 100644 index 000000000..765260b83 --- /dev/null +++ b/src/routes/solid-meta/getting-started/installation-and-setup.mdx @@ -0,0 +1,64 @@ +--- +title: Install and configure +order: 1 +--- + + +If using Solid `v1.0`, use version `0.27.x` or greater. +For earlier versions (eg. `v0.x`), you must use `v0.26.x`. + + +## Installation + +To get started, install using your preferred package manager. + + +
+```bash frame="none" +npm i @solidjs/meta +``` +
+ +
+```bash frame="none" +yarn add @solidjs/meta +``` +
+ +
+```bash frame="none" +pnpm add @solidjs/meta +``` +
+ + +## Setup + +1. Wrap your application with [``](/solid-meta/reference/meta/metaprovider) +2. To include head tags within your application, render any of the following: + 1. [``](/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 + + + + +); +``` +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`. \ No newline at end of file diff --git a/src/routes/solid-meta/getting-started/server-setup.mdx b/src/routes/solid-meta/getting-started/server-setup.mdx new file mode 100644 index 000000000..19a0bc691 --- /dev/null +++ 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(() => ( + + + +)); + +res.send(` + + + + ${getAssets()} + + +
${app}
+ + +`); +``` diff --git a/src/routes/solid-meta/index.mdx b/src/routes/solid-meta/index.mdx new file mode 100644 index 000000000..3cee39418 --- /dev/null +++ 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 new file mode 100644 index 000000000..d2a4c819f --- /dev/null +++ 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 new file mode 100644 index 000000000..f0be6b9f9 --- /dev/null +++ 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"; + +; +``` + +## Usage + +### Adding `base` tag + +```tsx twoslash +import { MetaProvider, Base } from "@solidjs/meta"; + +export default function Root() { + return ( + + + + ); +} +``` \ No newline at end of file diff --git a/src/routes/solid-meta/reference/meta/data.json b/src/routes/solid-meta/reference/meta/data.json new file mode 100644 index 000000000..27729436f --- /dev/null +++ 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 new file mode 100644 index 000000000..f50971362 --- /dev/null +++ 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 ``. + +```tsx twoslash +import { Link } from "@solidjs/meta"; +; +``` + +## Usage + +### Adding a favicon + +To add a favicon in an app, `` can be used to point to the asset: + +```tsx twoslash +import { MetaProvider, Link } from "@solidjs/meta"; + +export default function Root() { + return ( + + + + ); +} +``` + +### 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` + + `${emoji}` + ); +}; +``` + +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 ( + + + + ); +} +``` \ No newline at end of file diff --git a/src/routes/solid-meta/reference/meta/meta.mdx b/src/routes/solid-meta/reference/meta/meta.mdx new file mode 100644 index 000000000..13e077da5 --- /dev/null +++ b/src/routes/solid-meta/reference/meta/meta.mdx @@ -0,0 +1,34 @@ +--- +title: Meta +order: 3 +--- + +The `` 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` 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 ( + + + + + + ); +} +``` \ No newline at end of file diff --git a/src/routes/solid-meta/reference/meta/metaprovider.mdx b/src/routes/solid-meta/reference/meta/metaprovider.mdx new file mode 100644 index 000000000..d9932fa27 --- /dev/null +++ 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 `` + +```tsx twoslash +import { MetaProvider } from "@solidjs/meta"; + +// add meta components; +``` \ No newline at end of file diff --git a/src/routes/solid-meta/reference/meta/style.mdx b/src/routes/solid-meta/reference/meta/style.mdx new file mode 100644 index 000000000..187b44a83 --- /dev/null +++ b/src/routes/solid-meta/reference/meta/style.mdx @@ -0,0 +1,45 @@ +--- +title: Style +order: 4 +--- + +`Style` is a component that adds the [`style`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/style) element to your document's `head`. + +```tsx twoslash +import { Style } from "@solidjs/meta"; + +; +``` + +## Usage + +### Adding `style` tag + +The `Style` component can add CSS to style elements within your application. +It is recommended to add styles in an external stylesheet and use a `Link` instead, rather than using this component, however. + + + Styles within the `Style` component are not scoped. + + +```tsx twoslash +import { MetaProvider, Style } from "@solidjs/meta"; + +export default function Root() { + return ( + + + + ); +} +``` \ No newline at end of file diff --git a/src/routes/solid-meta/reference/meta/title.mdx b/src/routes/solid-meta/reference/meta/title.mdx new file mode 100644 index 000000000..3c0786c64 --- /dev/null +++ b/src/routes/solid-meta/reference/meta/title.mdx @@ -0,0 +1,27 @@ +--- +title: Title +order: 1 +--- + +`Title` is a component that renders the [`title`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/title) element. +This will render the title of the page in the browser tab. + +```tsx twoslash +import { Title } from "@solidjs/meta"; +My Site; +``` + +## Usage + +### Setting the title for your site + +```tsx twoslash filename="root.tsx" {5} +import { MetaProvider, Title } from "@solidjs/meta"; +export default function Root() { + return ( + + Default Application Title + + ); +} +``` \ No newline at end of file diff --git a/src/ui/layout.tsx b/src/ui/layout.tsx index 4e1d509e2..5af74f227 100644 --- a/src/ui/layout.tsx +++ b/src/ui/layout.tsx @@ -17,6 +17,8 @@ import { coreEntries, startEntries, routerEntries, + metaTree, + metaEntries, } from "solid:collection"; import { PathMatch } from "@solidjs/router/dist/types"; @@ -28,6 +30,8 @@ function getDefaultTree(project: (typeof PROJECTS)[number]) { return routerTree; case "solid-start": return startTree; + case "solid-meta": + return metaTree; default: return coreTree; } @@ -39,6 +43,8 @@ function getDefaultEntries(project: (typeof PROJECTS)[number]) { return routerEntries; case "solid-start": return startEntries; + case "solid-meta": + return metaEntries; default: return coreEntries; } diff --git a/src/ui/layout/main-header.tsx b/src/ui/layout/main-header.tsx index 480fabee7..3c238351c 100644 --- a/src/ui/layout/main-header.tsx +++ b/src/ui/layout/main-header.tsx @@ -31,11 +31,11 @@ interface NavProps { export function MainHeader(props: NavProps) { const [isScrolled, setIsScrolled] = createSignal(false); const notSolidCore = useMatch(() => "/:project/*", { - project: ["solid-router", "solid-start", "solid-metadata"], + project: ["solid-router", "solid-start", "solid-meta"], }); const translatedLocale = useMatch(() => "/:locale/:project/*", { locale: SUPPORTED_LOCALES, - project: ["solid-router", "solid-start", "solid-metadata"], + project: ["solid-router", "solid-start", "solid-meta"], }); if (!isServer) { @@ -107,17 +107,14 @@ export function MainHeader(props: NavProps) {
  • - + Meta - - - soon - - - +