seo

SEO

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

Scope

| Surface | Location | Framework | | ------------------------- | --------------------------------- | ---------- | | Marketing / product pages | editor/app/(www)/ | Next.js 16 | | Blog | docs/blog/ or apps/docs/blog/ | Docusaurus | | Documentation | docs/** | Docusaurus | | Sitemaps | editor/app/sitemap.ts + others | Next.js |

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.

Social Sharing

• Set image: in frontmatter for the OG image.
• OG image should be 1200x630 px for optimal display.
• Ensure the image URL is absolute and publicly accessible.

Crawl Control

robots.txt

Located at editor/app/robots.txt. Currently allows everything except /private/. When adding new route groups that should not be indexed (e.g. internal tools, preview embeds, auth flows), add a Disallow: rule here.

Canonical URLs & Tenant Domains

Grida serves grida.co (main) and [tenant].grida.site (tenant sites). Tenant-rendered pages must not compete with grida.co pages in search.

• Public marketing pages under (www) should set canonical to https://grida.co/....
• Tenant pages ((tenant)) should either set noindex or canonical to their own *.grida.site domain -- never to grida.co.
• Preview / embed pages ((preview)) should be noindex, nofollow.

Known Gaps

• The (www) root layout (editor/app/(www)/layout.tsx) does not set metadataBase. Pages with relative OG images should set it themselves (see metadataBase section above) or it should be added to the root layout.

General SEO Writing Rules

These apply across all surfaces (pages, docs, blog):

1. One primary keyword per page. Include it in the title, first paragraph, and at least one heading.
2. Write for humans first. Natural, helpful content ranks better than keyword-stuffed text.
3. Unique content. Every page must have a unique title and description. Duplicate meta across pages hurts rankings.
4. Descriptive link text. Use meaningful anchor text, not "click here."
5. Alt text on images. Describe what the image shows; include keywords when natural.
6. URL structure. Keep URLs short, lowercase, hyphenated, and descriptive. Avoid IDs or query params in public URLs.
7. Mobile-first. Ensure pages render well on mobile -- Google uses mobile-first indexing.
8. Performance. Page speed is a ranking factor. Prefer static/SSG pages for marketing content. Lazy-load below-fold images.

Verification Checklist

Before shipping a public page or post:

• [ ] title and description set in metadata / frontmatter
• [ ] description is under 160 characters and unique
• [ ] OG image set, absolute URL, returns 200 without auth
• [ ] Page added to sitemap (Next.js pages)
• [ ] Headings use keywords and follow hierarchy (no skipped levels)
• [ ] All images have alt text
• [ ] No duplicate meta with other pages
• [ ] Page is mobile-friendly
• [ ] Canonical URL is correct (no competing duplicates)