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). ```tsx // 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: ```tsx metadataBase: new URL("https://grida.co"), ``` Without this, crawlers may see broken OG URLs. ### Sitemap Public pages belong in `editor/app/sitemap.ts`. ```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: ```md --- 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)