mirror of
https://github.com/MODSetter/SurfSense.git
synced 2026-04-25 00:36:31 +02:00
feat: enhance SurfSense with new skills, blog section, and improve SEO metadata
Some checks failed
Build and Push Docker Images / tag_release (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-24.04-arm, linux/arm64, arm64) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-latest, linux/amd64, amd64) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_web, ./surfsense_web/Dockerfile, web, surfsense-web, ubuntu-24.04-arm, linux/arm64, arm64) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_web, ./surfsense_web/Dockerfile, web, surfsense-web, ubuntu-latest, linux/amd64, amd64) (push) Has been cancelled
Build and Push Docker Images / create_manifest (backend, surfsense-backend) (push) Has been cancelled
Build and Push Docker Images / create_manifest (web, surfsense-web) (push) Has been cancelled
Some checks failed
Build and Push Docker Images / tag_release (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-24.04-arm, linux/arm64, arm64) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_backend, ./surfsense_backend/Dockerfile, backend, surfsense-backend, ubuntu-latest, linux/amd64, amd64) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_web, ./surfsense_web/Dockerfile, web, surfsense-web, ubuntu-24.04-arm, linux/arm64, arm64) (push) Has been cancelled
Build and Push Docker Images / build (./surfsense_web, ./surfsense_web/Dockerfile, web, surfsense-web, ubuntu-latest, linux/amd64, amd64) (push) Has been cancelled
Build and Push Docker Images / create_manifest (backend, surfsense-backend) (push) Has been cancelled
Build and Push Docker Images / create_manifest (web, surfsense-web) (push) Has been cancelled
- Added multiple new skills to skills-lock.json from the repository `aaron-he-zhu/seo-geo-claude-skills`. - Introduced `fuzzy-search` dependency in package.json for improved search functionality. - Updated pnpm-lock.yaml to include the new `fuzzy-search` package. - Enhanced SEO metadata across various pages, including canonical links and descriptions for better search visibility. - Improved layout and structure of several components, including the homepage and changelog, to enhance user experience.
This commit is contained in:
parent
61b3f0d7e3
commit
7ea840dbb2
120 changed files with 25729 additions and 352 deletions
|
|
@ -0,0 +1,444 @@
|
|||
# Schema Markup Validation Guide
|
||||
|
||||
Complete reference for validating, testing, and troubleshooting structured data.
|
||||
|
||||
## Validation Tools
|
||||
|
||||
### Google Rich Results Test
|
||||
- **URL**: https://search.google.com/test/rich-results
|
||||
- **Purpose**: Check if your schema is eligible for Google rich results
|
||||
- **Tests**: Live URL or code snippet
|
||||
- **Output**: Errors, warnings, eligible rich result types
|
||||
|
||||
### Schema.org Validator
|
||||
- **URL**: https://validator.schema.org/
|
||||
- **Purpose**: Validate against official Schema.org specification
|
||||
- **Tests**: URL, code snippet, or microdata
|
||||
- **Output**: Technical validation errors
|
||||
|
||||
### Google Search Console
|
||||
- **Location**: Search Console → Enhancements section
|
||||
- **Purpose**: Monitor rich results performance and errors at scale
|
||||
- **Reports**: Rich results status, coverage, issues over time
|
||||
|
||||
---
|
||||
|
||||
## Common JSON-LD Syntax Errors
|
||||
|
||||
### Trailing Commas
|
||||
|
||||
**Error**: Invalid JSON syntax
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Article",
|
||||
"headline": "Title", ← Trailing comma here
|
||||
}
|
||||
```
|
||||
|
||||
**Fix**: Remove the comma after the last property
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org",
|
||||
"@type": "Article",
|
||||
"headline": "Title"
|
||||
}
|
||||
```
|
||||
|
||||
### Missing Required Quotes
|
||||
|
||||
**Error**: Property names must be quoted
|
||||
```json
|
||||
{
|
||||
@context: "https://schema.org"
|
||||
}
|
||||
```
|
||||
|
||||
**Fix**: Quote all property names
|
||||
```json
|
||||
{
|
||||
"@context": "https://schema.org"
|
||||
}
|
||||
```
|
||||
|
||||
### Incorrect Date Format
|
||||
|
||||
**Error**: Invalid date format
|
||||
```json
|
||||
{
|
||||
"datePublished": "01/15/2024"
|
||||
}
|
||||
```
|
||||
|
||||
**Fix**: Use ISO 8601 format
|
||||
```json
|
||||
{
|
||||
"datePublished": "2024-01-15T08:00:00+00:00"
|
||||
}
|
||||
```
|
||||
|
||||
### Relative URLs Instead of Absolute
|
||||
|
||||
**Error**: Relative URLs are not allowed
|
||||
```json
|
||||
{
|
||||
"image": "/images/photo.jpg"
|
||||
}
|
||||
```
|
||||
|
||||
**Fix**: Use absolute URLs
|
||||
```json
|
||||
{
|
||||
"image": "https://example.com/images/photo.jpg"
|
||||
}
|
||||
```
|
||||
|
||||
### Incorrect Array Syntax
|
||||
|
||||
**Error**: Multiple values not in array
|
||||
```json
|
||||
{
|
||||
"image": "url1.jpg", "url2.jpg"
|
||||
}
|
||||
```
|
||||
|
||||
**Fix**: Use array brackets for multiple values
|
||||
```json
|
||||
{
|
||||
"image": ["url1.jpg", "url2.jpg"]
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Required vs Recommended Properties
|
||||
|
||||
### FAQPage Schema
|
||||
|
||||
| Property | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| @type | Required | Must be "FAQPage" |
|
||||
| mainEntity | Required | Array of Question objects |
|
||||
| Question.name | Required | The question text |
|
||||
| Answer.text | Required | The answer text |
|
||||
|
||||
**Minimum**: 2 Q&A pairs
|
||||
|
||||
### HowTo Schema
|
||||
|
||||
| Property | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| @type | Required | Must be "HowTo" |
|
||||
| name | Required | Title of the how-to |
|
||||
| step | Required | Array of HowToStep objects |
|
||||
| step.text | Required | Step instructions |
|
||||
| image | Recommended | Improves visibility |
|
||||
| totalTime | Recommended | Shows duration in results |
|
||||
| supply | Recommended | Lists materials needed |
|
||||
| tool | Recommended | Lists tools needed |
|
||||
|
||||
**Minimum**: 2 steps with text
|
||||
|
||||
### Article Schema
|
||||
|
||||
| Property | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| @type | Required | Article/BlogPosting/NewsArticle |
|
||||
| headline | Required | Max 110 characters |
|
||||
| image | Required | Minimum 1200px wide |
|
||||
| datePublished | Required | ISO 8601 format |
|
||||
| author | Required | Person or Organization |
|
||||
| publisher | Required | Organization with logo |
|
||||
| publisher.logo | Required | Max 600px wide, 60px high |
|
||||
| dateModified | Recommended | Update when content changes |
|
||||
| description | Recommended | Improves display |
|
||||
|
||||
### Product Schema
|
||||
|
||||
| Property | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| @type | Required | Must be "Product" |
|
||||
| name | Required | Product name |
|
||||
| image | Required | Product images |
|
||||
| description | Recommended | Product description |
|
||||
| offers | Recommended | Required for price display |
|
||||
| offers.price | Recommended | Required for price display |
|
||||
| offers.priceCurrency | Recommended | Required for price display |
|
||||
| offers.availability | Recommended | Stock status |
|
||||
| aggregateRating | Recommended | Required for star ratings |
|
||||
| review | Recommended | Individual reviews |
|
||||
| sku | Recommended | Product identifier |
|
||||
| brand | Recommended | Brand information |
|
||||
|
||||
### LocalBusiness Schema
|
||||
|
||||
| Property | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| @type | Required | LocalBusiness or subtype |
|
||||
| name | Required | Business name |
|
||||
| address | Required | PostalAddress object |
|
||||
| address.streetAddress | Required | Street address |
|
||||
| address.addressLocality | Required | City |
|
||||
| address.addressRegion | Required | State/province |
|
||||
| address.postalCode | Required | ZIP/postal code |
|
||||
| address.addressCountry | Required | Country code |
|
||||
| geo | Recommended | Latitude/longitude |
|
||||
| telephone | Recommended | Phone number |
|
||||
| openingHoursSpecification | Recommended | Business hours |
|
||||
| priceRange | Recommended | Price range indicator |
|
||||
| aggregateRating | Recommended | Customer ratings |
|
||||
|
||||
### Organization Schema
|
||||
|
||||
| Property | Status | Notes |
|
||||
|----------|--------|-------|
|
||||
| @type | Required | Must be "Organization" |
|
||||
| name | Required | Organization name |
|
||||
| url | Required | Website URL |
|
||||
| logo | Recommended | Brand logo |
|
||||
| sameAs | Recommended | Social media profiles |
|
||||
| contactPoint | Recommended | Contact information |
|
||||
|
||||
---
|
||||
|
||||
## Google Rich Result Eligibility Requirements
|
||||
|
||||
### FAQ Rich Results
|
||||
|
||||
**Eligibility checklist**:
|
||||
- [ ] Minimum 2 Q&A pairs
|
||||
- [ ] Questions are actual questions (contain "?")
|
||||
- [ ] Answers are complete and comprehensive
|
||||
- [ ] Content matches visible page content exactly
|
||||
- [ ] Not a forum or Q&A page where users can submit answers
|
||||
- [ ] Not advertising or promotional in nature
|
||||
- [ ] Not for medical, legal, or financial advice without proper E-E-A-T
|
||||
|
||||
**Ineligible content**:
|
||||
- Medical advice without credentials
|
||||
- Legal advice
|
||||
- Product/service comparisons that are promotional
|
||||
- User-generated Q&A (use QAPage instead)
|
||||
|
||||
### How-To Rich Results
|
||||
|
||||
**Eligibility checklist**:
|
||||
- [ ] Minimum 2 steps with clear instructions
|
||||
- [ ] Complete process from start to finish
|
||||
- [ ] Each step has meaningful text (not just a title)
|
||||
- [ ] Not advertising or promotional
|
||||
- [ ] Not harmful or dangerous content
|
||||
- [ ] Steps are actionable and practical
|
||||
|
||||
**Ineligible content**:
|
||||
- Single-step processes
|
||||
- Recipes (use Recipe schema instead)
|
||||
- Promotional tutorials
|
||||
|
||||
### Product Rich Results
|
||||
|
||||
**For price display**:
|
||||
- [ ] Valid Product schema
|
||||
- [ ] `offers` with `price` property
|
||||
- [ ] `priceCurrency` specified
|
||||
- [ ] `availability` status
|
||||
|
||||
**For review stars**:
|
||||
- [ ] Valid `aggregateRating` OR individual `review`
|
||||
- [ ] Minimum 1 review for individual review display
|
||||
- [ ] Honest, unbiased reviews (not paid/incentivized)
|
||||
|
||||
**For product markup**:
|
||||
- [ ] `name` property present
|
||||
- [ ] At least one `image`
|
||||
- [ ] Valid product type (not person, organization, etc.)
|
||||
|
||||
### Article Rich Results
|
||||
|
||||
**Eligibility checklist**:
|
||||
- [ ] Valid Article/BlogPosting/NewsArticle schema
|
||||
- [ ] High-quality, original content
|
||||
- [ ] Proper `publisher` with valid logo
|
||||
- [ ] Valid `author` information
|
||||
- [ ] Images meet size requirements (1200px wide)
|
||||
- [ ] Not short-form content (minimum ~300 words)
|
||||
|
||||
---
|
||||
|
||||
## Testing Workflow
|
||||
|
||||
### Initial Implementation
|
||||
|
||||
1. **Add schema to development/staging environment**
|
||||
2. **Validate syntax at validator.schema.org**
|
||||
- Paste code or test URL
|
||||
- Fix all errors before proceeding
|
||||
3. **Test at Google Rich Results Test**
|
||||
- Check for Google-specific issues
|
||||
- Verify eligible rich result types
|
||||
4. **Visual inspection**
|
||||
- View page source to confirm schema is present
|
||||
- Check JSON formatting in browser
|
||||
|
||||
### Pre-Launch Testing
|
||||
|
||||
1. **Test on staging URL with Rich Results Test**
|
||||
2. **Verify all required properties present**
|
||||
3. **Confirm content matches visible page content**
|
||||
4. **Check for policy violations**
|
||||
5. **Test multiple schema types if combining**
|
||||
6. **Validate images are accessible and meet size requirements**
|
||||
|
||||
### Post-Launch Monitoring
|
||||
|
||||
1. **Submit sitemap to Google Search Console**
|
||||
2. **Monitor Enhancements reports**
|
||||
- Check for validation errors
|
||||
- Watch for policy violations
|
||||
- Track rich result impressions
|
||||
3. **Re-test pages if content changes**
|
||||
4. **Update `dateModified` when updating content**
|
||||
5. **Fix errors within 30 days to avoid rich result removal**
|
||||
|
||||
---
|
||||
|
||||
## Common Policy Violations
|
||||
|
||||
### Content Mismatch
|
||||
|
||||
**Violation**: Schema content doesn't match visible page content
|
||||
|
||||
**Example**: FAQ schema includes Q&A pairs not visible on page
|
||||
|
||||
**Fix**: Ensure all structured data reflects actual page content exactly
|
||||
|
||||
### Deceptive Content
|
||||
|
||||
**Violation**: Schema contains misleading information
|
||||
|
||||
**Example**: Product reviews that are fake or incentivized
|
||||
|
||||
**Fix**: Only include genuine, verifiable information
|
||||
|
||||
### Spammy Markup
|
||||
|
||||
**Violation**: Excessive or irrelevant schema
|
||||
|
||||
**Example**: Adding Product schema to every blog post
|
||||
|
||||
**Fix**: Only use schema types relevant to page content
|
||||
|
||||
### Hidden Content
|
||||
|
||||
**Violation**: Schema references content hidden from users
|
||||
|
||||
**Example**: FAQ answers only in schema, not visible on page
|
||||
|
||||
**Fix**: Make all schema content visible to users
|
||||
|
||||
### Promotional Content in FAQ
|
||||
|
||||
**Violation**: Using FAQ schema for promotional purposes
|
||||
|
||||
**Example**: Questions like "Why is [Brand] the best?"
|
||||
|
||||
**Fix**: Use neutral, informational questions
|
||||
|
||||
---
|
||||
|
||||
## Debugging Common Issues
|
||||
|
||||
### Schema Not Appearing in Rich Results Test
|
||||
|
||||
**Possible causes**:
|
||||
- JSON syntax error (validate at validator.schema.org)
|
||||
- Schema in incorrect location (should be in `<head>` or `<body>`)
|
||||
- Script tag missing `type="application/ld+json"`
|
||||
- Content served dynamically after page load (bot can't see it)
|
||||
|
||||
**Debug steps**:
|
||||
1. View page source (not inspect element)
|
||||
2. Search for `"@type"`
|
||||
3. Copy JSON to validator.schema.org
|
||||
4. Fix syntax errors
|
||||
|
||||
### Rich Results Not Showing in Search
|
||||
|
||||
**Possible causes**:
|
||||
- Schema is new (can take days/weeks to appear)
|
||||
- Page not indexed by Google
|
||||
- Schema has errors in Search Console
|
||||
- Content doesn't meet quality guidelines
|
||||
- Competition for rich results is high
|
||||
|
||||
**Debug steps**:
|
||||
1. Check Search Console → Enhancements
|
||||
2. Use URL Inspection tool to request indexing
|
||||
3. Verify schema passes Rich Results Test
|
||||
4. Check for manual actions
|
||||
|
||||
### Warnings vs Errors
|
||||
|
||||
**Errors** (must fix):
|
||||
- Invalid syntax
|
||||
- Missing required properties
|
||||
- Invalid property values
|
||||
- Schema type doesn't exist
|
||||
|
||||
**Warnings** (should fix when possible):
|
||||
- Missing recommended properties
|
||||
- Suboptimal property values
|
||||
- Non-standard extensions
|
||||
- Property not recognized for this type
|
||||
|
||||
---
|
||||
|
||||
## Schema Maintenance Checklist
|
||||
|
||||
### Monthly
|
||||
- [ ] Check Search Console for new errors
|
||||
- [ ] Verify rich results are still appearing
|
||||
- [ ] Update `dateModified` on changed content
|
||||
|
||||
### Quarterly
|
||||
- [ ] Audit all schema implementations
|
||||
- [ ] Test key pages with Rich Results Test
|
||||
- [ ] Update any outdated information (prices, dates, etc.)
|
||||
- [ ] Check for new schema types relevant to your content
|
||||
|
||||
### After Content Changes
|
||||
- [ ] Update schema to match new content
|
||||
- [ ] Update `dateModified` timestamp
|
||||
- [ ] Re-validate with Rich Results Test
|
||||
- [ ] Request re-indexing in Search Console if major changes
|
||||
|
||||
### After Site Migration
|
||||
- [ ] Verify schema preserved on new URLs
|
||||
- [ ] Update all absolute URLs in schema
|
||||
- [ ] Submit new sitemap
|
||||
- [ ] Monitor for errors in new domain's Search Console
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference: Error Messages and Fixes
|
||||
|
||||
| Error Message | Cause | Fix |
|
||||
|---------------|-------|-----|
|
||||
| "Missing required field" | Required property not included | Add the required property |
|
||||
| "Invalid date format" | Date not in ISO 8601 | Use format: 2024-01-15T08:00:00+00:00 |
|
||||
| "URL is not absolute" | Relative URL used | Add full URL with https:// |
|
||||
| "Unexpected token" | JSON syntax error | Check for missing quotes, brackets, commas |
|
||||
| "This markup is not eligible for rich results" | Schema type or content doesn't qualify | Review eligibility requirements |
|
||||
| "Image too small" | Image doesn't meet size requirements | Use image at least 1200px wide |
|
||||
| "The attribute price is required" | Product missing price | Add offers.price property |
|
||||
| "Logo must be 600x60 or smaller" | Publisher logo too large | Resize logo to meet requirements |
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **Schema.org Documentation**: https://schema.org/
|
||||
- **Google Search Central**: https://developers.google.com/search/docs/appearance/structured-data
|
||||
- **Rich Results Test**: https://search.google.com/test/rich-results
|
||||
- **Schema Validator**: https://validator.schema.org/
|
||||
- **JSON-LD Playground**: https://json-ld.org/playground/
|
||||
Loading…
Add table
Add a link
Reference in a new issue