@shoalrun/cli 0.1.0-alpha.12 → 0.1.0-alpha.13

package/agent-docs/publish/seo.sections/related-reading.md

@@ -0,0 +1,28 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/seo.md)
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## Related reading
+
+No matching documents.

package/agent-docs/publish/seo.sections/set-the-public-address.md

@@ -0,0 +1,36 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/seo.md)
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## Set the public address
+
+Put the address readers actually use in `site.origin`. This is where crawlers will fetch the page and its image:
+
+```yaml title="docs.config.yaml"
+site:
+  title: Acme API docs
+  origin: https://docs.acme.com
+```
+
+Check the domain in the built `og:image` URL. A page may display in a browser while its social preview cannot load an image from that domain. Preview deployments behind sign-in cannot be unfurled by a public crawler. [Publish on Vercel](https://www.shoalrun.com/publish/vercel.md) explains the production and preview origins for this site's build.

package/agent-docs/publish/seo.sections/what-agents-receive.md

@@ -0,0 +1,28 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/seo.md)
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## What agents receive
+
+The social tags are in HTML, and each generated share card is a public PNG. Agents reading Markdown get the authored title, body, and fields published by your [Markdown metadata settings](https://www.shoalrun.com/author/markdown-metadata.md). The Markdown body does not contain HTML meta tags. `documents.json` and `search-index.json` list the published page and its routes. Changing `seo.title` or the share image does not replace a clear page title or summary for agents that use the Markdown and search index. The [agent-friendly documentation guide](https://www.shoalrun.com/publish/agent-friendliness.md) explains how these public files differ from the documentation bundle shipped inside Shoalrun's CLI.

package/agent-docs/publish/seo.sections/what-the-build-adds.md

@@ -0,0 +1,42 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/seo.md)
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## What the build adds
+
+The build derives these metadata and discovery outputs from your site and page settings.
+
+| Output                                     | Default source                                                       |
+| ------------------------------------------ | -------------------------------------------------------------------- |
+| HTML `<title>`                             | `seo.title`, then page `title`                                       |
+| HTML `name="description"`                  | `seo.description`, then configured HTML description                  |
+| `og:title` and `twitter:title`             | Browser title, with `site.title` added for short titles when it fits |
+| `og:description` and `twitter:description` | Selected social description, falling back to the page `summary`      |
+| `og:url`                                   | `site.origin` plus the published page route                          |
+| Canonical URL                              | `site.origin` plus the published page route                          |
+| XML sitemap `lastmod`                      | Page `updated`, then optional `site.updated`                         |
+| `og:image` and `twitter:image`             | Absolute URL of that page's share image                              |
+| `twitter:card`                             | `summary_large_image` when a share image exists                      |
+
+The default image is a 1200×630 PNG with the page type, title, summary, site name, and URL. [Share images and favicon](https://www.shoalrun.com/styling/share-images.md) shows how to replace a page image or the site-wide design. Turning off share images removes image tags on pages without their own image.

package/agent-docs/publish/seo.sections/write-the-page-title-and-summary.md

@@ -0,0 +1,43 @@
+---
+id: guide.seo
+title: SEO and social previews
+summary: Give each page a useful title and summary, generate share cards, and
+  verify public preview URLs.
+type: how-to
+area: appearance
+subarea: appearance-branding
+canonical: /publish/seo
+---
+
+# SEO and social previews
+
+> Documentation index: [llms.min.txt](https://www.shoalrun.com/llms.min.txt) · Document manifest: [documents.json](https://www.shoalrun.com/documents.json)
+
+Navigation section: [Docs](https://www.shoalrun.com/.well-known/shoalrun/navigation/docs-50f26fe22670.txt) (ID: docs). [All sections and pages](https://www.shoalrun.com/llms.min.txt)
+
+Breadcrumbs: [Docs](https://www.shoalrun.com/what-is-shoalrun.md) > Publish and maintain > SEO and social previews
+
+**Updated: 2026-10-29.**
+
+Parent page: [Full Markdown page](/publish/seo.md)
+
+When someone shares a docs link, Slack and other services fetch the page's HTML and look for a title, description, and image. Shoalrun writes these tags at build time from page metadata and can generate a share image for every page. Start with a clear page `title` and a one-sentence `summary`; you do not need to hand-write Open Graph or Twitter tags.
+
+## Write the page title and summary
+
+```yaml title="content/start.mdx (frontmatter)"
+title: Getting started
+summary: Create your first project and make a request.
+```
+
+The title becomes the page heading and browser title. The summary is the default preview description and appears on the generated share image. For short titles, Shoalrun adds `site.title` to the Open Graph and Twitter titles when the result fits within 70 characters. The browser title and page heading remain unchanged.
+
+If a page needs a different browser and social title, or a different description, use `seo.title` and `seo.description` in its [frontmatter](https://www.shoalrun.com/author/frontmatter.md):
+
+```yaml
+seo:
+  title: Getting started with Acme API
+  description: Create a project, choose a credential, and make your first request.
+```
+
+`seo.title` sets the exact browser and social title; it skips the automatic site-name suffix. `seo.description` sets the browser and social description unless the page selects a separate `displayText.socialCard`. The generated image uses the same selected description, so its copy agrees with the tags. You can configure the text choices site-wide under `outputs.text`; see [text surfaces](https://www.shoalrun.com/author/custom-metadata.md) for precedence.