### Start Discourse Server

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Starts the Discourse development server to test the plugin locally.

```bash
bin/rails server
```

--------------------------------

### Install Plugin via Git

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Use this command to clone the plugin repository into your Discourse instance and rebuild the application.

```bash
cd /var/discourse
git clone https://github.com/kaktaknet/discourse-rich-json-ld-microdata.git plugins/discourse-rich-json-ld-microdata
./launcher rebuild app
```

--------------------------------

### Install Plugin Dependencies

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Installs the necessary Ruby gems for the plugin using Bundler.

```bash
bundle install
```

--------------------------------

### Verify Plugin Installation

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Verify the plugin is working by checking for the 'data-rich-microdata' attribute in the page source.

```html
<meta property="og:type" content="article" data-rich-microdata="og">
<script type="application/ld+json">
{
  "@context": "https://schema.org",
  "@type": "QAPage",
  ...
}
</script>
```

--------------------------------

### Server Translations Example (French)

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Provides an example of server-side translations in French for site settings and various plugin components like breadcrumbs, Open Graph, Twitter Cards, profile pages, and interaction statistics.

```yaml
fr:
  site_settings:
    rich_microdata_enabled: "Activer le plugin Rich Microdata"
    rich_microdata_cache_ttl: "Durée du cache en secondes"
    # ... more settings

  discourse_rich_microdata:
    breadcrumb:
      home: "Accueil"

    open_graph:
      category_description: "Discussions dans %{category_name}"
      user_description: "Profil de %{user_name}"

    twitter_card:
      label_replies: "Réponses"
      label_author: "Auteur"
      label_topics: "Sujets"
      label_posts: "Messages"
      label_karma: "Karma"

    profile_page:
      title: "Profil de %{user_name}"

    interaction_stats:
      created_topics: "Sujets créés"
      written_replies: "Réponses écrites"
      received_likes: "J'aime reçus"
      read_posts: "Messages lus"
      number_of_topics: "Nombre de sujets"
      number_of_replies: "Nombre de réponses"
```

--------------------------------

### Test Specific Builder in Rails Console

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Example of how to instantiate and build output for a specific builder (e.g., `QAPageBuilder`) with sample data in the Rails console.

```ruby
data = { title: "Test", posts: [...] }
builder = DiscourseRichMicrodata::Builders::QAPageBuilder.new(data, {})
puts JSON.pretty_generate(builder.build)
```

--------------------------------

### Update CHANGELOG.md for Release

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Example of how to update the CHANGELOG.md file with new version information, including the version number, release date, and a summary of changes.

```markdown
### Version 2.1.0 (2025-01-20)
- ✨ Added X feature
- 🐛 Fixed Y bug
- 📚 Improved Z documentation
```

--------------------------------

### Discourse Solved Plugin Integration

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Example demonstrating how the plugin detects and includes accepted answers in the QAPage schema when integrated with the Discourse Solved plugin.

```ruby
# When topic has accepted answer
topic = Topic.find(123)
topic.custom_fields['accepted_answer_post_id']  # => 5

# Generated QAPage includes acceptedAnswer
result = MetaGeneratorService.generate_for_topic(topic)
schema = JSON.parse(result[:body].match(/<script type="application\/ld\+json">(.*?)<\/script>/m)[1])

schema['mainEntity']['acceptedAnswer']['acceptedAnswerStatus']
# => "Accepted"
```

--------------------------------

### Builder Pattern Implementation

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Example of implementing a custom builder class by extending BaseBuilder. Includes structure for context, type, schema definition, and helper methods.

```ruby
module DiscourseRichMicrodata
  module Builders
    class YourBuilder < BaseBuilder
      def build
        # Return Hash or String
        {
          "@context" => SCHEMA_CONTEXT,
          "@type" => "YourType",
          # ... your schema
        }.tap { |schema| compact_hash(schema) }
      end

      private

      def your_helper_method
        # Helper logic
      end
    end
  end
end
```

--------------------------------

### QAPage Schema Example

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Use this schema to mark up a question and answer page. It includes details about the question, its author, answers, and related interactions. Ensure all URLs and identifiers are correctly set.

