npm - blume - Versions diffs - 1.6.2 → 1.6.4 - Mend

blume 1.6.2 → 1.6.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (79) hide show

package/CHANGELOG.md +25 -0
package/dist/cli/index.js +307 -68
package/dist/cli/index.js.map +28 -23
package/dist/types/ai/component-markdown.d.ts +14 -0
package/docs/01-quickstart.mdx +2 -2
package/docs/02-deployment.mdx +5 -5
package/docs/{07-faq.mdx → 08-faq.mdx} +7 -7
package/docs/advanced/blog.mdx +3 -3
package/docs/advanced/changelog.mdx +2 -2
package/docs/advanced/custom-pages.mdx +4 -4
package/docs/advanced/meta.ts +1 -1
package/docs/configuration/ask-ai.mdx +179 -0
package/docs/configuration/index.mdx +8 -7
package/docs/configuration/meta.ts +1 -2
package/docs/configuration/search.mdx +1 -1
package/docs/configuration/theming.mdx +1 -1
package/docs/content/components.mdx +1 -1
package/docs/content/i18n.mdx +7 -1
package/docs/content/index.mdx +1 -1
package/docs/content/navigation.mdx +2 -2
package/docs/content/syntax.mdx +1 -1
package/docs/discoverability/agent-discovery.mdx +196 -0
package/docs/discoverability/index.mdx +48 -0
package/docs/discoverability/json-api.mdx +58 -0
package/docs/discoverability/llms-txt.mdx +68 -0
package/docs/discoverability/markdown.mdx +76 -0
package/docs/discoverability/mcp.mdx +64 -0
package/docs/discoverability/meta.ts +18 -0
package/docs/discoverability/metadata.mdx +82 -0
package/docs/discoverability/open-graph.mdx +113 -0
package/docs/discoverability/rss.mdx +24 -0
package/docs/discoverability/sitemap-and-robots.mdx +95 -0
package/docs/discoverability/structured-data.mdx +51 -0
package/docs/index.mdx +5 -5
package/docs/reference/eval.mdx +1 -1
package/docs/reference/meta.ts +1 -1
package/docs/reference/translate.mdx +1 -0
package/package.json +18 -18
package/src/ai/component-markdown.ts +17 -2
package/src/ai/llms.ts +3 -10
package/src/ai/markdown.ts +3 -10
package/src/ai/openapi-components.ts +123 -0
package/src/ai/serializers.ts +24 -0
package/src/astro/templates.ts +42 -12
package/src/audit/checks/links.ts +1 -8
package/src/audit/checks/llms.ts +5 -4
package/src/audit/redirects.ts +4 -3
package/src/audit/run.ts +6 -8
package/src/audit/url.ts +33 -0
package/src/cli/commands/validate.ts +1 -0
package/src/components/content/Component.astro +65 -68
package/src/components/content/Tabs.astro +24 -9
package/src/components/content/example-pane.ts +6 -0
package/src/components/layout/LocaleLinks.astro +42 -0
package/src/components/layout/PageLayout.astro +5 -3
package/src/components/layout/ReferenceLayout.astro +5 -0
package/src/components/layout/RootLayout.astro +110 -39
package/src/components/layout/search-locale.ts +13 -0
package/src/components/openapi/ApiOverview.astro +7 -39
package/src/components/openapi/ApiTagOperations.astro +2 -1
package/src/components/openapi/AsyncApiOperation.astro +3 -2
package/src/components/openapi/GraphqlOperation.astro +3 -2
package/src/components/openapi/Operation.astro +3 -2
package/src/core/i18n.ts +13 -2
package/src/core/links.ts +33 -1
package/src/core/locale-links.ts +163 -0
package/src/core/sources/normalize.ts +57 -7
package/src/markdown/package-commands.ts +27 -3
package/src/openapi/graphql.ts +29 -0
package/src/openapi/model.ts +69 -0
package/src/openapi/render-mdx.ts +3 -2
package/src/openapi/signature.ts +18 -0
package/src/search/documents.ts +4 -9
package/src/theme/code-block-padding.ts +0 -8
package/src/theme/entry.ts +33 -27
package/src/translate/anchors.ts +91 -0
package/src/translate/validate.ts +8 -3
package/docs/configuration/ai.mdx +0 -613
package/docs/configuration/seo.mdx +0 -364

