sass-mohfarawati/docs/SEO.md

SEO

How search visibility works in this project and where each piece is controlled. Everything is data-driven from the admin; no code change is needed to adjust titles, descriptions, indexing, verification, or structured data.

Admin: Settings → SEO (/site-settings/seo)

Canonical page: app/_admin/site-settings/seo/page.tsx (mirrored under app/admin-internal/ and app/root/). Form: components/admin/seo-settings-form.tsx. Action: saveSeoSettingsAction in app/_admin/site-settings/actions.ts.

Stored as one JSON blob in app_config under key seo_settings (lib/seo-settings.ts parses/normalizes; lib/app-config.ts exposes getSeoSettings / updateSeoSettings).

Field	Effect
Indexierung erlauben	Off → noindex,nofollow meta on every page, robots.txt disallows /, sitemap.xml becomes empty. Maintenance mode forces the same automatically.
Google / Bing Verification	<meta name="google-site-verification"> and <meta name="msvalidate.01"> on all pages. Tokens are restricted to [A-Za-z0-9_-].
X / Twitter Handle	twitter:site + twitter:creator.
Strukturierte Daten	Type (Person / Organization), name, job title/slogan, sameAs profile URLs → JSON-LD publisher on every public page.
Keywords (per locale)	<meta name="keywords"> per language.

The page also shows a checklist (lib/seo-report.ts) — indexing state, public URL, meta description length per locale, OG image, favicon, verification, structured data, published projects, sitemap URL count — and open buttons for /sitemap.xml, /robots.txt, /manifest.webmanifest.

Titles, descriptions and the title template per locale live under Settings → Localization; logos, favicon and the default OG image under Settings → Brand.

Generated files

• app/robots.ts → /robots.txt. Indexable: allow /, disallow admin (/admin-internal, /root), /api/, /success, /coming-soon (+ locale variants), plus the sitemap URL. Not indexable (setting off or maintenance): disallow everything.
• app/sitemap.ts → /sitemap.xml. One entry per locale for home, about, portfolio, contact, every category that has published projects, and every published project — each with xhtml:link hreflang alternates and x-default. Empty while maintenance mode is on or indexing is disabled.
• app/manifest.ts → /manifest.webmanifest (icons from Brand settings).

Per-page metadata (lib/metadata.ts)

• buildAppMetadata() — root layout: metadataBase, robots, verification, keywords, icons, manifest, OG (og:locale as de_DE/en_US/ar_AR + alternateLocale), Twitter.
• buildLocalizedMetadata({...}) — every public page: templated title, description (≤300 chars), canonical + hreflang alternates, robots, OG, Twitter. Options: image (page-specific share image), noIndex, type: "article", publishedTime.
• Portfolio project pages pass the project cover as OG image and article type. This is independent of the project's view mode (GRID / STORY / CASE_STUDY), so new view modes inherit full SEO automatically.
• /success and /coming-soon are noindex.

Structured data (JSON-LD)

Rendered via components/seo/json-ld.tsx (server component; < is escaped).

• Site layout: WebSite + publisher (Person or Organization) graph linked by @id (buildSiteJsonLd).
• Project page: CreativeWork with url, headline, description, image, genre (category), keywords (service label, year), datePublished, author @id, client as sourceOrganization (buildProjectJsonLd).

Slugs

Categories and projects share /portfolio/[slug]; categories win at resolve time. The admin therefore rejects a project slug that equals an existing category slug and vice versa (app/_admin/portfolio/actions.ts).

Operational checklist before launch

1. NEXT_PUBLIC_SITE_URL must be the public https:// origin (canonical base).
2. Settings → Localization: site name + 50–160 char description in DE/EN/AR.
3. Settings → Brand: default OG image (1200×630) + favicon.
4. Settings → SEO: indexing on, verification codes, Person/Organization data.
5. Maintenance mode off. Verify /robots.txt and /sitemap.xml from the SEO page.
6. Submit the sitemap in Google Search Console / Bing Webmaster.