```json
{
  "@context": "https://schema.org",
  "@type": "QAPage",
  "@id": "https://forum.com/t/how-to-optimize-postgresql/123",
  "url": "https://forum.com/t/how-to-optimize-postgresql/123",
  "name": "How to optimize PostgreSQL queries?",
  "description": "My queries are running 3.5 seconds, need help optimizing...",
  "inLanguage": "en-US",
  "isPartOf": {
    "@id": "https://forum.com/#website"
  },
  "breadcrumb": {
    "@id": "https://forum.com/t/how-to-optimize-postgresql/123#breadcrumb"
  },
  "mainEntity": {
    "@type": "Question",
    "@id": "https://forum.com/t/how-to-optimize-postgresql/123#question",
    "name": "How to optimize PostgreSQL queries?",
    "text": "My queries are running 3.5 seconds on a table with 10M rows. Using simple SELECT with WHERE clause. How can I speed this up?",
    "answerCount": 12,
    "upvoteCount": 45,
    "dateCreated": "2025-01-15T10:30:00Z",
    "dateModified": "2025-01-16T14:20:00Z",
    "author": {
      "@type": "Person",
      "@id": "https://forum.com/u/john-dev#person",
      "name": "John Developer",
      "url": "https://forum.com/u/john-dev",
      "image": {
        "@type": "ImageObject",
        "url": "https://forum.com/user_avatar/john-dev/240/123.png",
        "width": 240,
        "height": 240
      },
      "interactionStatistic": [
        {
          "@type": "InteractionCounter",
          "interactionType": "https://schema.org/WriteAction",
          "userInteractionCount": 87,
          "description": "Created topics"
        },
        {
          "@type": "InteractionCounter",
          "interactionType": "https://schema.org/CommentAction",
          "userInteractionCount": 523,
          "description": "Written replies"
        },
        {
          "@type": "InteractionCounter",
          "interactionType": "https://schema.org/LikeAction",
          "userInteractionCount": 1249,
          "description": "Received likes"
        }
      ]
    },
    "about": [
      {
        "@type": "Thing",
        "@id": "https://forum.com/tag/postgresql",
        "name": "postgresql",
        "description": "PostgreSQL database management system"
      },
      {
        "@type": "Thing",
        "@id": "https://forum.com/tag/performance",
        "name": "performance",
        "description": "Performance optimization topics"
      }
    ],
    "interactionStatistic": [
      {
        "@type": "InteractionCounter",
        "interactionType": "https://schema.org/ViewAction",
        "userInteractionCount": 2834
      },
      {
        "@type": "InteractionCounter",
        "interactionType": "https://schema.org/LikeAction",
        "userInteractionCount": 45
      },
      {
        "@type": "InteractionCounter",
        "interactionType": "https://schema.org/CommentAction",
        "userInteractionCount": 12
      }
    ],
    "acceptedAnswer": {
      "@type": "Answer",
      "@id": "https://forum.com/t/how-to-optimize-postgresql/123/5#answer",
      "url": "https://forum.com/t/how-to-optimize-postgresql/123/5",
      "text": "Create a composite index on your WHERE columns: CREATE INDEX idx_table_cols ON your_table (col1, col2); This should bring your query time down to ~50ms.",
      "dateCreated": "2025-01-15T11:15:00Z",
      "upvoteCount": 89,
      "acceptedAnswerStatus": "Accepted",
      "author": {
        "@type": "Person",
        "name": "Maria DB Expert",
        "url": "https://forum.com/u/maria-db"
      }
    },
    "suggestedAnswer": [
      {
        "@type": "Answer",
        "@id": "https://forum.com/t/how-to-optimize-postgresql/123/2#answer",
        "url": "https://forum.com/t/how-to-optimize-postgresql/123/2",
        "text": "Have you checked if you have indexes on those columns?",
        "dateCreated": "2025-01-15T10:45:00Z",
        "upvoteCount": 12,
        "author": {
          "@type": "Person",
          "name": "Bob Backend",
          "url": "https://forum.com/u/bob-backend"
        }
      }
    ]
  }
}
```

--------------------------------

### Example RSpec Unit Test Structure

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Illustrates the basic structure for writing RSpec unit tests for the Open Graph builder. Ensure all necessary helpers and factories are required.

```ruby
# spec/lib/builders/open_graph_builder_spec.rb
require 'rails_helper'

describe DiscourseRichMicrodata::Builders::OpenGraphBuilder do
  let(:topic) { Fabricate(:topic) }
  let(:data) { DiscourseRichMicrodata::DataExtractor.extract_topic_data(topic) }
  let(:builder) { described_class.new(data, {}) }

  describe '#build' do
    it 'generates valid Open Graph tags' do
      result = builder.build
      expect(result).to include('og:title')
      expect(result).to include('og:url')
    end
  end
end
```

--------------------------------

### Example Bug Report for Discourse Plugin

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Provides a template for reporting bugs, including environment details, steps to reproduce, expected vs. actual behavior, and error logs.

```markdown
### Bug: Open Graph image not displaying

**Environment:**
- Plugin version: 2.0.0
- Discourse version: 3.1.0
- Ruby version: 3.2.1

**Steps to reproduce:**
1. Create topic with image
2. Check OG meta tags
3. Image URL is missing

**Expected:**
`<meta property="og:image" content="https://forum.com/uploads/image.jpg">`

**Actual:**
`<meta property="og:image" content="">`

**Error log:**
```
[RichMicrodata] ERROR: DataExtractor failed to extract image
```
```

--------------------------------

### Discourse Tagging Integration

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Example showing how Discourse tags are converted into Schema.org Thing entities within the generated schema.

```ruby
topic = Topic.find(123)
topic.tags.pluck(:name)  # => ["postgresql", "performance", "sql"]

# Generated schema includes:
{
  "about": [
    {
      "@type": "Thing",
      "@id": "https://forum.com/tag/postgresql",
      "name": "postgresql"
    }
  ]
}
```

--------------------------------

### JSON-LD QAPage Schema for Topics

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Example of a JSON-LD schema for a Question and Answer page, typically generated for topics that are structured as questions. This helps search engines understand the content's Q&A format.

```json
{
  "@context": "https://schema.org",
  "@type": "QAPage",
  "name": "How to optimize PostgreSQL queries?",
  "mainEntity": {
    "@type": "Question",
    "name": "How to optimize PostgreSQL queries?",
    "text": "Queries running 3.5 seconds...",
    "answerCount": 12,
    "acceptedAnswer": {
      "@type": "Answer",
      "text": "Use composite indexes...",
      "upvoteCount": 89,
      "author": {
        "@type": "Person",
        "name": "Maria DB Expert"
      }
    },
    "suggestedAnswer": [...]
```

