docs: site-wide SEO optimization

charlypa · charlypa · commit 36fa7aae2433 · 2026-03-10T19:32:30.000+05:30
- Fix homepage title and meta description (was broken with &lt;head /&gt; artifact)
- Add robots.txt with sitemap directive
- Add JSON-LD Organization and WebSite structured data
- Add global Twitter Card and Open Graph meta tags
- Enhance sitemap with lastmod and priority differentiation
- Fix anonymizeIP to true for GDPR compliance
- Add aria-label to homepage feature SVGs for accessibility
- Add meta descriptions to all 10 blog posts
- Add SEO pending guide for remaining manual tasks
diff --git a/blog/2024-03-05-welcome/index.md b/blog/2024-03-05-welcome/index.md
@@ -1,6 +1,7 @@
 ---
 slug: welcome
 title: Introducing Phoenix Code Desktop- Now on Windows, Mac & Linux
+description: "Phoenix Code native desktop apps are now available for Windows, Mac, and Linux. Web version available for ChromeOS and other platforms."
 authors: [arun, charly, kiran, mathew, phoenixBot]
 tags: [hello world, Native Apps, Windows, Linux, Mac, Release]
 ---
diff --git a/blog/2024-03-26-Release-3.5/index.md b/blog/2024-03-26-Release-3.5/index.md
@@ -1,6 +1,7 @@
 ---
 slug: release-3.5
-title: March-2024 Release (V-3.5) is now Live 
+title: March-2024 Release (V-3.5) is now Live
+description: "Phoenix Code 3.5 improves large project support, Find in Files, inline HTML number dials, and app stability. Download for Windows, Mac, and Linux."
 authors: [arun, charly, kiran, phoenixBot]
 tags: [Native Apps, Windows, Linux, Mac, Release]
 ---
diff --git a/blog/2024-04-27-Release-3.6/index.md b/blog/2024-04-27-Release-3.6/index.md
@@ -1,6 +1,7 @@
 ---
 slug: release-3.6
-title: April-2024 Release (V-3.6) is now Live 
+title: April-2024 Release (V-3.6) is now Live
+description: "Phoenix Code 3.6 adds PHP and custom live preview servers, advanced CSS/LESS/SCSS code intelligence, and UX improvements."
 authors: [arun, charly, andrew, faizan, phoenixBot]
 tags: [Native Apps, Windows, Linux, Mac, Release]
 ---
diff --git a/blog/2024-05-26-Release-3.7/index.md b/blog/2024-05-26-Release-3.7/index.md
@@ -1,6 +1,7 @@
 ---
 slug: release-3.7
-title: Little Things Release (May-2024, V-3.7) is now Live 
+title: Little Things Release (May-2024, V-3.7) is now Live
+description: "Phoenix Code 3.7 focuses on live preview improvements, CSS class and style code hints, and small UX refinements."
 authors: [arun, charly, phoenixBot]
 tags: [Live Preview, Live Code Hints, Windows, Linux, Mac, Release]
 ---
diff --git a/blog/2024-06-27-Release-3.8/index.md b/blog/2024-06-27-Release-3.8/index.md
@@ -1,6 +1,7 @@
 ---
 slug: release-3.8
-title: Critical Update + HTML Helpers Release (June-2024, V-3.8) is now Live 
+title: Critical Update + HTML Helpers Release (June-2024, V-3.8) is now Live
+description: "Phoenix Code 3.8 fixes crashes on M1 Macs and Linux, adds HTML drag-and-drop editing, and improves live preview stability."
 authors: [arun, charly, phoenixBot]
 tags: [Live Preview, Live Code Hints, Windows, Linux, Mac, Release]
 ---
diff --git a/blog/2024-09-02-Release-3.9/index.md b/blog/2024-09-02-Release-3.9/index.md
@@ -1,6 +1,7 @@
 ---
 slug: release-3.9
-title: HTML Workflows and stability Release (September-2024, V-3.9) is now Live 
+title: HTML Workflows and stability Release (September-2024, V-3.9) is now Live
+description: "Phoenix Code 3.9 improves app stability and robustness, adds HTML and text editing workflow enhancements, and ChromeOS support."
 authors: [arun, charly, kiran, devvaannsh, jozsefk9, acemi1, phoenixBot]
 tags: [Live Preview, Live Code Hints, Windows, Linux, Mac, Release]
 ---
