Skip to content

Latest commit

 

History

History
351 lines (282 loc) · 9.21 KB

structured-data-optimization.md

File metadata and controls

351 lines (282 loc) · 9.21 KB

Structured Data Optimization

This document describes the structured data implementation in the Notes project: Schema.org JSON-LD output for search discoverability.

Overview

Structured data follows Schema.org and common search-engine guidelines. It provides machines with explicit types and fields (site, organization, author, articles, breadcrumbs, FAQ where applicable). Impact on rankings or visibility depends on search engines and content; this doc is a reference for what the project emits.

Current Implementation

1. Base Schemas (All Pages)

WebSite Schema

{
  "@context": "https://schema.org",
  "@type": "WebSite",
  "name": "Blog",
  "description": "Raw thoughts on fatherhood, masculinity, and modern life...",
  "url": "https://notes.antoniwan.online",
  "inLanguage": "en-US",
  "publisher": { "@type": "Person", "name": "Antonio Rodriguez Martinez" },
  "potentialAction": {
    "@type": "SearchAction",
    "target": {
      "@type": "EntryPoint",
      "urlTemplate": "https://notes.antoniwan.online/search?q={search_term_string}"
    },
    "query-input": "required name=search_term_string"
  }
}

Organization Schema

{
  "@context": "https://schema.org",
  "@type": "Organization",
  "name": "Blog",
  "url": "https://notes.antoniwan.online",
  "logo": { "@type": "ImageObject", "url": "...", "width": 512, "height": 512 },
  "sameAs": ["https://twitter.com/antoniwan", "https://github.com/antoniwan"],
  "description": "Personal Blog & Content Creation",
  "foundingDate": "2024",
  "areaServed": "Worldwide",
  "serviceType": "Personal Blog & Content Creation"
}

Person Schema (Author)

{
  "@context": "https://schema.org",
  "@type": "Person",
  "name": "Antonio Rodriguez Martinez",
  "url": "https://antoniwan.online",
  "jobTitle": "Software Engineer & Writer",
  "worksFor": { "@type": "Organization", "name": "Blog" },
  "knowsAbout": ["Software Development", "Personal Growth", "Mental Health", "Parenting"],
  "description": "Software engineer and writer exploring fatherhood, masculinity, and modern life...",
  "alumniOf": { "@type": "Organization", "name": "Software Engineering Community" },
  "hasOccupation": {
    "@type": "Occupation",
    "name": "Software Engineer",
    "description": "Building digital solutions and exploring technology's impact on modern life"
  }
}

2. Enhanced Article Schema (Blog Posts)

BlogPosting Schema

{
  "@context": "https://schema.org",
  "@type": "BlogPosting",
  "headline": "Article Title",
  "description": "Article description...",
  "image": "https://notes.antoniwan.online/images/hero-image.jpg",
  "datePublished": "2025-01-01T00:00:00.000Z",
  "dateModified": "2025-01-01T00:00:00.000Z",
  "author": { "@type": "Person", "name": "Antonio Rodriguez Martinez" },
  "publisher": { "@type": "Organization", "name": "Blog" },
  "keywords": "empathy, psychology, mental-health, consciousness",
  "timeRequired": "PT5M",
  "url": "https://notes.antoniwan.online/p/article-slug",
  "inLanguage": "en-US",
  "articleSection": "psychology",
  "wordCount": 1500,
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "https://notes.antoniwan.online/p/article-slug"
  },
  "isPartOf": { "@type": "Blog", "name": "Blog", "url": "https://notes.antoniwan.online" },
  "about": [
    { "@type": "Thing", "name": "psychology" },
    { "@type": "Thing", "name": "integration-growth" }
  ],
  "hasPart": {
    "@type": "WebPageElement",
    "name": "Table of Contents",
    "description": "Structured navigation for this article"
  }
}

Breadcrumb Schema (for Blog Posts)

{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://notes.antoniwan.online"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "psychology",
      "item": "https://notes.antoniwan.online/category/psychology/"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "Article Title",
      "item": "https://notes.antoniwan.online/p/article-slug"
    }
  ]
}

3. Collection Page Schemas (Categories & Tags)

CollectionPage Schema