--------------------------------

### Pull Request Template Example

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

A markdown template for pull request descriptions, including sections for changes, testing, validation, screenshots, and related issues. Useful for standardizing PR submissions.

```markdown
## Description
Brief description of changes

## Type of Change
- [ ] Bug fix
- [ ] New feature
- [ ] Translation
- [ ] Documentation
- [ ] Performance improvement

## Testing
How did you test this?

## Validation
- [ ] Google Rich Results: ✅ / ❌
- [ ] Schema.org Validator: ✅ / ❌
- [ ] Facebook Debugger: ✅ / ❌

## Screenshots (if applicable)

## Related Issues
Closes #123
```

--------------------------------

### Open Graph Meta Tags for Topics

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Example of Open Graph meta tags generated for a topic. These tags provide information about the topic to social media platforms for rich previews.

```html
<meta property="og:type" content="article">
<meta property="og:title" content="How to optimize PostgreSQL queries?">
<meta property="og:url" content="https://forum.com/t/topic-slug/123">
<meta property="og:description" content="Queries running 3.5 seconds...">
<meta property="og:image" content="https://forum.com/uploads/postgres.jpg">
<meta property="article:author" content="https://forum.com/u/john">
```

--------------------------------

### Custom User Fields for Social Links

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Example of adding custom user fields for social links (e.g., GitHub) and modifying the data extractor to include them in the ProfilePage schema.

```ruby
# Add custom user field for GitHub username
user = User.find_by(username: 'john-dev')
user.custom_fields['github_username'] = 'johndev'
user.save!

# Modify lib/discourse_rich_microdata/data_extractor.rb:
def extract_user_data(user)
  # ... existing code ...
  data[:social_links] = []
  data[:social_links] << "https://github.com/#{user.custom_fields['github_username']}" if user.custom_fields['github_username']
  data
end

# Generated ProfilePage includes:
{
  "sameAs": [
    "https://github.com/johndev"
  ]
}
```

--------------------------------

### Get Cache Statistics

Source: https://context7.com/kaktaknet/discourse-rich-json-ld-microdata/llms.txt

Retrieves statistics about the current cache usage, including counts for topics, categories, and users.

```ruby
stats = MetaGeneratorService.cache_stats
```

--------------------------------

### Extract Topic Data for Image URL

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Extracts topic data to check the image URL. Ensure the URL is absolute and starts with 'https://'.

```ruby
data = DiscourseRichMicrodata::DataExtractor.extract_topic_data(topic)
data[:image_url]
# => Should start with https://
```

--------------------------------

### BreadcrumbList Schema Example

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Use this schema to represent the breadcrumb navigation of a website. It lists the hierarchy of pages leading to the current page. Ensure the 'position' property is correctly ordered.

```json
{
  "@context": "https://schema.org",
  "@type": "BreadcrumbList",
  "@id": "https://forum.com/t/how-to-optimize-postgresql/123#breadcrumb",
  "itemListElement": [
    {
      "@type": "ListItem",
      "position": 1,
      "name": "Home",
      "item": "https://forum.com"
    },
    {
      "@type": "ListItem",
      "position": 2,
      "name": "Database",
      "item": "https://forum.com/c/database/5"
    },
    {
      "@type": "ListItem",
      "position": 3,
      "name": "PostgreSQL",
      "item": "https://forum.com/c/database/postgresql/8"
    },
    {
      "@type": "ListItem",
      "position": 4,
      "name": "How to optimize PostgreSQL queries?",
      "item": "https://forum.com/t/how-to-optimize-postgresql/123"
    }
  ]
}
```

--------------------------------

### Enable Debug Mode

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Enable debug mode for the Rich Microdata plugin to get more detailed logs for troubleshooting. This setting should be turned off in production.

```ruby
SiteSetting.rich_microdata_debug_mode = true
```

--------------------------------

### Generated Open Graph Tags for Topic Pages

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Example of Open Graph meta tags generated by the plugin for a topic page. These tags are used for social media sharing.

```html
<meta property="og:site_name" content="My Forum" data-rich-microdata="og">
<meta property="og:type" content="article" data-rich-microdata="og">
<meta property="og:title" content="How to optimize PostgreSQL queries?" data-rich-microdata="og">
<meta property="og:url" content="https://forum.com/t/how-to-optimize-postgresql/123" data-rich-microdata="og">
<meta property="og:description" content="My queries are running 3.5 seconds, need help..." data-rich-microdata="og">
<meta property="og:image" content="https://forum.com/uploads/postgres-logo.jpg" data-rich-microdata="og">
<meta property="og:image:width" content="1200" data-rich-microdata="og">
<meta property="og:image:height" content="630" data-rich-microdata="og">
<meta property="og:locale" content="en_US" data-rich-microdata="og">
<meta property="article:published_time" content="2025-01-15T10:30:00Z" data-rich-microdata="og">
<meta property="article:modified_time" content="2025-01-16T14:20:00Z" data-rich-microdata="og">
<meta property="article:author" content="https://forum.com/u/john-dev" data-rich-microdata="og">
<meta property="article:section" content="Database" data-rich-microdata="og">
<meta property="article:tag" content="postgresql" data-rich-microdata="og">
<meta property="article:tag" content="performance" data-rich-microdata="og">
<meta property="article:tag" content="sql" data-rich-microdata="og">
```

