# Plan: SEO & Schema.org Improvements

## TL;DR
Upgrade research pages from `schema.org/Article` to `ScholarlyArticle` with complete academic metadata, fix the high-impression/low-CTR queries from GSC, and add structured data to Q&A pages. These are purely template/frontend changes with outsized SEO impact.

## Implementation Status (2026-03-08)

- ✅ **Done**: Step 1 implemented in `show.html.twig` — research JSON-LD now uses `ScholarlyArticle` with richer fields (`abstract`, `keywords`, `inLanguage`, `isAccessibleForFree`, `citation`, `publisher`, `author`).
- ✅ **Done**: Step 2 implemented in `show.html.twig` — `BreadcrumbList` schema added.
- ℹ️ **Clarification**: Q&A `QAPage` schema already exists in `templates/community/question_show.html.twig`; Step 3 should focus on validation/refinement, not first-time addition.
- ⏳ **Pending**: Steps 4–8.

---

## Current State

- **Research show page** (`show.html.twig` lines 172-224): Uses `@type: Article` with basic fields (headline, description, datePublished, publisher, author)
- **Missing academic fields**: `abstract`, `citation`, `isAccessibleForFree`, `keywords`, `inLanguage`, `pageStart`/`pageEnd`, `publisher.@type: Organization`
- **Profile pages**: Already have `ProfilePage` + `Person` schema — good
- **Q&A pages**: Have some schema but could be improved with `QAPage` markup
- **Blog pages**: Have basic schema
- **GSC issues**: Several high-impression queries (position 4-10) with low CTR — meta descriptions need improvement

---

## Steps

### Step 1: Upgrade Research Pages to ScholarlyArticle

Update `src/syndex/AcademicBundle/Resources/views/Research/show.html.twig` block `schemaBlock`:

Replace `@type: "Article"` with:
```json
{
  "@context": "https://schema.org",
  "@type": "ScholarlyArticle",
  "headline": "{{ research.title }}",
  "name": "{{ research.title }}",
  "abstract": "{{ research.abstract|slice(0, 500) }}",
  "description": "{{ research.abstract|slice(0, 200) }}",
  "datePublished": "{{ research.publishDate }}",
  "dateModified": "{{ research.updatedAt }}",
  "inLanguage": "{{ research.locale ?? 'ar' }}",
  "keywords": "{{ research.tags|join(', ') }}",
  "isAccessibleForFree": true,
  "author": [{% for author in research.authors %}
    {"@type": "Person", "name": "{{ author }}"}{% if not loop.last %},{% endif %}
  {% endfor %}],
  "publisher": {
    "@type": "Organization",
    "name": "{{ research.publisher ?? 'Shamra Academia' }}",
    "url": "https://shamra-academia.com"
  },
  "mainEntityOfPage": {
    "@type": "WebPage",
    "@id": "{{ url('show_research', {slug: research.slug}) }}"
  },
  "image": "https://shamra-academia.com/img/shamra-og.png",
  "citation": "{{ research.citationText ?? '' }}"
}
```

### Step 2: Add BreadcrumbList Schema

Add breadcrumb structured data to research pages:
```json
{
  "@type": "BreadcrumbList",
  "itemListElement": [
    {"@type": "ListItem", "position": 1, "name": "Home", "item": "https://shamra-academia.com"},
    {"@type": "ListItem", "position": 2, "name": "{{ research.field }}", "item": "https://shamra-academia.com/filter?field={{ research.fieldId }}"},
    {"@type": "ListItem", "position": 3, "name": "{{ research.title|slice(0, 60) }}"}
  ]
}
```

### Step 3: Add QAPage Schema to Questions

`templates/community/question_show.html.twig` already includes `QAPage` markup.

Refine and validate existing schema (instead of adding from scratch):
```json
{
  "@type": "QAPage",
  "mainEntity": {
    "@type": "Question",
    "name": "{{ question.title }}",
    "text": "{{ question.body }}",
    "dateCreated": "{{ question.createdAt }}",
    "answerCount": {{ question.answers|length }},
    "author": {"@type": "Person", "name": "{{ question.user.fullName }}"},
    "acceptedAnswer": { ... },
    "suggestedAnswer": [{ ... }]
  }
}
```
This enables Google's Q&A rich results.

### Step 4: Improve Meta Descriptions for High-Value Pages

In `show.html.twig`, improve the Twig meta description block:

Current: likely just truncated abstract.

Better pattern:
- Arabic: `"{{ research.title }} - رسالة {{ research.degreeType }} في {{ research.field }}. {{ research.abstract|slice(0, 120) }}... تصفح وحمّل مجاناً على شمرا أكاديميا"`
- English: `"{{ research.title }} - Read and download this {{ research.type }} paper. {{ research.abstract|slice(0, 120) }}... Free on Shamra Academia"`

This adds action words ("تصفح وحمّل", "Read and download") and a value prop ("مجاناً", "Free") to improve CTR.

### Step 5: Fix High-Impression, Low-CTR Pages (from GSC)

Specific pages to target:

| Query | Impressions | CTR | Position | Action |
|-------|------------|-----|----------|--------|
| مجلة جامعة حماة | 3,118 | 0.16% | 4.75 | Create dedicated landing page for this journal |
| مجلة جامعة حماه (variant) | 1,036 | 0.58% | 4.86 | Redirect to same page, fix alternate spelling |
| شمرا (brand) | 1,271 | 0.31% | 10.21 | Improve homepage title tag and meta description |
| رسائل ماجستير في القانون الدولي الإنساني pdf | 374 | 4.55% | 8.3 | Create topic page (Plan 04) + improve existing page meta |

For "مجلة جامعة حماة": create a publisher-specific landing page at `/publisher/{slug}` showing all papers from that journal.

### Step 6: Add Sitemap Enhancements

Update `public/sitemap.xml` generation:
- Add `lastmod` dates to all URLs
- Add `priority` values: homepage (1.0), research pages (0.8), topic pages (0.7), Q&A (0.5)
- Add `changefreq`: homepage (daily), research (monthly), topics (weekly)
- Split sitemap if >50K URLs: `sitemap-research.xml`, `sitemap-questions.xml`, `sitemap-topics.xml`

### Step 7: Open Graph & Twitter Cards

Verify/update `base.html.twig` OG tags for research pages:
- `og:type` should be `article` for research pages
- `og:title`, `og:description`, `og:image` — ensure they're populated
- Add `twitter:card` = `summary_large_image`
- Add `article:published_time`, `article:author`, `article:tag`

This improves how shared links appear on social media, relevant when users share papers.

### Step 8: Hreflang Tags

If research pages have both Arabic and English versions:
- Add `<link rel="alternate" hreflang="ar" href="...">` and `hreflang="en"` tags
- This prevents duplicate content issues and targets the right language in search

---

## Verification

1. Run Google Rich Results Test on a research page — verify ScholarlyArticle validates
2. Run Rich Results Test on a Q&A page — verify QAPage validates
3. Submit updated sitemap to Search Console
4. Monitor GSC for changes in rich result impressions after 2-4 weeks
5. Compare CTR for targeted queries before/after meta description improvements (4-week window)

---

## Decisions

- **ScholarlyArticle over Article**: More specific, signals academic content to Google. No downside.
- **No AMP for research pages**: AMP is being deprecated by Google. Focus on Core Web Vitals instead.
- **Progressive implementation**: Schema changes first (immediate), then meta descriptions, then sitemap — each can be deployed independently.