Nubian Geographic – Content Views

"Future Heritage" — التراث في المستقبل

A presentation layer for the Nubian Geographic editorial platform: a magazine-grade articles archive and an immersive single-article reading experience for WordPress.

🌍 ملاحظة بالعربية — هذه الإضافة تقدّم طبقة عرض فقط (أرشيف المقالات

• المقالة المفردة) للمنصة النوبية الجغرافية، وتدعم العربية والإنجليزية بالكامل (RTL/LTR). هذا الملف بالإنجليزية لأنه المعيار على GitHub، لكن واجهات الإضافة نفسها مترجمة بالكامل وتشمل ملفات ترجمة عربية جاهزة.

📑 Table of Contents

• ✨ Features
• 📋 Requirements
• 📥 Installation
• 🎨 Design Philosophy
• 🌍 Bilingual Support
• 🌓 Dark Mode Compatibility
• 🔧 Configuration
• 📂 File Structure
• 📸 Screenshots
• 💡 Usage Examples
• 🤝 Contributing
• 📄 License
• 👥 Credits
• 📞 Support

✨ Features

• ✅ Articles archive — a navy masthead with the page's own title and description, a live article count, category navigation, a featured story (page 1 only), an editorially varied discovery grid, and native crawlable pagination.
• ✅ Single article view — documentary image plate with its real caption, comfortable reading measure, structured article details (language + length), topics, previous/next navigation, related articles, and native comments.
• ✅ Optional sticky table of contents — appears only when the article column is wide enough (CSS container query), with a JS scroll-spy that marks the active heading.
• ✅ Bilingual out of the box — English (LTR) and Arabic (RTL) with logical-property layout; one component set serves both directions.
• ✅ Dark mode compatibility — adapts to the theme's dark-mode toggle for both the archive and the single article.
• ✅ SEO-safe — outputs zero SEO meta or structured data; Rank Math (or Yoast) remains the single SEO authority. Exactly one breadcrumb, one <h1>.
• ✅ Polylang-aware (read-only) — reads existing language relationships; never writes translations or language records.
• ✅ Accessible — WCAG AA contrast targets, visible focus rings, labelled sections, screen-reader helpers, reduced-motion support.
• ✅ Self-hosted typography — Inter (EN) + Cairo (AR) downloaded once via the theme's webfont loader; no third-party request at page view when self-hosting is available.
• ✅ Presentation only — creates or modifies no content, URLs, taxonomies, meta, or database rows. Deactivating restores the theme instantly.

📋 Requirements

Important — the plugin never writes to the database. There are no settings pages, no cron jobs, no REST routes, and uninstall performs no destructive operation.

📥 Installation

1. Download the latest ZIP (for example nubian-geographic-content-views-1.1.1.zip).
2. In WordPress go to Plugins → Add New → Upload Plugin, upload the ZIP, then Activate.
   • Or copy the nubian-geographic-content-views/ folder to /wp-content/plugins/ manually.
3. In Pages → Edit, assign the page template "NGCV — Articles Archive" to your Articles page (English) and to its Polylang Arabic translation.
4. Done — single articles (post post type) automatically use the plugin's article view. No configuration is required.
5. Purge your page cache (for example LiteSpeed) once after deploying.

Note — the archive page keeps its ID, slug, URL, and existing content. Only the presentation changes.

🎨 Design Philosophy

The views follow the "Future Heritage" art direction: archival precision with modern readability — gold accents on deep navy, sharp 2–4 px radii, and a recurring broken-gold "rule" motif. Nothing is invented: every title, date, category, and count shown already exists in WordPress for the current language.

Brand palette

Typography

Arabic pages switch the whole plugin surface to Cairo via one CSS rule keyed on html[lang^="ar"] / html[dir="rtl"]; uppercase and letter-spacing (Latin conventions that break Arabic joining) are disabled for Arabic.

🌍 Bilingual Support

• Full RTL/LTR — all layout uses CSS logical properties (inline-size, margin-inline-start, …), so one component set mirrors automatically. Arrows flip; uppercase/tracking off in RTL.
• Arabic UI strings ship in languages/nubian-geographic-content-views-ar.mo.
• Polylang integration (read-only) —
  • language-scoped archive queries (lang parameter),
  • a header language counterpart link on articles,
  • a compact language switcher that only links to translations that actually exist (suppressed when fewer than two languages).