--------------------------------

### Get Site Default Locale

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Retrieves the default locale set for the entire Discourse site. This is used as a fallback when a user's locale is not specified.

```ruby
SiteSetting.default_locale
# => "en"
```

--------------------------------

### Generated Twitter Card Tags for Topic Pages

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Example of Twitter Card meta tags generated by the plugin for a topic page. These tags are used for Twitter card previews.

```html
<meta name="twitter:card" content="summary_large_image" data-rich-microdata="twitter">
<meta name="twitter:site" content="@yourforum" data-rich-microdata="twitter">
<meta name="twitter:title" content="How to optimize PostgreSQL queries?" data-rich-microdata="twitter">
<meta name="twitter:description" content="My queries are running 3.5 seconds..." data-rich-microdata="twitter">
<meta name="twitter:image" content="https://forum.com/uploads/postgres-logo.jpg" data-rich-microdata="twitter">
<meta name="twitter:creator" content="@yourforum" data-rich-microdata="twitter">
<meta name="twitter:label1" content="Replies" data-rich-microdata="twitter">
<meta name="twitter:data1" content="12" data-rich-microdata="twitter">
<meta name="twitter:label2" content="Author" data-rich-microdata="twitter">
<meta name="twitter:data2" content="John Developer" data-rich-microdata="twitter">
```

--------------------------------

### Initialize and Generate Markup with Coordinator

Source: https://context7.com/kaktaknet/discourse-rich-json-ld-microdata/llms.txt

Initializes the Coordinator with extracted data and options, then generates combined meta tags for Open Graph, Twitter Card, and JSON-LD.

```ruby
data = DiscourseRichMicrodata::DataExtractor.extract_topic_data(topic, topic_view)

options = {
  language_options: {
    language: "en-US",
    language_og: "en_US",
    language_code: "en",
    i18n_locale: :en
  }
}

coordinator = DiscourseRichMicrodata::Coordinator.new(data, options)
result = coordinator.generate
```

--------------------------------

### Get User Effective Locale

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Retrieves the effective locale for a specific user. This is used to determine the language setting for user-specific content.

```ruby
user = User.find_by(username: 'ivan')
user.effective_locale
# => "ru"
```

--------------------------------

### Manual Testing: Caching Performance

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Compares the performance of MetaGeneratorService.generate_for_topic between a cold cache and a warm cache using Benchmark.ms.

```ruby
# First call (cold)
Benchmark.ms { MetaGeneratorService.generate_for_topic(topic) }
# => ~50ms

# Second call (warm)
Benchmark.ms { MetaGeneratorService.generate_for_topic(topic) }
# => ~2ms
```

--------------------------------

### Warm Up Cache for Popular Topics

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Pre-populates the cache for topics that have a high number of views. Includes a small delay to throttle requests.

```ruby
Topic.where("views > ?", 1000).find_each do |topic|
  MetaGeneratorService.generate_for_topic(topic)
  sleep 0.1  # Throttle
end
```

--------------------------------

### Cache Warm-Up Script

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

A Ruby script to pre-warm the microdata cache by generating schema for popular topics and all categories. Run this script on deployment.

```ruby
# script/warm_cache.rb
puts "Warming up microdata cache..."

# Popular topics (views > 1000)
Topic.where("views > ?", 1000).order(views: :desc).limit(100).find_each do |topic|
  MetaGeneratorService.generate_for_topic(topic)
  print "."
end

# All categories
Category.find_each do |category|
  MetaGeneratorService.generate_for_category(category)
  print "."
end

puts "\nCache warmed up!"
```

--------------------------------

### Manual Testing: Generate Markup

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Demonstrates how to generate and inspect meta tags for a topic using the MetaGeneratorService in the Rails console.

```ruby
# Rails console
topic = Topic.find(123)
topic_view = TopicView.new(topic)
controller = TopicsController.new

result = MetaGeneratorService.generate_for_topic(topic, topic_view, controller)

# Check head tags
puts result[:head]

# Check body tags (JSON-LD)
puts result[:body]
```

--------------------------------

### Test QAPage Builder

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Tests the QAPage builder by extracting topic data and building the JSON-LD schema for Q&A pages. Allows specifying language.

```ruby
qa_builder = DiscourseRichMicrodata::Builders::QAPageBuilder.new(data, { language: 'en-US' })
puts JSON.pretty_generate(qa_builder.build)
```

--------------------------------

### Translate Site Settings and Microdata Keys

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Copy and translate keys from an existing locale file like `server.en.yml` to create a new locale file for Spanish (`server.es.yml`). This ensures all plugin strings are localized.

```yaml
# config/locales/server.es.yml
es:
  site_settings:
    rich_microdata_enabled: "Activar plugin Rich Microdata"
    # ... more settings

  discourse_rich_microdata:
    breadcrumb:
      home: "Inicio"

    open_graph:
      category_description: "Discusiones en %{category_name}"
      user_description: "Perfil de usuario %{user_name}"

    twitter_card:
      label_replies: "Respuestas"
      label_author: "Autor"
      # ... more translations
```

--------------------------------

