You are viewing a plain text version of this content. The canonical link for it is here.
Posted to notifications@apisix.apache.org by "moonming (via GitHub)" <gi...@apache.org> on 2026/03/12 04:13:43 UTC
[PR] fix: improve SEO across the website [apisix-website]
moonming opened a new pull request, #2002:
URL: https://github.com/apache/apisix-website/pull/2002
## Summary
Comprehensive SEO improvements based on a full site audit of https://apisix.apache.org/.
## Changes
### P0: Broken Link Detection
- Changed `onBrokenLinks` from `'ignore'` to `'log'` and `onBrokenMarkdownLinks` from `'ignore'` to `'warn'` in all 4 Docusaurus config files (website, doc, blog-en, blog-zh)
- This surfaces broken links during builds instead of silently ignoring them
### P1: Meta Descriptions
- Added unique `<meta name="description">` and `<meta property="og:description">` to 6 pages that previously had none:
- `/docs` — Documentation hub
- `/plugins` — Plugin Hub
- `/downloads` — Downloads page
- `/help` — Help page
- `/showcase` — Showcase page
- `/team` — Team page
### P1: Twitter Card Upgrade
- Changed `twitter:card` from `summary` to `summary_large_image` in all 4 Docusaurus configs
- This displays a large preview image when links are shared on Twitter/X, improving CTR
### P1: Structured Data (Schema.org)
- Expanded `config/schema-org.js` from a single `WebSite` schema to include:
- `WebSite` with `SearchAction` (enables Google sitelinks search box)
- `Organization` with logo and `sameAs` links (GitHub, Twitter, YouTube)
- `SoftwareApplication` with description, category, license, and free offer
### P2: Image Accessibility
- Fixed empty `alt=""` attributes on AI Gateway page images:
- `Hero.tsx`: Added descriptive alt text for the architecture overview image
- `Advantage.tsx`: Added descriptive alt text for the plugin icons image
### P2: robots.txt
- Added `Disallow` rules for low-value pages that waste crawl budget:
- `/blog/tags/`, `/zh/blog/tags/` (tag listing pages)
- `/blog/page/`, `/zh/blog/page/` (blog pagination pages)
- `/search`, `/zh/search` (search results pages)
### P2: 302 → 301 Redirects
- Changed 4 `RedirectMatch 302` rules to `301` in `.htaccess` for permanent content redirects (getting-started and 3.2 plugins)
- Social media redirects (`/twitter`, `/youtube`, `/slack`) intentionally kept as 302
## Files Changed (15 files)
| File | Change |
|------|--------|
| `.htaccess` | 302 → 301 redirects |
| `blog/en/docusaurus.config.js` | onBrokenLinks + twitter:card |
| `blog/zh/docusaurus.config.js` | onBrokenLinks + twitter:card |
| `config/schema-org.js` | Expanded structured data |
| `doc/docusaurus.config.js` | onBrokenLinks + twitter:card |
| `website/docusaurus.config.js` | onBrokenLinks + twitter:card |
| `website/src/components/AIGateway/Advantage.tsx` | Alt text fix |
| `website/src/components/AIGateway/Hero.tsx` | Alt text fix |
| `website/src/pages/docs.tsx` | Meta description |
| `website/src/pages/downloads.tsx` | Meta description |
| `website/src/pages/help.tsx` | Meta description |
| `website/src/pages/plugins.tsx` | Meta description |
| `website/src/pages/showcase.tsx` | Meta description |
| `website/src/pages/team.tsx` | Meta description |
| `website/static/robots.txt` | Disallow rules |
## Not Included (requires manual work)
- **Font OTF → WOFF2**: Fonts are hosted on external CDN (`static.apiseven.com`) as OTF; converting requires obtaining source files, converting, and re-uploading
- **Docusaurus upgrade to v3**: Major framework upgrade requiring extensive testing
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] fix: improve SEO across the website [apisix-website]
Posted by "Copilot (via GitHub)" <gi...@apache.org>.
Copilot commented on code in PR #2002:
URL: https://github.com/apache/apisix-website/pull/2002#discussion_r2922177820
##########
website/static/robots.txt:
##########
@@ -1,7 +1,13 @@
# Algolia-Crawler-Verif: 027907D9E46C48C1
User-agent: *
+Disallow: /blog/tags/
+Disallow: /zh/blog/tags/
+Disallow: /blog/page/
+Disallow: /zh/blog/page/
+Disallow: /search
+Disallow: /zh/search
Review Comment:
`/search` and `/zh/search` are disallowed here, but `config/schema-org.js` advertises a `SearchAction` pointing at `/search?q=...`. If you want Google to use sitelinks search, the target URL needs to be crawlable (not blocked by robots). Either remove these Disallow rules or remove/adjust the SearchAction target so they’re consistent.
```suggestion
```
##########
website/src/pages/plugins.tsx:
##########
@@ -236,6 +236,8 @@ const Plugins: FC = () => {
return (
<Layout title={translate({ message: 'Plugin Hub' })}>
<Head>
+ <meta name="description" content="Explore 80+ Apache APISIX plugins for authentication, security, traffic control, observability, and AI. Powerful integrations for your API Gateway." />
+ <meta property="og:description" content="Explore 80+ Apache APISIX plugins for authentication, security, traffic control, observability, and AI." />
Review Comment:
These meta description strings are hardcoded in English. Since the site supports multiple locales, the zh build will also get the English meta tags. Consider using `translate(...)` with IDs so the description and og:description can be localized per locale.
```suggestion
<meta
name="description"
content={translate({
id: 'plugins.meta.description',
message:
'Explore 80+ Apache APISIX plugins for authentication, security, traffic control, observability, and AI. Powerful integrations for your API Gateway.',
})}
/>
<meta
property="og:description"
content={translate({
id: 'plugins.meta.ogDescription',
message:
'Explore 80+ Apache APISIX plugins for authentication, security, traffic control, observability, and AI.',
})}
/>
```
##########
website/src/pages/docs.tsx:
##########
@@ -177,6 +178,10 @@ const Docs: FC = () => {
return (
<Layout title={translate({ message: 'Documentation' })}>
+ <Head>
+ <meta name="description" content="Browse Apache APISIX documentation for API Gateway, AI Gateway, Ingress Controller, Helm Chart, and plugin development. Get started with guides, tutorials, and API references." />
+ <meta property="og:description" content="Browse Apache APISIX documentation for API Gateway, AI Gateway, Ingress Controller, Helm Chart, and plugin development." />
Review Comment:
These meta description strings are hardcoded in English. Since this site is configured for i18n (and the page already uses `Translate`/`translate`), the zh locale will also ship English `<meta name="description">`/`og:description`. Consider wrapping these values in `translate(...)` with stable IDs so locale-specific builds get localized metadata.
```suggestion
<meta
name="description"
content={translate({
id: 'docs.meta.description',
message:
'Browse Apache APISIX documentation for API Gateway, AI Gateway, Ingress Controller, Helm Chart, and plugin development. Get started with guides, tutorials, and API references.',
description: 'Meta description for the main Apache APISIX documentation page.',
})}
/>
<meta
property="og:description"
content={translate({
id: 'docs.meta.ogDescription',
message:
'Browse Apache APISIX documentation for API Gateway, AI Gateway, Ingress Controller, Helm Chart, and plugin development.',
description: 'Open Graph description for the main Apache APISIX documentation page.',
})}
/>
```
##########
config/schema-org.js:
##########
@@ -9,12 +9,46 @@ module.exports = function () {
attributes: {
type: 'application/ld+json',
},
- innerHTML: JSON.stringify({
- '@context': 'https://schema.org',
- '@type': 'WebSite',
- name: 'Apache APISIX',
- url: 'https://apisix.apache.org',
- }),
+ innerHTML: JSON.stringify([
+ {
+ '@context': 'https://schema.org',
+ '@type': 'WebSite',
+ name: 'Apache APISIX',
+ url: 'https://apisix.apache.org',
+ potentialAction: {
+ '@type': 'SearchAction',
+ target: 'https://apisix.apache.org/search?q={search_term_string}',
+ 'query-input': 'required name=search_term_string',
+ },
Review Comment:
The `SearchAction.target` points to `/search?q=...`, but this repo doesn’t configure an Algolia `searchPagePath` or define a `/search` page, and `robots.txt` now disallows `/search`. This makes the structured-data sitelinks search action effectively invalid/blocked for crawlers. Consider either (1) adding a real, crawlable search results page and allowing it in `robots.txt`, or (2) removing the `SearchAction` block until a search URL exists.
```suggestion
```
##########
website/src/pages/help.tsx:
##########
@@ -28,6 +29,10 @@ const Page = styled.div`
const Help: FC = () => (
<Layout title={translate({ message: 'Help' })}>
+ <Head>
+ <meta name="description" content="Get help with Apache APISIX. Browse documentation, join the community on GitHub, Slack, and Twitter, and connect with contributors." />
+ <meta property="og:description" content="Get help with Apache APISIX. Browse documentation and join the community on GitHub, Slack, and Twitter." />
Review Comment:
These meta description strings are hardcoded in English. With Docusaurus i18n enabled, the zh locale will also ship these English meta tags. Consider using `translate(...)` with IDs so each locale can provide localized `description` and `og:description`.
```suggestion
<meta
name="description"
content={translate({
id: 'help.meta.description',
message:
'Get help with Apache APISIX. Browse documentation, join the community on GitHub, Slack, and Twitter, and connect with contributors.',
})}
/>
<meta
property="og:description"
content={translate({
id: 'help.meta.ogDescription',
message:
'Get help with Apache APISIX. Browse documentation and join the community on GitHub, Slack, and Twitter.',
})}
/>
```
##########
website/src/pages/downloads.tsx:
##########
@@ -57,6 +58,10 @@ const DownloadCards: FC = () => {
const Downloads: FC = () => (
<Layout title={translate({ message: 'Downloads' })}>
+ <Head>
+ <meta name="description" content="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="Download Apache APISIX, the cloud-native API Gateway and AI Gateway. Get the latest release and historical versions." />
Review Comment:
These meta description strings are hardcoded in English. Because the site is i18n-enabled, the zh locale will also include English `<meta name="description">`/`og:description`. Consider using `translate(...)` with IDs (similar to visible text) so metadata is localized per locale.
```suggestion
<meta
name="description"
content={translate({
id: 'download.website.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.website.meta.ogDescription',
message:
'Download Apache APISIX, the cloud-native API Gateway and AI Gateway. Get the latest release and historical versions.',
})}
/>
```
##########
website/src/pages/team.tsx:
##########
@@ -287,6 +288,10 @@ const Team: FC = () => {
));
return (
<Layout title={translate({ message: 'Team' })}>
+ <Head>
+ <meta name="description" content="Meet the Apache APISIX team — PMC members, committers, and contributors building the cloud-native API Gateway and AI Gateway." />
+ <meta property="og:description" content="Meet the Apache APISIX team — PMC members, committers, and contributors." />
Review Comment:
These meta description strings are hardcoded in English. With Docusaurus i18n enabled, the zh locale will also ship English `<meta name="description">`/`og:description`. Consider using `translate(...)` with IDs to make these locale-specific.
```suggestion
<meta
name="description"
content={translate({
id: 'team.meta.description',
message:
'Meet the Apache APISIX team — PMC members, committers, and contributors building the cloud-native API Gateway and AI Gateway.',
})}
/>
<meta
property="og:description"
content={translate({
id: 'team.meta.ogDescription',
message:
'Meet the Apache APISIX team — PMC members, committers, and contributors.',
})}
/>
```
##########
website/src/pages/showcase.tsx:
##########
@@ -80,6 +81,10 @@ const Content: FC = () => {
const Showcase: FC = () => (
<Layout title={translate({ message: 'ShowCase' })}>
+ <Head>
+ <meta name="description" content="See which companies and organizations use Apache APISIX in production. Join the growing community of API Gateway users worldwide." />
+ <meta property="og:description" content="See which companies and organizations use Apache APISIX in production." />
Review Comment:
These meta description strings are hardcoded in English. Because the site is i18n-enabled, the zh locale will also include these English meta tags. Consider switching to `translate(...)` with IDs so the metadata can be localized alongside the visible strings.
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Re: [PR] fix: improve SEO across the website [apisix-website]
Posted by "moonming (via GitHub)" <gi...@apache.org>.
moonming merged PR #2002:
URL: https://github.com/apache/apisix-website/pull/2002
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: notifications-unsubscribe@apisix.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org