Skip to content

Canonical Article Structure (ISR-First, BFF-Ready)

This standard applies to articles currently used by ISR app-suite collections first, then to all remaining articles.

1) Required Metadata

Use frontmatter with this minimum contract:

---
articleKey: ART-SHOP-0000
slug: example-article-slug
title: Primary Title in Title Case
subtitle: One-sentence value statement for the target audience
publishedAt: "YYYY-MM-DD"
author:
  name: OVES Editorial
  role: Off-Grid Systems
category: off-grid
tone: technical-commercial
heroImage:
  url: https://res.cloudinary.com/oves/image/upload/v1/path/to/image.jpg
  alt: Specific descriptive alt text
categories:
  - category:technology-and-innovation
tags:
  - hybrid-inverter
  - lifecycle-cost
editorial:
  status: cleaned
  cleanedAt: "YYYY-MM-DD"
  workflowNote: metadata-structure-references-normalized
  trailRef: editorial-cleanup-tracker
---

2) Title and Subtitle Standardization

  • title: one core claim, concise, no filler words.
  • subtitle: one practical outcome for customer/operator.
  • Avoid duplicate meaning between title and subtitle.
  • No all-caps words except established acronyms (AC, DC, IoT, BMS).

3) Author and Category Rules

  • author.name: must be selected from docs/shared/pseudo-authors.yaml.
  • author.role: must match site/collection context.
  • category: must be exactly one of:
  • Company
  • Technology
  • Products
  • Marketing
  • Services
  • Industry
  • Source of truth: docs/shared/editorial-taxonomy.yaml (categories array).
  • categories[]: optional secondary taxonomy tags from legacy taxonomy.

4) Section Structure Rules

Use heading hierarchy consistently:

  • # exactly once (article headline if needed in body).
  • ## for main sections (3-6 sections target).
  • ### only for sub-sections under a ##.
  • No heading level jumps (# -> ### is invalid).

Recommended body flow:

  1. ## Context (what problem, for whom)
  2. ## Approach (solution framing)
  3. ## Technical Details (how it works, specs, constraints)
  4. ## Deployment Guidance (implementation and operations)
  5. ## Business Impact (cost, reliability, uptime, ROI)
  6. ## References (external and internal sources)

5) Tone Style Vocabulary

Pick one or two tones only:

  • technical
  • commercial
  • promotional
  • educational
  • thought-leadership
  • faq

Recommended mapping:

  • Product explanation: technical-commercial
  • Campaign update: promotional-commercial
  • Knowledge article: technical-educational

6) Reference and Evidence Rules

  • Include ## References in every cleaned article.
  • At least 2 references for technical claims.
  • Prefer primary sources (standards, manufacturer docs, field data, reputable institutional reports).
  • Keep claims measurable where possible (voltage ranges, cycle assumptions, uptime impacts, etc.).

7) Internal Editorial Trail

  • Set editorial.status: cleaned only after checklist completion.
  • Record the cleanup action in docs/shared/editorial-cleanup-tracker.yaml.
  • Trail must include: date, action scope, and short note on what changed.
  • Do not store real editor credentials/identity in article markdown.
  • Authoritative identity-level auditing is handled by BFF and Odoo.

8) Tag Governance

  • tags[] must come from docs/shared/editorial-taxonomy.yaml (tags array of string literals).
  • Reuse existing tags by default.
  • Add a new tag only when it introduces a new dimension or strategic interest.
  • Avoid symbolic duplicates (example: eng, eng.) and semantic duplicates (example: author, writer).
  • Every new tag addition must update the ledger.