feat(docs): add JSON-LD structured data for SEO#306
Merged
Conversation
- Add WebSite schema on all pages with organization info - Add BreadcrumbList schema dynamically based on URL path - Add SoftwareApplication schema on home/installation pages - Add FAQPage schema support via frontmatter (troubleshooting pages) - Add HowTo schema support via frontmatter (guide pages) - Add lang="en-US" attribute to HTML - Add outline config for table of contents (H2-H3) - Improve default meta description fallback Closes #305
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
There was a problem hiding this comment.
Pull request overview
This PR enhances the documentation site's SEO by implementing JSON-LD structured data schemas following Google's guidelines. The changes add machine-readable metadata that helps search engines better understand and display the documentation content in search results.
Changes:
- Added JSON-LD structured data generation function supporting WebSite, BreadcrumbList, SoftwareApplication, FAQPage, and HowTo schemas
- Added FAQ frontmatter to four troubleshooting pages (index, docker, connection, clients) with common questions and answers
- Added HowTo frontmatter to the quick-start guide with step-by-step setup instructions
- Improved default meta descriptions and added lang="en-US" attribute for better SEO
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/.vitepress/config.mts | Implements JSON-LD structured data generation logic with TypeScript types, adds transformHead integration, and improves SEO configuration (lang, description, outline) |
| docs/troubleshooting/index.md | Adds FAQ schema with 4 common troubleshooting questions covering connection, configuration, token testing, and logs |
| docs/troubleshooting/docker.md | Adds FAQ schema with 3 Docker-specific questions about port conflicts, image errors, and viewing logs |
| docs/troubleshooting/connection.md | Adds FAQ schema with 5 connection-related questions covering 401/403 errors, self-signed certificates, missing tools, and timeouts |
| docs/troubleshooting/clients.md | Adds FAQ schema with 3 client configuration questions about detection, server visibility, and JSON validation |
| docs/guide/quick-start.md | Adds HowTo schema with 3 setup steps for getting GitLab MCP running with an AI agent |
- Add siteUrl variable combining hostname and base path - Update WebSite, BreadcrumbList, and SoftwareApplication schemas - Remove trailing slash from canonical siteUrl
- Import version from package.json using createRequire - Add TOOL_COUNT/ENTITY_COUNT env vars with fallback defaults - Create shared siteDescription for all meta tags
gitlab-mcp is an OSS project under sw.foundation, not structured.world
|
🎉 This PR is included in version 6.59.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
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
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.
Summary
Improves documentation site SEO according to Google guidelines by adding JSON-LD structured data schemas.
Changes
Structured Data (JSON-LD)
Technical SEO
lang="en-US"attribute added to HTMLFiles Changed
docs/.vitepress/config.mts- JSON-LD generation logicdocs/troubleshooting/*.md- FAQ frontmatter addeddocs/guide/quick-start.md- HowTo frontmatter addedVerification
After merge, validate with:
Test plan
yarn lintpassesyarn testpasses (4593 tests)yarn docs:buildsucceedsCloses #305