### Profile Performance with Benchmark

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Use Ruby's Benchmark module to measure the performance of code sections. This is useful for identifying bottlenecks in your application, such as the `MetaGeneratorService.generate_for_topic` method.

```ruby
require 'benchmark'

Benchmark.bm do |x|
  x.report("cold:") { MetaGeneratorService.generate_for_topic(topic) }
  x.report("warm:") { MetaGeneratorService.generate_for_topic(topic) }
end
```

--------------------------------

### Git Workflow for Contributions

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Standard Git commands for forking a repository, creating a feature branch, committing changes, and opening a pull request.

```git
git checkout -b feature/AmazingFeature
git commit -m 'Add AmazingFeature'
git push origin feature/AmazingFeature
```

--------------------------------

### Create Git Tag for Release

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Command to create a new annotated Git tag for a specific release version and push it to the remote repository.

```bash
git tag -a v2.1.0 -m "Release 2.1.0"
git push origin v2.1.0
```

--------------------------------

### Benchmark Cache Performance

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Benchmarks the performance difference between cold cache (first call) and warm cache (subsequent calls) for generating topic meta data.

```ruby
require 'benchmark'

topic = Topic.find(123)

# Benchmark cold vs warm cache
Benchmark.bm(20) do |x|
  x.report("Cold (first call):") do
    Rails.cache.clear
    MetaGeneratorService.generate_for_topic(topic)
  end

  x.report("Warm (cached):") do
    MetaGeneratorService.generate_for_topic(topic)
  end

  x.report("Warm (100x):") do
    100.times { MetaGeneratorService.generate_for_topic(topic) }
  end
end
```

--------------------------------

### Tail and Grep Logs

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Use this command to continuously monitor production logs for RichMicrodata entries.

```bash
tail -f log/production.log | grep RichMicrodata
```

--------------------------------

### Run Automated Tests

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Execute the plugin's automated tests using `bundle exec rspec` followed by the path to the plugin's RSpec files. This is crucial for ensuring the plugin functions as expected after changes.

```bash
# Run tests (when available)
bundle exec rspec plugins/discourse-rich-json-ld-microdata
```

--------------------------------

### Fetch and Validate JSON-LD Markup with cURL

Source: https://context7.com/kaktaknet/discourse-rich-json-ld-microdata/llms.txt

Use cURL to fetch a page as Googlebot and extract the JSON-LD script. The output is then piped to `python -m json.tool` for pretty-printing.

```bash
# Fetch page as Googlebot and extract JSON-LD
curl -A "Googlebot" https://your-forum.com/t/topic-slug/123 | \
  grep -oP '(?<=<script type="application/ld+json">).*?(?=</script>)' | \
  python -m json.tool
```

--------------------------------

### Generate Meta Markup for Topic

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Generates Open Graph and JSON-LD schemas for a topic. Requires a Topic object as input.

```ruby
topic = Topic.find(123)
result = MetaGeneratorService.generate_for_topic(topic)

puts result[:head]    # Open Graph + Twitter Cards
puts result[:body]    # JSON-LD schemas
```

--------------------------------

### Manually Generate Schema

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Manually trigger the generation of schema markup for a specific topic using `MetaGeneratorService`. Useful for debugging markup generation issues.

```ruby
topic = Topic.find(123)
result = MetaGeneratorService.generate_for_topic(topic)
puts result
```

--------------------------------

### Ruby Commenting Standards

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Illustrates good and bad practices for commenting Ruby code. Focus on commenting complex logic only and avoiding commented-out code.

```ruby
# Calculate final score using weighted average of likes and views
score = (likes * 0.7) + (views * 0.3) / total_interactions
```

```ruby
# This is the score
score = (likes * 0.7) + (views * 0.3) / total_interactions # calculate score
```

--------------------------------

### Create Locale Files for New Languages

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

To add new languages, create server and client locale files in the config/locales directory.

```yaml
config/locales/
├── server.es.yml     # Spanish backend
├── client.es.yml     # Spanish frontend
```

--------------------------------

### Configure Rich Microdata Plugin Settings

Source: https://context7.com/kaktaknet/discourse-rich-json-ld-microdata/llms.txt

Access and modify plugin settings via SiteSetting. Use these settings to control the behavior and output of the Rich Microdata plugin.