diff --git a/blog/2024-11-24-Release-3.10/index.md b/blog/2024-11-24-Release-3.10/index.md
@@ -1,6 +1,7 @@
 ---
 slug: release-3.10
-title:  Editor Experience Release (November-2024, V-3.10) is now Live
+title: Editor Experience Release (November-2024, V-3.10) is now Live
+description: "Phoenix Code 3.10 improves the editor UI with indent guide lines, better performance, and visual feedback. Updated extension developer docs."
 authors: [arun, charly, devvaannsh, phoenixBot]
 tags: [Editor Experience, UI Improvements, Windows, Linux, Mac, Release]
 ---
diff --git a/blog/2025-01-30-Release-4.0/index.md b/blog/2025-01-30-Release-4.0/index.md
@@ -1,6 +1,7 @@
 ---
 slug: release-4.0
-title:  Git It Release (January-2025, V-4.0) is now Live
+title: Git It Release (January-2025, V-4.0) is now Live
+description: "Phoenix Code 4.0 introduces built-in Git integration, color previews, and open-in-terminal support. The largest release in the Brackets legacy."
 authors: [arun, charly, devvaannsh, phoenixBot]
 tags: [Git, Color previews, Version Control, open in terminal, Stability Improvements, Windows, Linux, Mac, Release]
 ---
diff --git a/blog/2025-01-30-The Legacy of Brackets - Continued/index.md b/blog/2025-01-30-The Legacy of Brackets - Continued/index.md
@@ -1,6 +1,7 @@
 ---
 slug: Blog-Legacy
-title:  "Phoenix Code: The Legacy of Brackets - Continued"
+title: "Phoenix Code: The Legacy of Brackets - Continued"
+description: "The story of Brackets — from its birth at Adobe to Phoenix Code. How a community kept the spirit of Brackets alive and built its future."
 authors: [arun, charly]
 tags: [Brackets, Continued, Phoenix Code, History]
 ---
diff --git a/blog/2026-01-18-Release-5.0/index.md b/blog/2026-01-18-Release-5.0/index.md
@@ -1,6 +1,7 @@
 ---
 slug: release-5.0
-title:  Phoenix Pro Release (January-2026, V-5.0) is now Live
+title: Phoenix Pro Release (January-2026, V-5.0) is now Live
+description: "Phoenix Code 5.0 introduces Phoenix Pro with Live Preview Edit, Emmet support, Tab Bar, and Custom Snippets. The biggest update yet."
 authors: [arun, charly, devvaannsh, phoenixBot]
 tags: [Phoenix Pro, Live Preview Edit, Emmet, Tab Bar, Custom Snippets, Collapse Folders, Smarter hint suggestions, Stability Improvements, Windows, Linux, Mac, Release]
 ---
