Repository navigation
[Epic] Fix docs URLs, language navigation and website reporting #773
Description
I want to track the website work in one place, starting with docs URLs and indexing, then language navigation, OSS Health and analytics. Existing issues and PRs are linked below, follow-ups should cover what they leave open.
Checked on production on 2026-10-23: /docs/v1/getting-started/install-cozystack/ returns HTTP 404, /docs/install/talos/ sends readers to v0, and sampled archive pages have conflicting robots tags. /docs/roadmap/ and /roadmap/ already resolve, keep them in regression checks.
Links from /ru/docs/ lead to English version pages. Some links with /ru/ added lead to missing pages, including /ru/demo/. DevStats and OSS Insight share the same GitHub data collector and repeat contributor tables, while their published snapshots still date from August.
Docs and navigation
- A1. Give current docs a permanent indexable URL that survives minor releases. Start from PR 772, which serves
/docs/latest/and/docs/v1/copies but keeps canonical URLs on the numbered version. Decide archive canonical and noindex rules before changing them. - A2. Map legacy
/docs/v1/*and unversioned docs URLs to their current equivalents, including renamed pages. Verify HTTP responses without JavaScript, query strings and fragments. Keep historical version URLs available. - A3. Remove noindex pages from sitemaps, emit one robots tag per content page, and check that
latest_version_idmatches the published version. Sitemap and canonical URLs must agree with A1. - A4. Update links in the main repository README,
llms.txt, navigation, footer and blog. Preserve intentional references to historical versions. PR 745 covers some broken links and anchors. - A5. Add production-build checks for old URLs, canonical, robots, sitemaps and release rollover. Extend issue 496, coordinate with issue 653 for PR builds including
next/. - A6. Keep the selected language when a translation exists. Show a clear fallback to the original when it does not, without generating missing language URLs. Cover navigation, content links, footer and version switching. Coordinate with PR 767, which changes version navigation.
OSS Health
- A7. Decide whether DevStats and OSS Insight need separate pages. Compare their metrics, remove repeated sections and name the real data source. Distinguish period totals from values measured at collection time.
- A8. Publish current snapshots and make the collection-to-publication process predictable. PR 770 contains the same snapshot files as PR 674 and PR 730. Choose one publication path, then define who handles monthly updates and how overdue data is reported. Show collection date and measurement period.
Analytics and content
- A9. After deployment, resubmit sitemaps in Search Console, check indexing exclusions and 404s, and request indexing for installation, Talm and platform guides. Compare coverage and organic traffic with a recorded baseline over 4-6 weeks.
- A10. Create separate reporting segments for suspected bots and referral spam, keeping raw data available. Check exclusion rules against several signals before using the filtered figures.
- A11. Compare suspicious analytics hits with available HTTP delivery data to distinguish site requests from hits sent directly to analytics. Choose filtering or delivery changes from that evidence.
- A12. Measure command copying, GitHub and community links, support visits and documentation search. Verify events arrive and agree which ones count as key events.
- A13. Investigate the reported drop in GitHub referrals using repository traffic, outbound links and attribution data.
- A14. Report AI referrals and dashboard-to-docs traffic separately. Dashboard referrals are a usage signal, not a count of unique installations.
- A15. Build a content plan from non-brand Search Console queries: Talm, Talos installation, hairpin proxy, LINSTOR/ZFS, Blockstor and platform comparisons. Reuse PR 667, PR 552 and issue 337 where they fit. PR 640 covers blog publishing tools.
Start with A1-A6, then A8. Analytics work needs the property owners, A9 follows deployment. Traffic recovery targets stay separate from code acceptance criteria.
Activity