```ruby
# Enable/disable plugin
SiteSetting.rich_microdata_enabled
# => true (default)

# Content type determines Schema.org type
SiteSetting.rich_microdata_content_type
# => "discussion" (options: discussion, qa, article, news, review, recipe, event)
# Maps to: DiscussionForumPosting, QAPage, Article, NewsArticle, Review, Recipe, Event

# Cache TTL in seconds
SiteSetting.rich_microdata_cache_ttl
# => 3600 (default, range: 300-86400)

# Limits for included content
SiteSetting.rich_microdata_max_answers
# => 10 (default, range: 5-50)

SiteSetting.rich_microdata_max_comments
# => 5 (default, range: 0-20, nested comments per answer)

# Include user statistics in Person schema
SiteSetting.rich_microdata_include_user_stats
# => true (default)

# Enable BreadcrumbList schema
SiteSetting.rich_microdata_enable_breadcrumbs
# => true (default)

# Enable WebSite schema with SearchAction
SiteSetting.rich_microdata_enable_website_schema
# => true (default)

# Default Open Graph image when topic has no image
SiteSetting.rich_microdata_og_image_default
# => "" (absolute URL or empty for site logo)

# Alternate locales for og:locale:alternate (comma-separated)
SiteSetting.rich_microdata_og_alternate_locales
# => "" (e.g., "en_US, zh_CN")

# Social media links for Organization schema sameAs
SiteSetting.rich_microdata_social_twitter      # @handle or URL
SiteSetting.rich_microdata_social_facebook     # Page URL
SiteSetting.rich_microdata_social_youtube      # Channel URL
SiteSetting.rich_microdata_social_instagram    # Profile URL
SiteSetting.rich_microdata_social_telegram     # Channel URL
SiteSetting.rich_microdata_social_linkedin     # Company URL
SiteSetting.rich_microdata_social_vk           # Page URL
SiteSetting.rich_microdata_social_dzen         # Channel URL
SiteSetting.rich_microdata_social_tiktok       # Profile URL
SiteSetting.rich_microdata_social_tenchat      # Profile URL

# Repository links
SiteSetting.rich_microdata_repo_github         # Organization URL
SiteSetting.rich_microdata_repo_gitlab         # Organization URL
SiteSetting.rich_microdata_repo_sourcecraft    # Organization URL
SiteSetting.rich_microdata_repo_bitbucket      # Organization URL

# Debug and validation
SiteSetting.rich_microdata_debug_mode
# => false (enables debug logging)

SiteSetting.rich_microdata_validate_output
# => false (validates JSON-LD against Schema.org - development only)
```

--------------------------------

### Generate Meta Tags in Rails Console

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Demonstrates how to use the MetaGeneratorService within the Rails console to generate meta tags for a specific topic.

```ruby
# Rails console
topic = Topic.find(123)
result = MetaGeneratorService.generate_for_topic(topic, nil, nil)
puts result[:head]
puts result[:body]
```

--------------------------------

### Test Open Graph Builder

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Tests the Open Graph builder by extracting topic data and building the Open Graph tags. Allows specifying language.

```ruby
topic = Topic.find(123)
data = DiscourseRichMicrodata::DataExtractor.extract_topic_data(topic)
og_builder = DiscourseRichMicrodata::Builders::OpenGraphBuilder.new(data, { language_og: 'en_US' })
puts og_builder.build
```

--------------------------------

### Extract Meta Tags with cURL

Source: https://context7.com/kaktaknet/discourse-rich-json-ld-microdata/llms.txt

Fetch a page using cURL and filter for meta tags using grep. This command displays the first 30 meta tags found on the page.

```bash
# View all meta tags in page head
curl -s https://your-forum.com/t/topic-slug/123 | \
  grep -E '<meta (property|name)=' | head -30
```

--------------------------------

### Enable Plugin in Admin Panel

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Enable the plugin by setting 'rich_microdata_enabled' to true in the Discourse Admin settings.

```yaml
✅ rich_microdata_enabled: true
```

--------------------------------

### Check Generated Markup with Googlebot

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Simulate a request as Googlebot using `curl` to inspect the generated markup, specifically looking for `application/ld+json` tags. This helps verify that structured data is being correctly outputted for search engines.

```bash
# As Googlebot
curl -A "Googlebot" https://your-forum.com/t/topic-slug/123 | grep "application/ld+json"
```

--------------------------------

### Generate Topic Metadata with MetaGeneratorService

Source: https://context7.com/kaktaknet/discourse-rich-json-ld-microdata/llms.txt

Generates comprehensive meta tag markup for a Discourse topic, including Open Graph, Twitter Cards, and JSON-LD schemas. Results are cached. Ensure language options are correctly extracted from the controller context.

```ruby
# Generate metadata for a Discourse topic
topic = Topic.find(123)
topic_view = TopicView.new(topic.id, current_user)

# Language options extracted from controller context
language_options = {
  language: "en-US",
  language_og: "en_US",
  language_code: "en",
  i18n_locale: :en
}

result = MetaGeneratorService.generate_for_topic(topic, topic_view, language_options)
# => { head: "<meta property=\"og:locale\" content=\"en_US\">...", body: "" }

# Insert into HTML <head>
result[:head].html_safe
# Output includes:
# - LLM indexing meta tags (llms-txt, llms-full-txt, llms-sitemaps-txt)
# - Open Graph tags (og:locale, og:image:width/height, article:modified_time, article:tag)
# - Twitter Card tags (twitter:card, twitter:label1/data1, twitter:label2/data2)
# - JSON-LD QAPage/DiscussionForumPosting schema with Question, Answers, Comments
# - BreadcrumbList schema
# - WebSite schema with SearchAction
```

--------------------------------

### Generate User Profile Metadata with MetaGeneratorService

Source: https://context7.com/kaktaknet/discourse-rich-json-ld-microdata/llms.txt

Generates a ProfilePage schema with a Person entity for user profile pages. This includes user statistics, avatar, bio, and activity metrics if enabled. Ensure correct language options are provided.