package/docs/configuration/seo.mdx DELETED Viewed

@@ -1,364 +0,0 @@
----
-title: SEO
-description: Metadata, Open Graph images, RSS feeds, and JSON-LD — Blume's discoverability layer, grouped under one seo config.
-sidebar:
-  label: SEO
----
-Blume handles the discoverability layer for you: page metadata, social share images, feeds, and structured data. The configurable features live under the `seo` key in `blume.config.ts`; metadata is driven by your content.
-```ts blume.config.ts lineNumbers
-seo: {
-  og: { enabled: true },
-  rss: { enabled: true, types: ["blog", "changelog"] },
-  sitemap: true,
-  robots: true,
-  structuredData: true,
-  x: { handle: "@acme" },
-}
-```
-Most of this is sharper with an absolute site URL — set [`deployment.site`](/docs/deployment) so feeds, OG images, canonicals, the sitemap, and JSON-LD can emit full URLs.
-## Metadata
-Every page renders the standard `<head>` tags from your config and frontmatter:
-- `<title>` — the page title plus your site `title`.
-- `<meta name="description">` and `og:description` — the page `description`, falling back to the site `description`.
-- `og:title` and `og:site_name` — the page title and your site `title`.
-- `<link rel="canonical">` and `og:url` — the page's absolute URL (when `deployment.site` is set).
-- `og:type` — `article` on blog posts and changelog entries, `website` elsewhere. Article pages also emit `article:published_time` and `article:modified_time` from the page's `date` and last-modified timestamp.
-- `og:image` — the [OG image](#open-graph-images) for the page. A generated card also declares its `og:image:width`, `og:image:height`, `og:image:type`, and `og:image:alt`, so a crawler can lay the card out without fetching it first; an `seo.image` you supply yourself declares none of these, since its size and format are unknown.
-- `twitter:card`, `twitter:title`, `twitter:description`, `twitter:image` — the X card. Pages with an image get the wide `summary_large_image` variant; pages without one still get the compact `summary` card rather than rendering as a bare link.
-### X attribution
-X reads everything else on the card from the `og:*` tags, so the only values it can't infer are the accounts to credit. Set them under `seo.x` and Blume emits `twitter:site` (your site's account) and `twitter:creator` (the author's). The `@` is optional — `acme` and `@acme` both work.
-```ts blume.config.ts lineNumbers
-seo: {
-  x: { handle: "@acme", creator: "@jane" },
-}
-```
-A page can claim its own author, which is what you want for a guest post:
-```yaml lineNumbers
----
-title: How we shipped it
-seo:
-  x:
-    creator: "@guestauthor"
----
-```
-Override any of the other tags per page with `seo` frontmatter:
-```yaml lineNumbers
----
-title: Pricing
-description: Plans and pricing for every team size.
-seo:
-  title: Pricing — Acme
-  canonical: https://acme.com/pricing
-  noindex: false
----
-```
-<TypeTable
-  type={{
-    "seo.title": {
-      type: "string",
-      description: "Override the <title> and og:title for this page.",
-    },
-    "seo.description": {
-      type: "string",
-      description: "Override the meta + og:description.",
-    },
-    "seo.image": {
-      type: "string",
-      description: "Custom social image (see Open Graph).",
-    },
-    "seo.canonical": {
-      type: "string",
-      description: "Override the canonical URL.",
-    },
-    "seo.noindex": {
-      type: "boolean",
-      description: "Emit robots noindex and skip structured data.",
-    },
-    "seo.x.creator": {
-      type: "string",
-      description:
-        "Credit this page to an X account (twitter:creator), overriding seo.x.creator from your config.",
-    },
-  }}
-/>
-## Open Graph images
-Blume can render a 1200×630 social card for every page at build time — no headless browser, thanks to [Takumi](https://takumi.kane.tw), so builds stay fast. On by default once [`deployment.site`](/docs/deployment) is set or auto-detected (the `og:image` URL has to be absolute to be useful to crawlers), and off otherwise. Set `enabled` to override that either way:
-```ts blume.config.ts lineNumbers
-seo: {
-  og: { enabled: true }, // or false to opt out even with a site set
-}
-```
-### Brand the generated card
-Set a local SVG and color palette to match the generated card to your brand. The logo can live in `public/` or at the project root. Omit any palette value to keep its default.
-```ts blume.config.ts lineNumbers
-seo: {
-  og: {
-    logo: "/logo/og.svg",
-    palette: {
-      accent: "#ff5410",
-      background: "#1d1d1d",
-      foreground: "#fff6f2",
-      muted: "#a6a19f",
-      border: "#323232",
-    },
-  },
-}
-```
-By default, each card is derived from your content and theme — the **page title** as the headline, the **page description** as the subtitle (the same text as its `og:description`, so `seo.description` wins over `description`), your **site title** as the eyebrow, and your theme **accent** for the mark. Images are served at `/og/<slug>.png`, mirroring each route, and are prerendered as static files even in server mode:
-| Page route          | Image URL                  |
-| ------------------- | -------------------------- |
-| `/`                 | `/og/index.png`            |
-| `/quickstart`       | `/og/quickstart.png`       |
-| `/configuration/ai` | `/og/configuration/ai.png` |
-Override the generated card for any page with `seo.image` — a file in `public/` or an external URL. It takes precedence over the generated card and works even when `og` is off, so you can mix custom images with generated ones:
-```yaml lineNumbers
----
-title: Pricing
-seo:
-  image: /og/pricing-custom.png
----
-```
-:::note
-Every palette color accepts any CSS color — hex, `oklch(…)`, `rgb(…)`, and so on. The accent also accepts a named preset (`blue`, `teal`, …), matching [`theme.accent`](/docs/configuration/theming#accent). A color the renderer can't parse fails the build rather than silently shipping a default-colored card.
-:::
-Emoji in a page title or site title render as [Twemoji](https://github.com/jdecked/twemoji) glyphs, fetched from a CDN while the card renders — so a build whose titles contain emoji needs network access. Each glyph is fetched once per build, however many pages use it.
-### Show, hide, or override card layers
-Beyond the headline, the card carries three optional layers: the **brand mark** in the top-left (your logo, or an accent tile with the site title's initial), the **subtitle** under the headline (the page `description`, or your site `description` for pages without one), and a **footer** with your repo slug (from `github`) and the site's URL — the deployment site's host plus [`deployment.base`](/docs/deployment#subpath-deploys), so a GitHub Pages project site reads `user.github.io/repo`. Override any of them with a string of your own, or hide one with `false`:
-```ts blume.config.ts lineNumbers
-seo: {
-  og: {
-    site: "docs.acme.com", // footer URL text, or false to hide it
-    description: false, // hide the subtitle on every card; a string replaces the site fallback
-    logo: false, // no brand mark at all — not even the initial tile
-  },
-}
-```
-### Card fonts
-By default the card renders in Takumi's built-in font, which covers only Latin glyphs — a title in another script (Japanese, Chinese, Korean, Arabic, …) would render as tofu, empty boxes.
-**Set [`theme.fonts`](/docs/configuration/theming#fonts) and the card follows it.** When your config picks its own fonts, the generated cards automatically render the headline in your display font and the description and footer in your body font, so shared links match the site — including non-Latin coverage, with nothing to configure here. (Families from non-Google providers are skipped — the card renderer can only fetch from Google Fonts — but local font files work.)
-To use different fonts on cards than on the site, or to add script coverage without touching the theme, set `og.fonts` explicitly — it always wins over the theme-derived fonts:
-```ts blume.config.ts lineNumbers
-seo: {
-  og: {
-    fonts: [
-      "Noto Sans JP",
-      { name: "Inter", weight: [400, 700] },
-      { name: "Berkeley Mono", src: "./fonts/BerkeleyMono-Regular.woff2" },
-    ],
-  },
-}
-```
-Each entry is a Google Fonts family name, an object pinning its `weight` (a number, a list, or a variable range like `"100..900"`) and `style` (`"normal"`, `"italic"`, or both), or a local font file — `src` resolves from the project root, with optional `weight` and `style` when the file's own metadata shouldn't decide.
-Google families are fetched at build — so a build that uses them needs network access — and the renderer only pulls the glyph subsets each title actually uses. Fallback is per-glyph, so adding a family only affects glyphs the other fonts can't draw.
-An explicit `og.fonts: []` opts out entirely: cards keep the built-in font even when `theme.fonts` is set.
-### Custom page titles
-A custom [`.astro` page](/docs/advanced/custom-pages) has no frontmatter to read, so its generated card is titled by humanizing the last URL segment of its route — `/getting-started` becomes "Getting Started", but `/cli` becomes "Cli". Name those cards explicitly with `og.titles`, keyed by route (`"/"` addresses the home, whose card otherwise carries the site title):
-```ts blume.config.ts lineNumbers
-seo: {
-  og: {
-    titles: {
-      "/cli": "CLI",
-    },
-  },
-}
-```
-Entries only apply to custom pages — a content page's card always takes its headline from the page title, so retitle those in frontmatter instead.
-`seo.image` is frontmatter, so it only covers Markdown and MDX content. To give a custom [`.astro` page](/docs/advanced/custom-pages) its own social image — a marketing home or landing page, and the way to give the home page alone a bespoke share image — pass the `ogImage` prop to `PageLayout`.
-## RSS feeds
-Blume builds an RSS feed for each content type in `rss.types` — `blog` and `changelog` by default — that has pages, served at `/<type>/rss.xml`. See [Feeds](/docs/content#feeds) for authoring blog and changelog entries with dates.
-```ts blume.config.ts lineNumbers
-seo: {
-  rss: {
-    enabled: true,
-    types: ["blog", "changelog"],
-    limit: 50,
-  },
-}
-```
-| Option    | Default                 | Description                           |
-| --------- | ----------------------- | ------------------------------------- |
-| `enabled` | `true`                  | Generate feeds.                       |
-| `types`   | `["blog", "changelog"]` | Content types that each get a feed.   |
-| `limit`   | `50`                    | Maximum items per feed, newest first. |
-Blume injects `<link rel="alternate">` tags so browsers and feed readers discover the feeds automatically.
-## Structured data
-Blume emits [schema.org](https://schema.org) JSON-LD in every page's `<head>` so search engines understand your content. On by default:
-```ts blume.config.ts lineNumbers
-seo: {
-  structuredData: true,
-}
-```
-Each page includes:
-- a **WebSite** node for site identity,
-- the page as an **article** — `BlogPosting` for blog posts, `TechArticle` for changelog and docs — with its description and publish date,
-- a **BreadcrumbList** built from the navigation trail.
-URLs are absolute when `deployment.site` is set. Pages marked `seo.noindex` are skipped.
-### Site identity
-The WebSite node says a site exists; it doesn't say _what_ it is or _who_ runs it — which is what AI agents read JSON-LD for before they recommend or cite you. Two optional blocks fill that in, both needing `deployment.site` (the nodes carry absolute identifiers):
-```ts blume.config.ts lineNumbers
-seo: {
-  organization: {
-    name: "Acme", // defaults to the site title
-    email: "hello@acme.com",
-    telephone: "+1 555 0100",
-    address: { addressLocality: "Sydney", addressCountry: "AU" },
-    logo: "/logo.svg",
-    sameAs: ["https://github.com/acme", "https://x.com/acme"],
-  },
-  software: {
-    license: "MIT",
-    operatingSystem: "Node.js 22+",
-    price: 0, // emitted as an Offer; 0 marks it free
-    sameAs: ["https://www.npmjs.com/package/acme"],
-  },
-}
-```
-`organization` adds an **Organization** node to every page — the WebSite and article nodes cite it as `publisher` — with the email and telephone as a `ContactPoint` (`contactType` defaults to `"customer support"`) and the address as a `PostalAddress`, the two fields business-verification checks look for. `name` and `url` default to the site's; a root-relative `logo` is absolutized like any page URL.
-`software` adds a **SoftwareApplication** node to the homepage: the product's name and description (defaulting to the site's), `applicationCategory` (default `"DeveloperApplication"`), operating system, license, an `Offer` when `price` is set, and the registry or repository URLs in `sameAs`. Pass `software: true` to take every default. The organization, when configured, is cited as its `publisher`.
-## Sitemap
-Blume writes a `sitemap.xml` of every indexable page at build time. It needs an absolute [`deployment.site`](/docs/deployment) and lists every page except drafts, hidden, and `noindex` pages. On a [versioned](/docs/content/versioning) site, archived pages whose canonical points at their live equivalent are left out too — the live page is the one to index. On by default:
-```ts blume.config.ts lineNumbers
-seo: {
-  sitemap: true,
-}
-```
-Ship your own `public/sitemap.xml` to take over — Blume never overwrites a file you place in `public/`.
-## Robots
-Blume writes a `robots.txt` that allows all crawlers, declares your [content signals](#content-signals), and adds a `Sitemap:` line pointing to the sitemap when one is available. On by default:
-```ts blume.config.ts lineNumbers
-seo: {
-  robots: true,
-}
-```
-```txt robots.txt
-User-agent: *
-Content-Signal: search=yes, ai-input=yes, ai-train=yes
-Allow: /
-Sitemap: https://docs.example.com/sitemap.xml
-```
-### Content signals
-The `Content-Signal` line — the emerging content-usage convention — declares how AI crawlers may reuse your docs. Blume emits it **on by default with every signal set to `yes`**, matching its stance that docs are open to humans and agents alike:
-- `search` — traditional and AI search indexing
-- `aiInput` — grounding / RAG at answer time
-- `aiTrain` — model training
-Restrict any signal by setting it to `false`; the ones you leave out stay `yes`:
-```ts blume.config.ts lineNumbers
-seo: {
-  contentSignals: {
-    aiTrain: false, // opt out of training, keep search + grounding
-  },
-}
-```
-```txt robots.txt
-User-agent: *
-Content-Signal: search=yes, ai-input=yes, ai-train=no
-Allow: /
-```
-Set `contentSignals: false` to drop the declaration entirely:
-```ts blume.config.ts lineNumbers
-seo: {
-  contentSignals: false,
-}
-```
-<TypeTable
-  type={{
-    "seo.contentSignals": {
-      type: "boolean | object",
-      description:
-        "Content-Signal declaration. true or omitted emits all signals as yes; false drops the line; an object sets signals individually.",
-    },
-    "contentSignals.search": {
-      type: "boolean",
-      description: "Allow use for search indexing (search). Default true.",
-    },
-    "contentSignals.aiInput": {
-      type: "boolean",
-      description:
-        "Allow use for AI grounding / RAG at answer time (ai-input). Default true.",
-    },
-    "contentSignals.aiTrain": {
-      type: "boolean",
-      description: "Allow use for AI model training (ai-train). Default true.",
-    },
-  }}
-/>
-Content signals express a preference, not access control: they tell well-behaved crawlers how you'd like your content used, and it's on the crawler to honor them.
-Ship your own `public/robots.txt` to take over.