Add SEO: sitemap, Open Graph, JSON-LD, meta descriptions, and content strategy TODO

aalex · aalex · commit 1a1bc357f7bb · 2026-05-26T01:01:58.000-04:00
- Add @astrojs/sitemap for automatic sitemap generation
- Add robots.txt pointing to sitemap
- Add Open Graph and Twitter Card meta tags to all pages
- Add per-page meta descriptions targeting relevant keywords
- Add canonical URLs and hreflang alternate links for i18n
- Add JSON-LD SoftwareApplication schema on download page
- Add JSON-LD WebSite schema on home page
- Add TODO.md with keyword strategy and blog content plan
diff --git a/TODO.md b/TODO.md
@@ -0,0 +1,79 @@
+# SEO Content Strategy — TODO
+
+## 6. Keyword Optimization
+
+### Target Keywords (by page)
+
+**Home page** — primary landing page, should rank for:
+- "free projection mapping software"
+- "open source video mapping"
+- "projection mapping tool for artists"
+- "video mapping software free download"
+- "mapmap projection"
+
+**Download page:**
+- "download projection mapping software free"
+- "video mapping software windows/mac/linux"
+
+**Docs page:**
+- "projection mapping tutorial"
+- "how to use projection mapping software"
+- "video mapping beginner guide"
+
+### Action Items
+
+- [ ] Rewrite home page intro to naturally include target keywords (avoid stuffing — write for humans first, search engines second)
+- [ ] Add a "What is projection mapping?" section on the home page (targets informational queries, builds topical authority)
+- [ ] Ensure each page's H1 contains the primary keyword for that page
+- [ ] Add internal links between pages (e.g., docs page links to download, home links to docs)
+- [ ] Submit sitemap to Google Search Console
+- [ ] Submit sitemap to Bing Webmaster Tools
+- [ ] List MapMap on free software directories:
+  - AlternativeTo.net
+  - SourceForge
+  - Free Software Directory (FSF)
+  - awesome-projection-mapping lists on GitHub
+  - FLOSS Manuals
+- [ ] Add the site to relevant "projection mapping software" comparison articles (reach out to authors)
+
+## 7. Blog / Tutorials Section
+
+### Why
+
+- Fresh content signals authority to Google (active project = trustworthy)
+- Tutorials rank for long-tail queries ("how to projection map on a building", "mapmap osc tutorial")
+- Shareable content drives backlinks and social traffic
+- Artist showcases build community and social proof
+
+### Implementation Plan
+
+1. Add a blog content directory: `src/data/en/blog/` and `src/data/fr/blog/`
+2. Create a blog listing page at `/[locale]/blog/`
+3. Create a dynamic route for blog posts: `/[locale]/blog/[slug]/`
+4. Each post is a markdown file with frontmatter: title, date, description, tags, author
+5. Add blog link to navigation
+6. Add an RSS feed (Astro has `@astrojs/rss` for this — great for SEO and subscribers)
+
+### Content Ideas (prioritized by SEO impact)
+
+**High impact (targets search queries people actually make):**
+- [ ] "Getting Started with Projection Mapping: A Beginner's Guide"
+- [ ] "How to Set Up a Projection Mapping Installation for Live Events"
+- [ ] "Projection Mapping on Buildings: Step-by-Step Tutorial"
+- [ ] "Free Projection Mapping Software Comparison (2025)"
+- [ ] "How to Use OSC to Control Video Mapping in Real-Time"
+
+**Medium impact (community building, shareable):**
+- [ ] Artist showcase: interview a MapMap user, feature their work
+- [ ] "MapMap at [Festival Name]: Recap and Photos"
+- [ ] "What's New in MapMap 0.6.3"
+- [ ] Video tutorials (embed YouTube/Vimeo — also good for video SEO)
+
+**Low effort, ongoing:**
+- [ ] Release notes for each new version
+- [ ] Quick tips (under 300 words, one specific technique per post)
+
+### Publishing Cadence
+
+Aim for 1-2 posts per month. Consistency matters more than volume.
+Even a quarterly update post is better than silence.
diff --git a/astro.config.mjs b/astro.config.mjs
@@ -1,9 +1,10 @@
 import { defineConfig } from 'astro/config';
 import tailwind from '@astrojs/tailwind';
