Skip to content

Enhance documentation and SEO for brand assets #543

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
softmarshmallow merged 1 commit into from
Feb 17, 2026
Merged

Enhance documentation and SEO for brand assets #543

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 55 additions & 4 deletions editor/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,59 @@
# `editor`

## Universal routing (docs-friendly links)
This package is the Next.js app that powers **`grida.co`** and tenant domains (e.g. `xyz.grida.site`, custom domains).

Grida supports **universal routing** so documentation can link to stable, tenant-agnostic URLs like `https://grida.co/_/<path>` and have them resolved to canonical tenant/document routes at runtime.
- This doc is a curated “where to change what” map. It’s intentionally **not** exhaustive.

- When you add a **new user-facing page** that should be referenced from docs, ensure it is registered in **universal routing**.
- When debugging docs links that point to the editor, start from the universal routing spec: `docs/wg/platform/universal-docs-routing.md`.
## Key rules (things that bite later)

- **Auth is special**: `app/(auth)` is security-critical. **Do not modify** routes/flows there.
- **Public API is versioned**: treat `app/(api)/(public)/v1` as **backwards-compatible** (additive changes only unless you’re intentionally breaking/v2-ing).
- **Layouts are per route group**: there isn’t a single shared root layout across the whole `app/` tree — top-level route groups own their root `layout.tsx`/metadata.
- **Edge entrypoint is `proxy.ts`**: on Next.js 16 this replaces `middleware.ts` (same runtime + semantics). Don’t add a new `middleware.ts`.
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Feb 17, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

🧩 Analysis chain

🌐 Web query:

Next.js 16 proxy.ts middleware replacement

💡 Result:

In Next.js 16, proxy.ts replaces middleware.ts for request interception on the Node.js runtime (to make the “network boundary” explicit). To migrate, rename middleware.ts → proxy.ts and rename your exported function to proxy—the logic can stay the same. [1][2]

Migration (recommended):

  • Run the codemod: npx @next/codemod@canary middleware-to-proxy . [2]
  • Or manually:
// proxy.ts
import type { NextRequest } from "next/server";
import { NextResponse } from "next/server";

export function proxy(request: NextRequest) {
  // your existing redirects/rewrites/header logic
  return NextResponse.next();
}

Note: middleware.ts still exists for Edge runtime use cases, but it’s deprecated and planned for removal in a future version. [1]

Sources:
[1] Next.js 16 blog (proxy.ts formerly middleware.ts)
[2] Next.js docs message: Renaming Middleware to Proxy

Clarify the runtime distinction for proxy.ts vs middleware.ts in Next.js 16.

