docs(seo): PNG social card, per-page TechArticle JSON-LD, IndexNow ping

- Switched og:image / twitter:image to img/social-card.png (1200x630).
  Some unfurlers (Slack, LinkedIn legacy) prefer PNG over SVG.
- Added apps/docs/plugins/api-jsonld.mjs — postBuild plugin that walks
  build/docs/api/*.html and injects a TechArticle JSON-LD block per page,
  templated from the page's own <title> and meta description. Docs
  frontmatter doesn't allow `head:` so this is the cleanest path to
  per-page structured data in the static HTML.
- Added IndexNow key file at static/<key>.txt + a notify-search-engines
  job in deploy-docs.yml that POSTs the full sitemap URL list to
  api.indexnow.org after each Pages deploy. Bing + Yandex pick up
  changes within minutes instead of waiting for crawl.

Author: awbx

.github/workflows/deploy-docs.yml

@@ -58,3 +58,40 @@ jobs:
       - name: Deploy to GitHub Pages
         id: deployment
         uses: actions/deploy-pages@v4
+
+  notify-search-engines:
+    needs: deploy
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Ping IndexNow (Bing, Yandex)
+        run: |
+          set -euo pipefail
+          KEY=00ead8a088444c033454e7c5d686592d
+          HOST=awbx.github.io
+          SITEMAP=https://awbx.github.io/fhir-dsl/sitemap.xml
+          # Wait briefly for the deploy edge to flush, then extract URLs from sitemap.
+          sleep 30
+          URLS=$(curl -sf "$SITEMAP" | grep -oE '<loc>[^<]+</loc>' | sed 's:</?loc>::g')
+          if [ -z "$URLS" ]; then
+            echo "No URLs found in sitemap; skipping IndexNow notify."
+            exit 0
+          fi
+          # Build the JSON payload (Bing IndexNow batch endpoint).
+          URL_LIST=$(echo "$URLS" | jq -R -s -c 'split("\n") | map(select(length > 0))')
+          PAYLOAD=$(jq -n \
+            --arg host "$HOST" \
+            --arg key "$KEY" \
+            --arg keyLocation "https://$HOST/fhir-dsl/$KEY.txt" \
+            --argjson urls "$URL_LIST" \
+            '{host: $host, key: $key, keyLocation: $keyLocation, urlList: $urls}')
+          echo "Notifying IndexNow with $(echo "$URL_LIST" | jq 'length') URLs."
+          curl -sS -X POST "https://api.indexnow.org/IndexNow" \
+            -H "Content-Type: application/json; charset=utf-8" \
+            -H "Host: api.indexnow.org" \
+            --data "$PAYLOAD" \
+            -o /tmp/indexnow.txt -w "HTTP %{http_code}\n" || true
+          cat /tmp/indexnow.txt 2>/dev/null || true

apps/docs/docusaurus.config.js

@@ -7,7 +7,7 @@ const BASE_URL = '/fhir-dsl/';
 const FULL_SITE_URL = `${SITE_URL}${BASE_URL}`;
 const SITE_DESCRIPTION =
   'The TypeScript FHIR toolchain — typed query builder, code generator, FHIRPath, validators, SMART-on-FHIR, terminology, and an MCP bridge.';
-const SOCIAL_CARD = 'img/social-card.svg';
+const SOCIAL_CARD = 'img/social-card.png';
 
 /** @type {import('@docusaurus/types').Config} */
 const config = {
@@ -96,6 +96,7 @@ const config = {
   ],
 
   plugins: [
+    './plugins/api-jsonld.mjs',
     [
       require.resolve('@easyops-cn/docusaurus-search-local'),
       /** @type {import('@easyops-cn/docusaurus-search-local').PluginOptions} */

apps/docs/plugins/api-jsonld.mjs

@@ -0,0 +1,91 @@
+// Docusaurus plugin: inject TechArticle JSON-LD into every built /docs/api/*.html
+// page after the build. Docs frontmatter doesn't support `head:`, so this is the
+// cleanest way to get per-page structured data into the static HTML for SEO.
+//
+// Reads each page's <title> (already populated by Docusaurus from the doc's
+// frontmatter title) and the og:description meta tag for the description, so
+// no per-file maintenance is needed when API ref pages change.
+
+import { readdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const SITE = "https://awbx.github.io/fhir-dsl";
+
+function buildJsonLd({ title, description, url }) {
+  return {
+    "@context": "https://schema.org",
+    "@type": "TechArticle",
+    headline: title,
+    name: title,
+    description,
+    url,
+    inLanguage: "en",
+    isPartOf: {
+      "@type": "WebSite",
+      name: "fhir-dsl docs",
+      url: `${SITE}/`,
+    },
+    about: {
+      "@type": "SoftwareSourceCode",
+      name: "fhir-dsl",
+      codeRepository: "https://github.com/awbx/fhir-dsl",
+      programmingLanguage: "TypeScript",
+    },
+    author: { "@type": "Person", name: "Abdelhadi Sabani" },
+    publisher: { "@type": "Person", name: "Abdelhadi Sabani" },
+    proficiencyLevel: "Expert",
+    articleSection: "API Reference",
+  };
+}
+
+function extractMeta(html) {
+  // Docusaurus emits both <title> and <meta name="description"> in head.
+  const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/);
+  const descMatch =
+    html.match(/<meta[^>]*\bname=["']description["'][^>]*\bcontent=["']([^"']+)["']/) ||
+    html.match(/<meta[^>]*\bcontent=["']([^"']+)["'][^>]*\bname=["']description["']/);
+  if (!titleMatch || !descMatch) return null;
+  // Strip Docusaurus's " | site title" suffix from <title> for cleaner JSON-LD.
+  const title = titleMatch[1].replace(/\s*\|\s*fhir-dsl\s*$/, "");
+  return { title, description: descMatch[1] };
+}
+
+function injectJsonLd(html, ld) {
+  const tag = `<script type="application/ld+json">${JSON.stringify(ld)}</script>`;
+  // Insert just before </head> so it lands among the other head tags.
+  return html.replace(/<\/head>/, `${tag}</head>`);
+}
+
+export default function apiJsonLdPlugin() {
+  return {
+    name: "api-jsonld-plugin",
+    async postBuild({ outDir }) {
+      const apiDir = join(outDir, "docs", "api");
+      let stats;
+      try {
+        stats = statSync(apiDir);
+      } catch {
+        return;
+      }
+      if (!stats.isDirectory()) return;
+
+      let injected = 0;
+      for (const entry of readdirSync(apiDir)) {
+        if (!entry.endsWith(".html")) continue;
+        const path = join(apiDir, entry);
+        const html = readFileSync(path, "utf-8");
+        const meta = extractMeta(html);
+        if (!meta) continue;
+        const slug = entry.replace(/\.html$/, "");
+        const url = `${SITE}/docs/api/${slug}`;
+        const ld = buildJsonLd({ ...meta, url });
+        writeFileSync(path, injectJsonLd(html, ld), "utf-8");
+        injected++;
+      }
+      if (injected > 0) {
+        // eslint-disable-next-line no-console
+        console.log(`[api-jsonld-plugin] injected TechArticle JSON-LD into ${injected} API ref pages`);
+      }
+    },
+  };
+}

apps/docs/static/00ead8a088444c033454e7c5d686592d.txt

@@ -0,0 +1 @@
+00ead8a088444c033454e7c5d686592d