SEO

SEO

Guidelines for search engine optimization across the Grida project -- Next.js pages, blog posts, and documentation.

Scope

Next.js Pages (editor/app/(www))

Metadata

Every public page must export metadata (static or dynamic).

// Static
export const metadata: Metadata = {
  title: "Page Title — Grida",
  description: "Concise, keyword-rich description under 160 chars.",
  keywords: ["relevant", "keywords"],
  openGraph: {
    title: "Page Title — Grida",
    description: "Same or tailored OG description.",
    images: ["/og/page-name.png"],
  },
  twitter: {
    card: "summary_large_image",
  },
};

// Dynamic
export async function generateMetadata({ params }): Promise<Metadata> { ... }

Rules:

• title should end with — Grida (or use a title.template in the root layout).
• description must be unique per page, under 160 characters, and include primary keywords.
• Every page with OG images must set metadataBase or use absolute URLs so crawlers resolve them correctly.
• OG images must return 200 without auth and use correct Content-Type.

metadataBase

When openGraph.images uses relative paths, the layout or page must set:

metadataBase: new URL("https://grida.co"),

Without this, crawlers may see broken OG URLs.

Sitemap

Public pages belong in editor/app/sitemap.ts.

{
  url: "https://grida.co/new-page",
  changeFrequency: "monthly",
  priority: 0.5,
}

• Use priority: 1 only for the homepage.
• Match changeFrequency to actual update cadence.
• When adding a new public page, always add a sitemap entry.
• Sitemaps are split per route group (root, /packages, /library, …). A new sitemap.ts is invisible to crawlers until it's added as a Sitemap: line in editor/app/robots.txt — non-root sitemaps are not auto-discovered.
• Prefer deriving sitemap entries from the page's data source (see packages/sitemap.ts) over hand-maintained URL lists, which drift.

Google Image Search

Next.js <Image> renders optimized /_next/image?url=... URLs that Google Images indexes unreliably.

For pages where images are the search target (brand assets, logos, press kits):

• Use <Image unoptimized> or plain <img> so the rendered src is a stable, direct public URL (e.g. /brand/grida-symbol-240.png).
• Include descriptive alt text with "Grida" + asset name + format.

Checklist for image assets:

• Returns 200 without cookies; not blocked for Googlebot-Image
• Correct Content-Type (image/png, image/svg+xml, etc.)
• Not blocked by robots.txt or X-Robots-Tag
• /_next/image endpoint itself is not blocked (other pages still use it)
• Stable, clean URLs under public/ -- no query-string-only canonicals

Structured Data (JSON-LD)

Use JSON-LD for rich results where applicable:

• Product pages: Product or SoftwareApplication
• Blog posts: BlogPosting or Article
• FAQ sections: FAQPage
• Brand/org: Organization

Embed via a <script type="application/ld+json"> in the page or layout.

Documentation (docs/**)

Docs are built with Docusaurus and published at grida.co/docs.

Frontmatter

Every doc page should have:

---
title: Feature Name
description: One-line summary for search snippets (under 160 chars).
keywords: [keyword1, keyword2]
---

• title becomes the <title> tag and H1.
• description becomes the meta description.
• keywords help Docusaurus generate meta tags.
• Add slug: only when the default URL path is wrong.

Headings

• Use a single # H1 matching the title frontmatter.
• Use ## for sections -- these generate anchor links and appear in the TOC.
• Headings should be descriptive and keyword-aware (search engines weight them).

Internal Linking

• Link related docs to each other -- it helps search engines discover pages and improves user navigation.
• Use relative paths within /docs.
• For editor pages, use universal routing: https://grida.co/_/<path>.

Blog Posts

Title

• Clear, specific, keyword-forward. Front-load the most important words.
• Avoid clickbait or vague titles.
• Good: "How Grida Canvas Renders 10K Nodes at 60 FPS"
• Bad: "Exciting Updates!"

Meta Description

• Write a custom description in frontmatter (under 160 chars).
• Summarize the post's value proposition -- what will the reader learn?

Content Structure

• Open with a clear summary paragraph (search engines often use this as the snippet).
• Use ## headings that include relevant keywords.
• Break content into scannable sections.
• Include alt text on all images.