The guidance on line 12 is mostly correct but incomplete. proxy.ts replaces middleware.ts for Node.js runtime in Next.js 16 with equivalent semantics (function logic remains the same—just rename the export to proxy). However, middleware.ts still exists for Edge runtime use cases (though deprecated). Expand the note to clarify this distinction so developers understand when to use each approach.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@editor/AGENTS.md` at line 12, Update the note about Edge entrypoints to
clarify runtimes: state that proxy.ts replaces middleware.ts for Node.js runtime
in Next.js 16 (same semantics but export renamed to proxy), while middleware.ts
is still used for Edge runtime scenarios (though deprecated) so developers
should choose proxy.ts for Node.js runtime and middleware.ts only for
Edge-specific needs; reference the files proxy.ts and middleware.ts and mention
Next.js 16 and Edge vs Node.js runtime distinctions in the single sentence.

- **Tenant pages are tenant-aware**: follow [`app/(tenant)/README.md`](<app/(tenant)/README.md>) for host-prefixed fetches (`server.HOST` / `web.HOST`) and tenant-friendly `href="/path"` patterns.
- **Shared UI boundaries matter**:
- `components/` should remain route-agnostic and override-friendly (see [`components/AGENTS.md`](components/AGENTS.md))
- `kits/` are stateful “drop-in widgets” that must not couple to global editor/workbench state (see [`kits/AGENTS.md`](kits/AGENTS.md))
- `scaffolds/` are feature assemblies and may bind to global/editor state
- **Stable public asset URLs**: put canonical assets under `public/` (e.g. `/brand/...png`) when you need a durable, crawlable, cache-friendly path. (If you care about image search quirks, see [`app/(www)/SEO.md`](<app/(www)/SEO.md>).)

## Directory map

### Editor root (selected)

| Path | What lives here | Guide | Notes |
| ------------- | ------------------------------------------- | ---------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `app/` | Next.js App Router routes | — | Route groups are listed below. Main sitemap: [`app/sitemap.ts`](app/sitemap.ts). |
| `www/` | Public-site components for `(www)` | — | Header/footer + landing components. Nav config: [`www/data/sitemap.ts`](www/data/sitemap.ts) (despite the name, it’s **not** `sitemap.xml`). |
| `components/` | Shared UI building blocks | [`components/AGENTS.md`](components/AGENTS.md) | Route-agnostic, override-friendly components. Includes primitives under `components/ui/*` and related subdirectories. |
| `scaffolds/` | Feature-sized UI assemblies | — | Bigger, feature-scoped assemblies (often app-coupled). |
| `lib/` | Stable, non-opinionated modules | — | Good candidates to promote to `/packages` once matured. |
| `grida-*` | Large domain folders (e.g. `grida-canvas*`) | — | Editor-local domain implementations that may be promoted into `/packages` once stabilized. |
| `kits/` | Stateful “drop-in” widgets | [`kits/AGENTS.md`](kits/AGENTS.md) | Opinionated, state-rich UI modules: stateful inside the kit, simple API for consumers. No route/global-store coupling. |
| `theme/` | Templates and themes | — | Email templates, enterprise templates, etc. |
| `public/` | Static assets | — | Use for **stable public asset URLs** (e.g. `/brand/...png`). |

### `app/` route groups (selected)

| Route group | Used for | Guide | Notes / rules |
| ------------- | ------------------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `(workbench)` | Core editor / workbench | — | Performance-sensitive. Keep `use client` boundaries narrow and avoid heavy deps in shared layouts. |
| `(workspace)` | Dashboard / org & project management | — | Similar constraints as `(workbench)`; avoid pushing heavyweight client code into shared layouts. |
| `(tenant)` | Tenant-rooted routes (custom domains / `*.grida.site`) | [`app/(tenant)/README.md`](<app/(tenant)/README.md>) | Tenant-aware routing + host-prefixed fetch rules (`server.HOST` / `web.HOST`). |
| `(api)` | Route handlers (public + private) | — | Public: `app/(api)/(public)/v1` (treat as stable). Private: `app/(api)/private` (first-party). Private editor web APIs live under `app/(api)/private/editor` (see `README.md`). |
| `(auth)` | Auth flow routes | — | **Do not modify.** |
| `(tools)` | Standalone tools | — | Tools live under `app/(tools)/tools/*`. Some tools include a local `AGENTS.md` (example: [`halftone`](<app/(tools)/tools/halftone/AGENTS.md>)). |
| `(preview)` | Embed/preview surfaces | — | Read-only previews and embed-purpose routes (often consumed by tools/playground). |
| `(library)` | Library (open assets) pages | — | Library browsing/marketing routes. |
| `(www)` | Public marketing / SEO pages | [`app/(www)/SEO.md`](<app/(www)/SEO.md>) | Public `grida.co` landing pages and SEO-first routes. |
| `(site)` | Public pages not SEO-first | — | Public routes that aren’t primarily marketing/SEO. |
| `(insiders)` | Insider/local-only routes | — | Local-only/internal tooling and flows. Don’t depend on these for production UX. |
| `(dev)` | Dev-only pages/tools | — | Development-only routes; avoid linking from production UI. |

## Navigation, sitemaps, and docs links

- **Header/nav config**: [`www/data/sitemap.ts`](www/data/sitemap.ts) (drives `www/header.tsx`; despite the name, this is **not** `sitemap.xml`)
- **`sitemap.xml` generator**: [`app/sitemap.ts`](app/sitemap.ts) (Next.js `MetadataRoute.Sitemap` for `grida.co`; tenant routes are handled separately)
- **Universal routing (docs-friendly links)**: [`../docs/wg/platform/universal-docs-routing.md`](../docs/wg/platform/universal-docs-routing.md)
- When docs link to editor pages, prefer `https://grida.co/_/<path>`.
- If you add a new user-facing page that docs should reference, ensure it’s registered in universal routing.
5 changes: 4 additions & 1 deletion editor/app/(www)/(brand)/brand/page.tsx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -123,7 +123,7 @@ export default function BrandPage() {
</p>
</div>

{/* Not a download target — present for crawlers/SEO */}
{/* Not a download target — present for crawlers/SEO. unoptimized so HTML has direct PNG URLs for Google Image index. */}
<div className="relative rounded-2xl border bg-background overflow-hidden p-10 md:p-12">
<div className="relative w-full aspect-square">
{/* Light/Dark aware wordmark */}
Expand All @@ -132,6 +132,7 @@ export default function BrandPage() {
alt="Grida wordmark logo"
fill
priority
unoptimized
sizes="(max-width: 1024px) 100vw, 40vw"
className="object-contain dark:hidden"
/>
Expand All @@ -140,6 +141,7 @@ export default function BrandPage() {
alt="Grida wordmark logo"
fill
priority
unoptimized
sizes="(max-width: 1024px) 100vw, 40vw"
className="object-contain hidden dark:block"
/>
Expand Down Expand Up @@ -286,6 +288,7 @@ function BrandAssetCard({
alt={alt}
fill
priority
unoptimized
sizes="(max-width: 640px) 100vw, 40vw"
className="object-contain"
/>
Expand Down
49 changes: 49 additions & 0 deletions editor/app/(www)/SEO.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
### SEO gotchas for `editor/app/(www)` (not the basics)

This doc exists to record **easy-to-miss stack-specific issues** and **our preferred tricks**.

---

### Google Image Search gotcha: Next.js `<Image>` hides the “real” image URL

**Symptom:** the page ranks (e.g. “Grida logo png”), but **Google Images doesn’t surface the logo assets** from that page.

**Cause:** Next.js `<Image>` commonly renders an optimized `src` like:

- `/_next/image?url=%2Fbrand%2Fgrida-symbol-240.png&w=...&q=...`

Google Images indexes the asset more reliably when the rendered `img src` is a **stable public URL** such as `/brand/...png` rather than only an optimized proxy URL.

**Our trick (for brand/press/asset pages):** ensure the rendered `img src` is a **direct, stable, public asset URL**.

- **Preferred**: keep `<Image>`, but add `unoptimized` for SEO-critical assets.
- **Alternative**: use a plain `<img>` when you want to be maximally explicit.

**Apply to:** pages where the images themselves are the query target (“logo png”, brand assets, downloads).

**Sanity checklist:**

- **Public**: returns **200** without cookies; not blocked for `Googlebot-Image`
- **Correct `Content-Type`**: `image/png`, `image/svg+xml`, etc.
- **Not blocked by robots**: `robots.txt` and `X-Robots-Tag`
- **`/_next/image` is fetchable**: not blocked by robots, authentication, or middleware (other pages may still rely on the optimizer)
- **Stable, clean URLs**: prefer `public/` paths like `/brand/...` (avoid query-string-only canonical asset URLs)
- **Alt text**: include “Grida” + asset name + format (e.g. “Grida wordmark logo (PNG)”)

**Reminder:** JSON-LD / Open Graph help, but they **don’t replace** crawlable image URLs in the HTML for Image Search.

---

### Image search boost: sitemap + canonical URL

- **Image sitemap**: include brand PNGs in the image sitemap (one entry per canonical asset URL).
- **Canonical**: keep a single, clean canonical `/brand` URL (avoid duplicates, tracking params, and competing alternates).

---

### Next.js metadata: relative OG/Twitter images need `metadataBase`

OG/Twitter images must resolve to **absolute public URLs** that return **200** without auth.

If `openGraph.images` uses relative paths in Next.js metadata, `metadataBase` is required so crawlers see correct absolute URLs.

Loading