Note — <html lang>/dir stay owned by WordPress + Polylang. The plugin hard-codes no language or direction.

🌓 Dark Mode Compatibility

The Digital Newspaper theme toggles dark mode via a body.digital_newspaper_dark_mode class (persisted in localStorage.themeMode). This plugin respects it:

• Scoped token overrides for surfaces, hairlines, text, and accents. Light-mode appearance is unchanged — every dark rule requires the body class.
• Archive: cards, featured panel, category nav, pagination, and a softened navy masthead (#0A1F44) with the gold rule preserved.
• Single article: prose, headings, TOC, blockquotes, tables, code, article details, topics, previous/next, related, comments — all re-tuned for WCAG AA contrast on dark surfaces.
• Components that used navy as text flip to the dark ink; the brand tokens (--ngcv-navy, --ngcv-gold, --ngcv-blue) are never redefined.

🔧 Configuration

The plugin ships with sensible defaults and is fully filterable.

// Example: disable the featured story on the archive.
add_filter( 'ngcv_show_featured_story', '__return_false' );

// Example: enable the posts-page fallback for a verified page ID.
add_filter(
    'ngcv_articles_page_ids',
    function ( $ids ) {
        $ids[] = 42; // The real "Articles" page ID.
        return $ids;
    }
);

📂 File Structure

nubian-geographic-content-views/
├── nubian-geographic-content-views.php  # Bootstrap + loader
├── uninstall.php                        # No-op uninstall
├── readme.txt                           # WordPress.org readme
├── includes/
│   ├── class-plugin.php                 # Context, body classes, shell
│   ├── class-template-router.php        # Template routing
│   ├── class-archive.php                # Archive data layer
│   ├── class-single.php                 # Single-article data layer
│   ├── class-assets.php                 # CSS/JS, image sizes, fonts
│   └── class-polylang.php               # Read-only Polylang adapter
├── templates/
│   ├── archive-articles.php             # Archive view
│   ├── single-article.php               # Single-article view
│   └── parts/                           # Card, featured, TOC, …
├── assets/
│   ├── css/  (tokens, archive, single, responsive)
│   └── js/   (content-views.js — TOC + scroll-spy)
└── languages/                           # pot + ar .po/.mo

📸 Screenshots

Note — screenshots will be added here as the visual documentation matures. Planned captures:

💡 Usage Examples

Assign the archive presentation

Pages → Edit → Page Attributes → Template → "NGCV — Articles Archive" on both language versions of the Articles page.

Override a template from a child theme

Copy any plugin template into your child theme and edit freely:

your-child-theme/
└── ngcv-templates/
    ├── archive-articles.php
    ├── single-article.php
    └── parts/article-card.php

Responsive image sizes

ngcv-card       768 × 480   landscape card (8:5)
ngcv-card-tall  720 × 900   portrait card  (4:5)
ngcv-hero      1600 × 900   documentary plate (16:9)

Regenerate thumbnails once after deployment so older media gains the new crops (the browser falls back gracefully until then).

🤝 Contributing

Contributions are welcome.

1. Open an issue describing the change first.
2. Keep the project's guardrails in mind: presentation only, no content/query/SEO changes, WordPress APIs, escaped output.
3. Preserve bilingual behaviour (test both EN and AR).

📄 License

Released under the GPL-2.0-or-later license — the same license as WordPress itself.

👥 Credits

• Nubian Geographic — project owner and editorial direction.
• Digital Newspaper theme by BlazeThemes — the host theme whose shell and dark-mode system this plugin integrates with.
• Polylang — translation relationships (consumed read-only).
• Rank Math — SEO ownership (the plugin outputs none).
• Inter by Rasmus Andersson and Cairo by Mohamed Gaber — the brand typefaces.

📞 Support

• 🐛 Bug reports: open a GitHub issue with steps to reproduce, WordPress/PHP versions, and theme version.
• 💡 Feature ideas: the plugin is deliberately presentation-only; proposals that respect that boundary are preferred.
• 🌐 Arabic support: available — write your issue in Arabic or English.

🔖 Topics

wordpress-plugin · nubian · cultural-heritage · documentation · bilingual · rtl · multilingual · dark-mode · accessibility · editorial · magazine · polylang · rank-math