feat(seo): add BreadcrumbList, SoftwareApplication schema, and image alt text (#2029)

Author: moonming

config/breadcrumb.js

@@ -0,0 +1,127 @@
+const SITE_URL = 'https://apisix.apache.org';
+
+/**
+ * Generate BreadcrumbList JSON-LD structured data from a URL path.
+ *
+ * Example for /docs/apisix/plugins/limit-req/:
+ *   Home > Docs > APISIX > Plugins > limit-req
+ */
+function buildBreadcrumbs(urlPath) {
+  // Remove trailing index.html and normalize
+  const cleanPath = urlPath
+    .replace(/\/index\.html$/, '/')
+    .replace(/\.html$/, '/');
+
+  // Split into segments, filter empties
+  const segments = cleanPath.split('/').filter(Boolean);
+
+  if (segments.length === 0) return null; // homepage, no breadcrumb needed
+
+  // Build breadcrumb items
+  const items = [
+    {
+      '@type': 'ListItem',
+      position: 1,
+      name: 'Home',
+      item: SITE_URL + '/',
+    },
+  ];
+
+  // Human-readable labels for known path segments
+  const labels = {
+    docs: 'Docs',
+    apisix: 'APISIX',
+    blog: 'Blog',
+    plugins: 'Plugins',
+    'learning-center': 'Learning Center',
+    'ingress-controller': 'Ingress Controller',
+    'helm-chart': 'Helm Chart',
+    docker: 'Docker',
+    'ai-gateway': 'AI Gateway',
+    downloads: 'Downloads',
+    team: 'Team',
+    contribute: 'Contribute',
+    showcase: 'Showcase',
+    help: 'Help',
+    articles: 'Articles',
+    events: 'Events',
+    general: 'General',
+    zh: 'Chinese',
+  };
+
+  let currentPath = '';
+  for (let i = 0; i < segments.length; i++) {
+    const seg = segments[i];
+    currentPath += '/' + seg;
+
+    // Skip 'zh' locale prefix in breadcrumb display
+    if (seg === 'zh' && i === 0) continue;
+
+    const name = labels[seg] || seg.replace(/-/g, ' ').replace(/\b\w/g, (c) => c.toUpperCase());
+
+    items.push({
+      '@type': 'ListItem',
+      position: items.length + 1,
+      name,
+      item: SITE_URL + currentPath + '/',
+    });
+  }
+
+  // Don't generate breadcrumbs for single-level pages (just Home > Page)
+  if (items.length <= 1) return null;
+
+  return {
+    '@context': 'https://schema.org',
+    '@type': 'BreadcrumbList',
+    itemListElement: items,
+  };
+}
+
+/**
+ * Docusaurus plugin that injects BreadcrumbList JSON-LD into every page
+ * during the post-build phase.
+ */
+module.exports = function breadcrumbPlugin() {
+  return {
+    name: 'breadcrumb-jsonld',
+
+    async postBuild({ outDir }) {
+      const fs = require('fs');
+      const path = require('path');
+
+      function findHtmlFiles(dir) {
+        const results = [];
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+          const fullPath = path.join(dir, entry.name);
+          if (entry.isDirectory()) {
+            results.push(...findHtmlFiles(fullPath));
+          } else if (entry.name.endsWith('.html')) {
+            results.push(fullPath);
+          }
+        }
+        return results;
+      }
+
+      const htmlFiles = findHtmlFiles(outDir);
+      let injected = 0;
+
+      for (const filePath of htmlFiles) {
+        let html = fs.readFileSync(filePath, 'utf-8');
+
+        const relativePath = path.relative(outDir, filePath);
+        const urlPath = '/' + relativePath.split(path.sep).join('/');
+
+        const breadcrumbs = buildBreadcrumbs(urlPath);
+        if (!breadcrumbs) continue;
+
+        const script = `<script type="application/ld+json">${JSON.stringify(breadcrumbs)}</script>`;
+        html = html.replace('</head>', `    ${script}\n  </head>`);
+        fs.writeFileSync(filePath, html, 'utf-8');
+        injected++;
+      }
+
+      console.log(`  [breadcrumb] Injected BreadcrumbList into ${injected} pages`);
+    },
+  };
+};

doc/docusaurus.config.js

@@ -205,6 +205,7 @@ module.exports = {
     ],
     ['docusaurus-plugin-sass', {}],
     require.resolve('../config/schema-org'),
+    require.resolve('../config/breadcrumb'),
   ],
   themeConfig: {
     navbar: {

website/docusaurus.config.js

@@ -97,6 +97,7 @@ module.exports = {
     ],
     ['docusaurus-plugin-sass', {}],
     require.resolve('../config/schema-org'),
+    require.resolve('../config/breadcrumb'),
   ],
   themeConfig: {
     navbar: {

website/src/pages/downloads.tsx

@@ -61,6 +61,27 @@ const Downloads: FC = () => (
     <Head>
       <meta name="description" content={translate({ id: 'download.meta.description', message: 'Download Apache APISIX, the cloud-native API Gateway and AI Gateway. Get the latest release, verify signatures, and access historical versions.' })} />
       <meta property="og:description" content={translate({ id: 'download.meta.ogDescription', message: 'Download Apache APISIX, the cloud-native API Gateway and AI Gateway. Get the latest release and historical versions.' })} />
+      <script type="application/ld+json">
+        {JSON.stringify({
+          '@context': 'https://schema.org',
+          '@type': 'SoftwareApplication',
+          name: 'Apache APISIX',
+          applicationCategory: 'DeveloperApplication',
+          operatingSystem: 'Linux, macOS, Docker, Kubernetes',
+          license: 'https://www.apache.org/licenses/LICENSE-2.0',
+          url: 'https://apisix.apache.org/downloads/',
+          author: {
+            '@type': 'Organization',
+            name: 'Apache Software Foundation',
+            url: 'https://www.apache.org/',
+          },
+          offers: {
+            '@type': 'Offer',
+            price: '0',
+            priceCurrency: 'USD',
+          },
+        })}
+      </script>
     </Head>
     <DownloadsPage>
       <PageTitle><Translate id="download.website.title">Downloads</Translate></PageTitle>

website/src/pages/team.tsx

@@ -256,7 +256,7 @@ const Team: FC = () => {
           href={`https://github.com/${member.githubUsername}`}
           target="_blank"
         >
-          <Avatar src={member.avatarUrl} />
+          <Avatar src={member.avatarUrl} alt={member.name || member.username} width={108} height={108} loading="lazy" />
           <MemberName>{member.name}</MemberName>
           <Username>
             @