```ruby
# Generate metadata for a user profile
user = User.find_by(username: "john_doe")

language_options = {
  language: "ru-RU",
  language_og: "ru_RU",
  language_code: "ru",
  i18n_locale: :ru
}

result = MetaGeneratorService.generate_for_user(user, language_options)

# Generated ProfilePage JSON-LD:
# {
#   "@context": "https://schema.org",
#   "@type": "ProfilePage",
#   "@id": "https://forum.example.com/u/john_doe",
#   "name": "Профиль пользователя John Doe",
#   "mainEntity": {
#     "@type": "Person",
#     "name": "John Doe",
#     "identifier": "john_doe",
#     "image": { "@type": "ImageObject", "url": "https://forum.example.com/user_avatar/...", "width": 240, "height": 240 },
#     "interactionStatistic": [
#       { "@type": "InteractionCounter", "interactionType": "WriteAction", "userInteractionCount": 45, "description": "Создано тем" },
#       { "@type": "InteractionCounter", "interactionType": "CommentAction", "userInteractionCount": 312, "description": "Написано ответов" },
#       { "@type": "InteractionCounter", "interactionType": "LikeAction", "userInteractionCount": 892, "description": "Получено лайков" }
#     ]
#   }
# }
```

--------------------------------

### Enable Debug Mode and Extract Topic Data

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Enable debug mode in SiteSettings and extract specific topic data for debugging validation errors. Requires Ruby and access to the Discourse environment.

```ruby
SiteSetting.rich_microdata_debug_mode = true

topic = Topic.find(123)
data = DiscourseRichMicrodata::DataExtractor.extract_topic_data(topic)
puts JSON.pretty_generate(data)
```

--------------------------------

### Manual Testing: Language Detection

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Tests the language detection functionality by mocking a user's locale and verifying that the correct translations are used in the generated meta tags.

```ruby
# Mock user locale
user.update(locale: 'ru')
controller = mock_controller(current_user: user)

result = MetaGeneratorService.generate_for_topic(topic, nil, controller)
# Check if Russian translations are used
```

--------------------------------

### Format Date for Schema.org

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Uses the `iso8601_date` helper to format dates correctly for schema.org markup. Avoid using `to_s` directly as it may not be in the required ISO 8601 format.

```ruby
# Use iso8601_date helper
"dateCreated" => iso8601_date(data[:created_at])
# NOT: data[:created_at].to_s
```

--------------------------------

### Test Language Detection with User Locale

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Tests the language detection mechanism by setting a user's locale and generating meta data. Verifies that translations are used.

```ruby
# Mock user locale
user = User.find_by(username: 'ivan')
user.update(locale: 'ru')
controller.instance_variable_set(:@current_user, user)

# Generate with user's language
result = MetaGeneratorService.generate_for_topic(topic, nil, controller)

# Check if Russian translations are used
puts result[:body]  # Should contain "Главная" instead of "Home"
```

--------------------------------

### Check RichMicrodata Logs

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Command to tail the development log file and filter for lines containing 'RichMicrodata', useful for debugging.

```bash
tail -f log/development.log | grep RichMicrodata
```

--------------------------------

### Testing Translations in Rails Console

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Demonstrates how to test translations directly within the Rails console by setting the locale and using the I18n.t method with and without interpolation.

```ruby
# Rails console
I18n.locale = :fr
I18n.t('discourse_rich_microdata.breadcrumb.home')
# => "Accueil"

I18n.t('discourse_rich_microdata.open_graph.category_description', category_name: 'Tech')
# => "Discussions dans Tech"
```

--------------------------------

### Run RSpec Tests for Plugin

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Executes the RSpec tests for the Discourse Rich JSON-LD Microdata plugin.

```bash
bundle exec rspec plugins/discourse-rich-json-ld-microdata/spec
```

--------------------------------

### Generate Meta Markup for User

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Generates meta markup for a user. Requires a User object as input.

```ruby
user = User.find_by(username: 'john-dev')
result = MetaGeneratorService.generate_for_user(user)
```

--------------------------------

### Configure Twitter Large Image Cards

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Enables large image cards for Twitter by setting the Twitter site handle in admin settings. Verifies the correct card type is generated.

```ruby
builder = DiscourseRichMicrodata::Builders::TwitterCardBuilder.new(data, {})
result = builder.build
result["twitter:card"]  # => "summary_large_image"
```

--------------------------------

### Check Image Accessibility with Curl

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Verifies if an image URL is accessible by making an HTTP HEAD request. A '200 OK' response indicates the image is available.

```bash
curl -I https://forum.com/uploads/image.jpg
# => Should return 200 OK
```

--------------------------------

### Monitor Cache Hit Rate

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Ruby code to add to `MetaGeneratorService` to monitor and calculate the cache hit rate. Includes methods to increment hits and misses, and a method to retrieve the rate.

```ruby
# Add to lib/discourse_rich_microdata/meta_generator_service.rb

def self.cache_hit_rate
  hits = Rails.cache.read('rich_microdata:cache_hits') || 0
  misses = Rails.cache.read('rich_microdata:cache_misses') || 0
  total = hits + misses

  return 0 if total == 0
  (hits.to_f / total * 100).round(2)
end

def self.increment_cache_hit
  Rails.cache.increment('rich_microdata:cache_hits', 1, initial: 0)
end

def self.increment_cache_miss
  Rails.cache.increment('rich_microdata:cache_misses', 1, initial: 0)
end
```

--------------------------------

### Generate Category Metadata with MetaGeneratorService

Source: https://context7.com/kaktaknet/discourse-rich-json-ld-microdata/llms.txt

Generates CollectionPage schema and associated meta tags for category listing pages. This includes subcategory information and topic/post counts. Ensure language options are correctly extracted.