+import sitemap from '@astrojs/sitemap';
 
 export default defineConfig({
   site: 'https://mapmapteam.github.io',
-  integrations: [tailwind()],
+  integrations: [tailwind(), sitemap()],
   i18n: {
     defaultLocale: 'en',
     locales: ['en', 'fr'],
diff --git a/package-lock.json b/package-lock.json
diff --git a/package.json b/package.json
@@ -8,6 +8,7 @@
     "preview": "astro preview"
   },
   "dependencies": {
+    "@astrojs/sitemap": "^3.7.2",
     "@astrojs/tailwind": "^6.0.0",
     "@tailwindcss/typography": "^0.5.19",
     "astro": "^5.0.0",
diff --git a/public/robots.txt b/public/robots.txt
@@ -0,0 +1,4 @@
+User-agent: *
+Allow: /
+
+Sitemap: https://mapmapteam.github.io/sitemap-index.xml
diff --git a/src/layouts/BaseLayout.astro b/src/layouts/BaseLayout.astro
@@ -1,15 +1,27 @@
 ---
 import Navigation from '../components/Navigation.astro';
 import Footer from '../components/Footer.astro';
-import { getLangFromUrl } from '../i18n/utils';
+import { getLangFromUrl, getLocalizedPath } from '../i18n/utils';
+import { languages } from '../i18n/ui';
+import type { Locale } from '../i18n/utils';
 
 interface Props {
   title: string;
   description?: string;
+  ogImage?: string;
+  jsonLd?: Record<string, unknown>;
 }
 
-const { title, description = 'MapMap - open source video mapping software' } = Astro.props;
+const {
+  title,
+  description = 'MapMap is a free, open source projection mapping software for artists and creative teams. Available on Windows, macOS, and Linux.',
+  ogImage = 'http://projection-mapping.org/wp-content/uploads/2017/08/mapmap-workshop.jpg',
+  jsonLd,
+} = Astro.props;
+
 const lang = getLangFromUrl(Astro.url);
+const canonicalUrl = new URL(Astro.url.pathname, Astro.site);
+const currentPath = Astro.url.pathname;
 ---
 
 <!doctype html>
@@ -20,6 +32,43 @@ const lang = getLangFromUrl(Astro.url);
     <meta name="description" content={description} />
     <title>{title} | MapMap</title>
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+
+    <!-- Canonical URL -->
+    <link rel="canonical" href={canonicalUrl.href} />
+
+    <!-- Alternate language links -->
+    {Object.keys(languages).map((code) => (
+      <link
+        rel="alternate"
+        hreflang={code}
+        href={new URL(getLocalizedPath(currentPath, code as Locale), Astro.site).href}
+      />
+    ))}
+    <link
+      rel="alternate"
+      hreflang="x-default"
+      href={new URL(getLocalizedPath(currentPath, 'en'), Astro.site).href}
+    />
+
+    <!-- Open Graph -->
+    <meta property="og:type" content="website" />
+    <meta property="og:url" content={canonicalUrl.href} />
+    <meta property="og:title" content={`${title} | MapMap`} />
+    <meta property="og:description" content={description} />
+    <meta property="og:image" content={ogImage} />
+    <meta property="og:locale" content={lang === 'fr' ? 'fr_FR' : 'en_US'} />
+    <meta property="og:site_name" content="MapMap" />
+
+    <!-- Twitter Card -->
+    <meta name="twitter:card" content="summary_large_image" />
+    <meta name="twitter:title" content={`${title} | MapMap`} />
+    <meta name="twitter:description" content={description} />
+    <meta name="twitter:image" content={ogImage} />
+
+    <!-- JSON-LD Structured Data -->
+    {jsonLd && (
+      <script type="application/ld+json" set:html={JSON.stringify(jsonLd)} />
+    )}
   </head>
   <body class="min-h-screen flex flex-col bg-white text-gray-900">
     <Navigation />
diff --git a/src/pages/[locale]/docs.astro b/src/pages/[locale]/docs.astro
@@ -10,9 +10,17 @@ const lang = getLangFromUrl(Astro.url);
 
 const content = await import(`../../data/${lang}/docs.md`);
 const Content = content.default;
+
+const descriptions = {
+  en: 'Learn how to use MapMap: projection mapping tutorial covering layers, shapes, meshes, OSC control, and more. Complete user guide for beginners and advanced users.',
+  fr: 'Apprenez à utiliser MapMap : tutoriel de projection vidéo couvrant les calques, formes, meshes, contrôle OSC et plus. Guide complet pour débutants et utilisateurs avancés.',
+};
 ---
 
-<BaseLayout title="Documentation">
+<BaseLayout
+  title="Documentation"
+  description={descriptions[lang]}
+>
   <article class="prose prose-lg max-w-none">
     <Content />
   </article>
diff --git a/src/pages/[locale]/download.astro b/src/pages/[locale]/download.astro
@@ -10,9 +10,42 @@ const lang = getLangFromUrl(Astro.url);
 
 const content = await import(`../../data/${lang}/download.md`);
 const Content = content.default;
+
+const descriptions = {
+  en: 'Download MapMap for free — open source projection mapping software for Windows, macOS, and Linux. No registration required. Start video mapping in minutes.',
+  fr: 'Téléchargez MapMap gratuitement — logiciel libre de projection vidéo pour Windows, macOS et Linux. Aucune inscription requise. Commencez le video mapping en quelques minutes.',
+};
+
+const jsonLd = {
+  '@context': 'https://schema.org',
+  '@type': 'SoftwareApplication',
+  name: 'MapMap',
+  description: descriptions[lang],
+  url: 'https://mapmapteam.github.io',
+  applicationCategory: 'MultimediaApplication',
+  operatingSystem: 'Windows, macOS, Linux',
+  offers: {
+    '@type': 'Offer',
+    price: '0',
+    priceCurrency: 'USD',
+  },
+  license: 'https://opensource.org/licenses/GPL-3.0',
+  softwareVersion: '0.6.3',
+  downloadUrl: 'http://download.mapmap.info/windows/mapmap-0.6.3-x86-installer.exe',
+  screenshot: 'http://projection-mapping.org/wp-content/uploads/2017/08/mapmap-workshop.jpg',
+  author: {
+    '@type': 'Organization',
+    name: 'MapMap Team',
+    url: 'https://mapmapteam.github.io',
+  },
+};
 ---
 
-<BaseLayout title={lang === 'fr' ? 'Télécharger' : 'Download'}>
+<BaseLayout
+  title={lang === 'fr' ? 'Télécharger' : 'Download'}
+  description={descriptions[lang]}
+  jsonLd={jsonLd}
+>
   <article class="prose prose-lg max-w-none">
     <Content />
   </article>
diff --git a/src/pages/[locale]/index.astro b/src/pages/[locale]/index.astro
@@ -10,9 +10,27 @@ const lang = getLangFromUrl(Astro.url);
 
 const content = await import(`../../data/${lang}/home.md`);
 const Content = content.default;
+
+const descriptions = {
+  en: 'MapMap is a free, open source projection mapping software for artists and small teams. Create stunning video projections on any surface. Download for Windows, macOS, and Linux.',
+  fr: 'MapMap est un logiciel libre et gratuit de projection vidéo (video mapping) pour artistes et petites équipes. Créez des projections visuelles sur toute surface. Disponible sur Windows, macOS et Linux.',
+};
+
+const jsonLd = {
+  '@context': 'https://schema.org',
+  '@type': 'WebSite',
+  name: 'MapMap',
+  url: 'https://mapmapteam.github.io',
+  description: descriptions[lang],
+  inLanguage: lang,
+};
 ---
 
-<BaseLayout title={lang === 'fr' ? 'Accueil' : 'Home'}>
+<BaseLayout
+  title={lang === 'fr' ? 'Accueil' : 'Home'}
+  description={descriptions[lang]}
+  jsonLd={jsonLd}
+>
   <article class="prose prose-lg max-w-none">
     <Content />
   </article>
diff --git a/src/pages/[locale]/support.astro b/src/pages/[locale]/support.astro