diff --git a/docusaurus.config.js b/docusaurus.config.js
@@ -21,6 +21,35 @@ const config = {
 	// For GitHub pages deployment, it is often '/<projectName>/'
 	baseUrl: "/",
 	trailingSlash: false,
+	headTags: [
+		{
+			tagName: 'script',
+			attributes: { type: 'application/ld+json' },
+			innerHTML: JSON.stringify({
+				'@context': 'https://schema.org',
+				'@type': 'Organization',
+				name: 'Phoenix Code',
+				url: 'https://phcode.dev',
+				logo: 'https://docs.phcode.dev/img/logo.svg',
+				sameAs: [
+					'https://x.com/phcodedev',
+					'https://github.com/phcode-dev/',
+					'https://discord.gg/rBpTBPttca',
+					'https://www.youtube.com/channel/UCNK2a8DKqPQQe3GlfTk-RHg',
+				],
+			}),
+		},
+		{
+			tagName: 'script',
+			attributes: { type: 'application/ld+json' },
+			innerHTML: JSON.stringify({
+				'@context': 'https://schema.org',
+				'@type': 'WebSite',
+				name: 'Phoenix Code Documentation',
+				url: 'https://docs.phcode.dev',
+			}),
+		},
+	],
 
 	// GitHub pages deployment config.
 	// If you aren't using GitHub pages, you don't need these.
@@ -59,10 +88,27 @@ const config = {
 			/** @type {import('@docusaurus/preset-classic').Options} */
 			({
 				sitemap: {
+					lastmod: 'date',
 					changefreq: "weekly",
 					priority: 0.5,
 					ignorePatterns: ["/tags/**"],
-					filename: "sitemap.xml"
+					filename: "sitemap.xml",
+					createSitemapItems: async (params) => {
+						const {defaultCreateSitemapItems, ...rest} = params;
+						const items = await defaultCreateSitemapItems(rest);
+						return items.map((item) => {
+							if (item.url === 'https://docs.phcode.dev/') {
+								return {...item, priority: 1.0, changefreq: 'weekly'};
+							}
+							if (item.url.includes('/blog/') && !item.url.includes('/blog/tags/')) {
+								return {...item, priority: 0.7, changefreq: 'monthly'};
+							}
+							if (item.url.includes('/docs/')) {
+								return {...item, priority: 0.6};
+							}
+							return item;
+						});
+					},
 				},
 
 				docs: {
@@ -89,7 +135,7 @@ const config = {
 				// Will be passed to @docusaurus/plugin-google-gtag (only enabled when explicitly specified)
 				gtag: {
 					trackingID: "G-XMWSCV9SP1",
-					anonymizeIP: false
+					anonymizeIP: true
 				}
 			})
 		]
@@ -119,6 +165,11 @@ const config = {
 	themeConfig:
 		/** @type {import('@docusaurus/preset-classic').ThemeConfig} */
 		({
+			metadata: [
+				{name: 'twitter:card', content: 'summary_large_image'},
+				{name: 'twitter:site', content: '@phcodedev'},
+				{property: 'og:site_name', content: 'Phoenix Code'},
+			],
 			algolia: {
 				// The application ID provided by Algolia
 				appId: "8DZVLXVEPA",
diff --git a/seo-pending-guide.md b/seo-pending-guide.md
@@ -0,0 +1,125 @@
+# SEO Pending Items Guide
+
+Items that could not be automated and require manual action.
+
+## 1. Social Card Image (High Priority)
+
+**Problem:** Current `static/img/socialcard.png` is 478x277px. The optimal size for Open Graph previews (Facebook, Twitter/X, LinkedIn, Discord) is **1200x630px**.
+
+**Impact:** Small images render poorly or get cropped in social previews, reducing click-through from shared links.
+
+**Action:** Re-export or redesign `static/img/socialcard.png` at 1200x630px. Keep the same filename so no config changes are needed.
+
+**Validation:** After deploying, paste a page URL into:
+- https://cards-dev.twitter.com/validator (Twitter/X)
+- https://developers.facebook.com/tools/debug/ (Facebook)
+
+---
+
+## 2. Doc Page Meta Descriptions (High Priority)
+
+**Problem:** All 40+ documentation pages under `/docs/` are missing `description` in their frontmatter. Without it, Google auto-generates snippets from random page content.
+
+**Impact:** +5.8% CTR per page with an optimized description (Yoast/HubSpot study). Google uses the provided description 37% of the time (Ahrefs study of 20k keywords).
+
+**Action:** Add a `description` field to the frontmatter of each doc page. Example:
+
+```yaml
+---
+title: Live Preview
+description: "Use Phoenix Code's live preview to see HTML and CSS changes in real time. Supports browser sync, custom servers, and visual editing."
+---
+```
+
+**Guidelines:**
+- 150-160 characters (Google truncates beyond ~160)
+- Include the primary keyword for that page naturally
+- Describe what the reader will learn or accomplish
+- Use active language
+
+**Pages needing descriptions (prioritize by traffic):**
+- `docs/01-intro.md`
+- `docs/08-Features/06-Live Preview/01-live-preview.md`
+- `docs/08-Features/beautify-code.md`
+- `docs/08-Features/05-keyboard-shortcuts.md`
+- `docs/04-editing-colors.md`
+- `docs/02-Linux.md`, `docs/03-Mac.md`
+- All remaining doc pages under `docs/`
+
+---
+
+## 3. Google Search Console Setup (High Priority)
+
+**Problem:** The sitemap at `https://docs.phcode.dev/sitemap.xml` should be explicitly submitted to Google Search Console for fastest indexing.
+
+**Action:**
+1. Go to https://search.google.com/search-console
+2. Add property `https://docs.phcode.dev` (if not already added)
+3. Go to Sitemaps > Add a new sitemap
+4. Enter `sitemap.xml` and submit
+5. After `robots.txt` is deployed, Google will also discover it automatically
+
+---
+
+## 4. Blog Post Cover Images (Medium Priority)
+
+**Problem:** No blog post has a custom `image` field in frontmatter. All posts fall back to the global social card (which is also undersized).
+
+**Impact:** Custom images per post make social shares more visually distinct and clickable. Posts with images get 2-3x higher engagement on social platforms.
+
+**Action:** For each blog post, create a 1200x630px cover image and add to frontmatter:
+
+```yaml
+---
+image: /img/blog/release-5.0-cover.png
+---
+```
+
+Store images in `static/img/blog/`.
+
+---
+
+## 5. Category Page Metadata (Low Priority)
+
+**Problem:** `_category_.json` files under `docs/` only set `collapsible` and `collapsed`. They lack `label` and `description` fields.
+
+**Action:** Update each `_category_.json`:
+
+```json
+{
+  "label": "Features",
+  "description": "Phoenix Code editor features — live preview, Git, extensions, visual editing, and more.",
+  "collapsible": true,
+  "collapsed": false
+}
+```
+
+**Files:**
+- `docs/08-Features/_category_.json`
+- `docs/07-Pro Features/_category_.json`
+- `api/API-Reference/_category_.json`
+
+---
+
+## 6. Monitor Core Web Vitals (Ongoing)
+
+**Action:** After deployment, check performance at:
+- https://pagespeed.web.dev/?url=https://docs.phcode.dev
+- Google Search Console > Core Web Vitals report
+
+**Targets:** LCP < 2.5s, INP < 200ms, CLS < 0.1
+
+---
+
+## What Was Already Done (This PR)
+
+| Change | File(s) |
+|--------|---------|
+| Fixed homepage title + description | `src/pages/index.js` |
+| Added `robots.txt` | `static/robots.txt` |
+| Added global OG + Twitter meta tags | `docusaurus.config.js` |
+| Added JSON-LD Organization + WebSite schemas | `docusaurus.config.js` |
+| Enhanced sitemap with lastmod + custom priorities | `docusaurus.config.js` |
+| Fixed `anonymizeIP: true` for GDPR | `docusaurus.config.js` |
+| Added aria-label to homepage SVGs | `src/components/HomepageFeatures/index.js` |
+| Added meta descriptions to 10 blog posts | All `blog/*/index.md` files |
diff --git a/src/components/HomepageFeatures/index.js b/src/components/HomepageFeatures/index.js
@@ -40,7 +40,7 @@ function Feature({Svg, title, description}) {
   return (
     <div className={clsx('col col--4')}>
       <div className="text--center">
-        <Svg className={styles.featureSvg} role="img" />
+        <Svg className={styles.featureSvg} role="img" aria-label={title} />
       </div>
       <div className="text--center padding-horiz--md">
         <Heading as="h3">{title}</Heading>
diff --git a/src/pages/index.js b/src/pages/index.js
@@ -29,11 +29,10 @@ function HomepageHeader() {
 }
 
 export default function Home() {
-  const {siteConfig} = useDocusaurusContext();
   return (
     <Layout
-      title={`Hello from ${siteConfig.title}`}
-      description="Documentation for Phoenix Code editor <head />">
+      title="Phoenix Code Documentation"
+      description="Phoenix Code documentation — live preview editor with Git integration, visual CSS editing, and browser support. Free and open source.">
       <HomepageHeader />
       <main>
         <HomepageFeatures />
diff --git a/static/robots.txt b/static/robots.txt
@@ -0,0 +1,5 @@
+User-agent: *
+Allow: /
+Disallow: /assets/
+
+Sitemap: https://docs.phcode.dev/sitemap.xml