```ruby
# Generate metadata for a Discourse category
category = Category.find(5)

language_options = DiscourseRichMicrodata::LanguageHelper.extract_language_options(controller)

result = MetaGeneratorService.generate_for_category(category, language_options)
# => { head: "<meta property=\"og:locale\" content=\"en_US\">...", body: "" }

# The generated JSON-LD includes:
# {
#   "@context": "https://schema.org",
#   "@type": "CollectionPage",
#   "@id": "https://forum.example.com/c/support/5",
#   "name": "Support",
#   "description": "Get help with technical issues",
#   "hasPart": [
#     { "@type": "CollectionPage", "name": "FAQ", "numberOfItems": 42 },
#     { "@type": "CollectionPage", "name": "Tutorials", "numberOfItems": 28 }
#   ],
#   "interactionStatistic": [
#     { "@type": "InteractionCounter", "interactionType": "WriteAction", "userInteractionCount": 1500 }
#   ]
# }
```

--------------------------------

### Compact Hashes Before Returning

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Ensure that hashes returned from methods do not contain nil values. Use a utility function like `compact_hash` to clean up the hash before returning it.

```ruby
compact_hash(hash)
```

--------------------------------

### Generate Meta Markup for Category

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Generates meta markup for a category. Requires a Category object as input.

```ruby
category = Category.find(5)
result = MetaGeneratorService.generate_for_category(category)
```

--------------------------------

### Reduce Memory Usage Settings

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Configuration settings to reduce memory usage on large forums, including limiting answer extraction, disabling user stats, and using a shorter cache TTL.

```yaml
rich_microdata_max_answers: 5
rich_microdata_max_comments: 3
```

```yaml
rich_microdata_include_user_stats: false
```

```yaml
rich_microdata_cache_ttl: 1800  # 30 minutes
```

--------------------------------

### Troubleshoot Markup Not Appearing

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

If markup is not appearing, first check if the `rich_microdata_enabled` site setting is `true` in the Rails console. If it is enabled, try clearing the cache using `MetaGeneratorService.clear_all_cache`.

```ruby
# Check if enabled
SiteSetting.rich_microdata_enabled
# => true

# Clear cache
MetaGeneratorService.clear_all_cache
```

--------------------------------

### Generate Monthly Microdata Report

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Generates a monthly report detailing cache statistics for microdata generation, including counts of cached items, hit rate, and total cache size.

```ruby
# Monthly report
puts "Microdata Generation Report"
puts "==========================="
puts "Topics cached: #{MetaGeneratorService.cache_stats[:topics]}"
puts "Categories cached: #{MetaGeneratorService.cache_stats[:categories]}"
puts "Users cached: #{MetaGeneratorService.cache_stats[:users]}"
puts "Cache hit rate: #{MetaGeneratorService.cache_hit_rate}%"
puts "Total cache size: #{MetaGeneratorService.cache_stats[:total_size]}"
```

--------------------------------

### Adjust Answer and Comment Limits

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Configure the maximum number of answers and comments to include in QAPage schema. Adjusting these limits impacts JSON-LD size and recommended values are provided.

```yaml
rich_microdata_max_answers: 20  # Default: 10
rich_microdata_max_comments: 10  # Default: 5
```

--------------------------------

### View Full HTML Head

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/README.md

Retrieve the complete HTML content of the `<head>` section for a given URL using `curl`. This is useful for a comprehensive review of all meta tags and linked resources.

```bash
# View full head
curl https://your-forum.com/t/topic-slug/123 | grep -A 50 "<head>"
```

--------------------------------

### Clone Discourse Rich JSON-LD Microdata Plugin

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Clones the plugin repository into the Discourse plugins directory for local development.

```bash
cd discourse
git clone https://github.com/kaktaknet/discourse-rich-json-ld-microdata.git plugins/discourse-rich-json-ld-microdata
```

--------------------------------

### Define Question Entity for Schema.org

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/USAGE.md

Ensures all required fields for a 'Question' schema type are present. This is crucial for accurate representation in search results.

```ruby
# Edit lib/discourse_rich_microdata/builders/qa_page_builder.rb
# Ensure all required fields are present
def question_entity
  {
    "@type" => "Question",
    "name" => data[:title],  # Required
    "text" => data[:excerpt],  # Required
    "answerCount" => data[:posts_count] - 1  # Required
  }
end
```

--------------------------------

### Update Plugin Version in plugin.rb

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Shows how to update the plugin's version number within the `plugin.rb` file, following Semantic Versioning guidelines.

```ruby
# version: 2.1.0
```

--------------------------------

### Create New Feature Branch

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Creates a new Git branch for developing a feature, following a standard naming convention.

```bash
git checkout -b feature/your-feature-name
```

--------------------------------

### Avoid Database Queries in Builders

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

When building data structures, avoid direct database queries within builder methods. Instead, pass necessary data through a hash to maintain performance and separation of concerns.

```ruby
User.find(author_id)
```

--------------------------------

### Check Ruby Syntax Errors with RuboCop

Source: https://github.com/kaktaknet/discourse-rich-json-ld-microdata/blob/main/CONTRIBUTING.md

Uses RuboCop to check for Ruby syntax errors and style violations within the plugin directory.

```bash
rubocop plugins/discourse-rich-json-ld-microdata
```