{
  "@context": "https://schema.org",
  "@type": "CollectionPage",
  "name": "Category Name",
  "description": "Category description...",
  "url": "https://notes.antoniwan.online/category/category-name/",
  "mainEntity": {
    "@type": "ItemList",
    "numberOfItems": 25,
    "itemListElement": [
      {
        "@type": "ListItem",
        "position": 1,
        "item": {
          "@type": "BlogPosting",
          "headline": "Post Title",
          "description": "Post description...",
          "url": "https://notes.antoniwan.online/p/post-slug",
          "datePublished": "2025-01-01T00:00:00.000Z",
          "author": { "@type": "Person", "name": "Antonio Rodriguez Martinez" }
        }
      }
    ]
  },
  "breadcrumb": { "@type": "BreadcrumbList", "itemListElement": [...] }
}

Advanced Schema Types

1. FAQ Schema (Auto-detected)

Automatically generated for content with Q&A patterns:

{
  "@context": "https://schema.org",
  "@type": "FAQPage",
  "mainEntity": [
    {
      "@type": "Question",
      "name": "What is empathy?",
      "acceptedAnswer": {
        "@type": "Answer",
        "text": "Empathy is the ability to understand and share the feelings of others..."
      }
    }
  ]
}

2. HowTo Schema (for Tutorials)

For instructional content:

{
  "@context": "https://schema.org",
  "@type": "HowTo",
  "name": "How to Practice Empathy",
  "description": "Step-by-step guide to developing empathy...",
  "totalTime": "PT30M",
  "step": [
    {
      "@type": "HowToStep",
      "position": 1,
      "name": "Listen Actively",
      "text": "Focus on what the other person is saying without interrupting..."
    }
  ]
}

3. Review Schema (for Reviews)

For review content:

{
  "@context": "https://schema.org",
  "@type": "Review",
  "name": "Book Review: Meditations",
  "description": "Review of Marcus Aurelius' Meditations...",
  "reviewRating": {
    "@type": "Rating",
    "ratingValue": 5,
    "bestRating": 5,
    "worstRating": 1
  },
  "author": { "@type": "Person", "name": "Antonio Rodriguez Martinez" },
  "reviewBody": "This book changed my perspective on life..."
}

Implementation Details

1. Automatic Generation

  • Structured data is automatically generated from content frontmatter
  • No manual schema creation required
  • Consistent implementation across all content types

2. Content Analysis

  • Automatic FAQ detection from markdown content
  • Content type classification for appropriate schema selection
  • Dynamic breadcrumb generation

3. Validation

  • Built-in validation for common structured data issues
  • Error and warning reporting
  • Circular reference detection

SEO Benefits

1. Enhanced Search Results

  • Rich snippets in search results
  • Featured snippet opportunities
  • Better click-through rates

2. Improved Crawling

  • Clear content structure for search engines
  • Better understanding of content relationships
  • Improved indexing efficiency

3. User Experience

  • Rich search result previews
  • Better content discovery
  • Enhanced social media sharing

Best Practices Implemented

1. Schema.org Compliance

  • All schemas follow official Schema.org specifications
  • Proper @context and @type usage
  • Valid property values

2. Google Guidelines

  • Follows Google's structured data guidelines
  • Proper nesting and relationships
  • Valid JSON-LD format

3. Performance

  • Efficient schema generation
  • Minimal impact on page load
  • Optimized for search engine parsing

Testing and Validation

1. Built-in Validation

import { validateStructuredData } from '../utils/structuredData';

const validation = validateStructuredData(schema);
console.log(validation.isValid); // true/false
console.log(validation.errors); // array of errors
console.log(validation.warnings); // array of warnings

2. Google Testing Tools

  • Use Google's Rich Results Test
  • Validate with Google Search Console
  • Monitor structured data performance

3. Debugging

import { generateStructuredDataSummary } from '../utils/structuredData';

const summary = generateStructuredDataSummary(schemas);
console.log(summary); // Detailed validation report

Future Enhancements

1. Content-Specific Schemas

  • Recipe schemas for food content
  • Event schemas for time-sensitive content
  • Product schemas for review content

2. Dynamic Content Analysis

  • AI-powered content classification
  • Automatic schema selection
  • Content quality scoring

3. Performance Monitoring

  • Schema performance tracking
  • Search result improvement metrics
  • User engagement correlation

Conclusion

Our structured data implementation provides a solid foundation for search engine optimization while maintaining flexibility for future enhancements. The automatic generation and validation systems ensure consistent, high-quality structured data across all content types, maximizing search engine discoverability and improving user experience.

For questions or suggestions about structured data implementation, please refer to the development team or consult the Schema.org documentation.