SEO foundations, plus surface the AI story on the home page - #889
Merged
Conversation
The site emitted no rel=canonical anywhere and baseURL was "/", so Hugo generated relative <loc> values in sitemap.xml. The sitemaps.org spec requires an absolute URL there, which made all 4704 entries unusable for discovery, and og:url resolved to "/" on the home page. - config.toml: baseURL -> https://skywalking.apache.org/. canonifyURLs stays off, so internal links are unchanged; only sitemap/og:url/canonical/RSS gain absolute URLs. - layouts/robots.txt: new, advertises the sitemap. Hugo's built-in default emitted a bare "User-agent: *" with no Sitemap: directive. - layouts/partials/seo/meta.html: rel=canonical on every page, a <meta name="description"> where the page has real prose, and reciprocal en/zh-CN hreflang on the 53 blog posts that exist in both languages. - layouts/partials/seo/doc-canonical-map.html: docs.js renders `Latest` and the newest tag from the same commitId, so e.g. /docs/main/latest/ and /docs/main/v10.4.0/ are identical documents at two URLs. The tagged one now canonicalises to /latest/. Keyed on commitId equality, so it self-corrects at each release. Every version URL stays live and served; older versions self-canonicalise and remain independently indexable. - layouts/partials/seo/lang.html + all baseof templates: content/zh holds Chinese blog posts but the site is a single Hugo language, so all 113 of them declared lang="en". Derive the tag from the URL instead. - layouts/partials/seo/schema.html: JSON-LD replacing the internal template's bare itemprop microdata - Organization and SoftwareApplication on the home page, BlogPosting on posts, TechArticle plus BreadcrumbList on docs. - content/_index.html: add a description. Without one, Hugo's internal opengraph template fell back to .Summary, which scraped the hero SVG ("- APACHE SOFTWARE FOUNDATION - OPEN SOURCE - ...") into every social card. - data/docs.yml: BanyanDB `Latest` pointed at dda5b5ed, which is the v0.10.1 tag commit, so /docs/skywalking-banyandb/latest/ served v0.10.1 docs through both the v0.10.2 and v0.10.3 releases. Realigned to v0.10.3. Verified against a full local build: 4551/4552 pages carry a canonical (the only page without is the Vite 3d-map SPA shell, which bypasses Hugo layouts), 200 sampled version-canonical targets all resolve, 113/113 zh pages and 30 zh_tags pages report zh-CN with no English page mislabelled, and JSON-LD parses on 391/391 of a random 400-page sample with no dangling @id references.
The site shipped GenAI/LLM monitoring in 10.4 and the Horizon UI AI Assistant,
but neither appeared on the home page, and the Chinese blog was reachable only
from a dropdown it shared with two third-party accounts.
Positioning
- Hero: "the observability platform for cloud-native and AI". The lead drops the
four-verb opener ("collects, analyzes, aggregates and visualizes") for what the
platform actually does now, including the GenAI models services call.
- New GenAI capability card: latency, traffic, success rate, input/output tokens
and estimated cost per provider and model, from SkyWalking, OTLP or Zipkin
traces (docs/en/setup/service-agent/virtual-genai.md, shipped in v10.4.0).
- The capability grid becomes 3x2: five pillars plus a "See all capabilities"
tile, so the fifth card is not stranded on a row of its own and the spare slot
earns an internal link to /docs/.
- "plain language" -> "natural language" throughout. Peer products (Dynatrace,
Grafana, New Relic, OpenObserve, Arize) all use the latter; "plain language"
names a different thing (the plain-language writing movement) and is not what
anyone searches for. Also fixes "Ask your observability", which had no object.
- Deliberately not branded "AI-native": SkyWalking is a mature APM that gained AI
capabilities, and none of the comparable products make that claim either.
- "A modern APM" -> "An observability platform", so the page stops describing
itself as two different categories.
- The agents card listed ten languages under a "14 language agents" link. It now
lists eleven (Ruby was missing) and says eleven, which is what data/docs.yml
supports.
Navigation
- The 中文资料 dropdown mixed one on-site destination with links to B站 and 掘金.
Since those platforms outrank skywalking.apache.org on Baidu by construction
(ICP-filed and China-hosted, which this domain is not), pointing at them from
every page worked against the site's own Chinese content. 中文博客 is now a
direct link to /zh/, and the two accounts moved to the footer next to Twitter
and Slack. Applied to both the navbar and the mobile sidebar, which carried a
second copy of the same dropdown.
- The docs section was called four different things: "Projects and Docs" in the
navbar, "Projects and Documentation" in the sidebar, "Documentation" in the
<title>, and "Projects & documentation" in the H1. Both nav labels are now
"Documentation", matching the title that search engines index.
- /zh/ gains a definitional block above the article list. The site had no Chinese
page saying what SkyWalking is, so Chinese search and Chinese AI assistants had
nothing on this domain to quote. The article list is unchanged.
Fixes
- The Slack card and footer icon both pointed at http://s.apache.org/slack-invite,
which redirects to infra.apache.org/slack.html and only offers self-signup to
@apache.org addresses. Both now use the same mailto: to the dev list, which is
the only route that actually produces an invite.
- The "AI-assisted analysis" card linked to /blog/ rather than /tags/ai/, and
undersold the feature; retitled to troubleshooting and pointed at the tag page
the blog's own topic filter uses.
- .cap-tag declared display:inline-block inside a column flexbox, so every pill
stretched to the full card width. Pre-existing; more visible now that the cards
are wider.
- footer.html rendered an empty <i> for links with no iconfont glyph, so B站 and
掘金 fall back to their name as text.
Verified on a full build: 4551/4552 pages carry a canonical, 113/113 zh pages and
30 zh_tags pages report zh-CN, 106 pages carry reciprocal hreflang, JSON-LD parses
across the sample, and every internal link on the home page resolves except the
two docs paths that exist only in versions this working copy has not fetched
(verified present in skywalking v10.4.0 and horizon-ui origin/main).
At 46px in the hero's ~530px text column, "The observability platform for cloud-native and AI" wrapped to three lines with the last two words alone on the third, reading as though they had drifted off the heading. text-wrap: balance is the usual fix but is wrong here — it breaks at the hyphen in "cloud-native", which is worse. Instead the .accent span is nowrap, so "cloud-native and AI" stays one unit and the break lands at the phrase boundary after "for". Checked for the obvious side effect: at 320/375/390/414/768/1024px the accent measures 277-403px and document.scrollWidth never exceeds the viewport, so the nowrap introduces no horizontal scrolling.
Every page but the home page carried two <title> tags: partials/head.html emitted one and all 21 baseof templates repeated the identical expression. Removed from the baseofs so head.html is the sole owner. The home page's <title> was "Apache SkyWalking", which wins brand queries and nothing else, and could not be changed because the IsHome branch printed .Site.Title unconditionally. It now honours an optional `seo_title` front-matter key, set only on content/_index.html; every other page keeps "Page | Apache SkyWalking". Also: - The docs BreadcrumbList still named the section "Projects and Docs" after the nav was renamed to "Documentation". - Trimmed the comments added across this branch down to the constraints a reader cannot infer from the code, dropping the narrative ones. - CLAUDE.md: documented that `Latest` and the newest version entry must share a commitId (the canonical rule reads it, and BanyanDB drifted for two releases), plus a section on what layouts/partials/seo/ owns and the rules that are easy to break — absolute baseURL, single <title>, and content/zh being blog posts rather than a translated site.
"The observability platform for cloud-native and AI" needed 610px for its lead-in against a 530px text column, so between 1024px and 1600px — most desktop widths — it broke into three lines with a stubby "platform for" in the middle. Dropping to "Observability for" gives two clean lines at every width measured (1920 down to 375; a single line at 820px), keeps the 46px size, and matches the <title> set in the previous commit. "Apache SkyWalking" opened the lead paragraph in the same grey as the rest of the sentence; it is now bold in the heading colour.
✅ Deploy Preview for skywalking-website-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The site emitted no
rel=canonicalanywhere, andbaseURLwas"/". Hugo derives sitemap<loc>,og:urland canonical frombaseURL, so the live sitemap contained relative locations:The sitemaps.org spec requires an absolute URL there, which made all 4,704 entries unusable for discovery, and
robots.txt(a bareUser-agent: *) never advertised the sitemap anyway. Separately, GenAI/LLM monitoring shipped in 10.4 and the Horizon UI AI Assistant landed, but neither appeared on the home page.SEO
baseURL→https://skywalking.apache.org/.canonifyURLsis off and templates userelURL, so internal links are unchanged; only sitemap/og:url/canonical/RSS gain absolute URLs.layouts/robots.txt— new, advertises the sitemap.layouts/partials/seo/— canonical,<meta name="description">, en↔zhhreflang, and JSON-LD (Organization, SoftwareApplication, BlogPosting, TechArticle, BreadcrumbList) replacing the internal template's bare itemprop microdata. Wired in through the existinghooks/head-end.html, so the theme stays unforked.docs.jsrendersLatestand the newest tag from the samecommitId, so e.g./docs/main/latest/and/docs/main/v10.4.0/are the same document at two URLs with nothing saying which is authoritative. The tagged one now canonicalises to/latest/. Keyed oncommitId, so it self-corrects at each release. Every version URL stays live and served; older versions self-canonicalise and remain independently indexable.<html lang>.content/zhholds Chinese blog posts but the site is a single Hugo language, so all 113 of them declaredlang="en". Derived from the URL instead.<title>. Every page but the home page had two —head.htmlemitted one and all 21baseof.htmltemplates repeated it.head.htmlis now the sole owner.data/docs.yml— BanyanDBLatestpointed atdda5b5ed, which is the v0.10.1 tag commit, so/docs/skywalking-banyandb/latest/served v0.10.1 docs through both the v0.10.2 and v0.10.3 releases. Realigned to v0.10.3.Home page
data/docs.ymlsupports./blog/rather than/tags/ai/.Navigation
/zh/; the two accounts moved to the footer. Applied to the navbar and the mobile sidebar, which carried a second copy.<title>), "Projects & documentation" (H1). Both nav labels are now "Documentation"./zh/gains a definitional block above the article list; the site had no Chinese page saying what SkyWalking is. The article list is unchanged.Fixes
http://s.apache.org/slack-invite, which redirects toinfra.apache.org/slack.htmland only offers self-signup to@apache.orgaddresses. Both now use the samemailto:to the dev list..cap-tagdeclareddisplay:inline-blockinside a column flexbox, so every pill stretched to the full card width. Pre-existing.footer.htmlrendered an empty<i>for links with no iconfont glyph.Verification
Full local build,
hugoexit 0:rel=canonical<loc>absolute / relative in sitemapzh-CNhreflang<title>The one page without a canonical is
public/3d-map-app/index.html, the Vite SPA shell, which bypasses Hugo layouts.Version-canonical spot check:
200 sampled version-canonical targets all resolve to real built pages.
Notes for reviewers
og:localestill reportsenon Chinese pages. It comes from Hugo's_internal/opengraph.html, which cannot be overridden; a second tag would only be a conflicting duplicate. Fixing it means replacing that template call with a local partial — deliberately out of scope here.docs.jsruns in CI:virtual-genai/(present inskywalkingv10.4.0) andhorizon-ui/next/operate/ai-assistant/(present onskywalking-horizon-uimain, and a pre-existing link). Worth a glance on the preview build.CLAUDE.mddocuments thatLatestand the newest version entry must share acommitId— it is now load-bearing, not cosmetic.