Frontmatter Standards

This guide defines the standard frontmatter metadata fields to be used across all content types in RallyPoynt OS documentation. Consistent frontmatter helps maintain content quality, improves search functionality, and enables advanced features like content filtering, relationship mapping, and dynamic navigation.

What is Frontmatter?

Frontmatter is metadata at the beginning of Markdown files, enclosed by triple dashes (---). It provides structured data about the content using YAML syntax:

---
title: Example Document
description: This is an example document showing frontmatter usage
---

Required Fields

These fields must be included in all content:

Field	Type	Description	Example
title	String	The title of the document (displayed as the main heading)	"Client Onboarding Process"
description	String	A brief description (used for SEO and preview cards)	"Step-by-step guide for onboarding new real estate clients"

Common Fields

These fields should be included whenever applicable:

Field	Type	Description	Example
sidebar_position	Number	Position in the sidebar (lower numbers appear first)	2
tags	Array	Keywords for categorization and search	["process", "client", "onboarding"]
businessArea	String	Primary business area for the content	"operations"
contentLevel	String	The content type for specialized filtering	"article"
lastUpdated	Date	Date of last content update (YYYY-MM-DD)	"2023-07-15"
slug	String	Custom URL path (overrides default path)	"/custom-url-path"

Specialized Fields

These fields are used for specific content types or features:

Field	Type	Description	Example
id	String	Unique identifier (for cross-referencing)	"client-onboarding"
implementationDifficulty	String	Difficulty level for implementation guides	"medium"
implementationTime	Number	Estimated minutes required for implementation	60
relatedPages	Array	Related content page IDs	["client-management", "intake-form"]
associatedResources	Array	Associated resource IDs	["onboarding-checklist", "client-profile-template"]
technicalLevel	String	Technical complexity for developers	"intermediate"
author	String	Content author	"RallyPoynt Team"
showComments	Boolean	Whether to display comment section	true

Content Type-Specific Fields

Article Pages

---
title: Building Client Relationships
description: Strategies for developing strong, lasting client relationships
sidebar_position: 2
tags: [clients, relationships, communication]
businessArea: sales
contentLevel: article
lastUpdated: 2023-07-20
implementationDifficulty: medium
relatedPages: [client-communication, follow-up-systems]
---

Process Documentation

---
title: Transaction Coordination Process
description: End-to-end process for managing real estate transactions
sidebar_position: 3
tags: [process, transactions, coordination]
businessArea: operations
contentLevel: process
lastUpdated: 2023-07-18
implementationDifficulty: hard
implementationTime: 120
relatedPages: [contract-management, closing-checklist]
associatedResources: [transaction-timeline-template]
---

Component Documentation

---
title: Interactive Checklists
description: Implementation guide for using interactive checklist components
sidebar_position: 4
tags: [components, checklists, interactive]
businessArea: systems
contentLevel: component
technicalLevel: intermediate
lastUpdated: 2023-07-22
---

Resource Pages

---
title: Client Intake Form
description: Standardized form for gathering new client information
sidebar_position: 1
tags: [template, forms, clients]
businessArea: operations
contentLevel: resource
lastUpdated: 2023-07-10
id: client-intake-form
relatedPages: [client-onboarding, crm-setup]
---

Field Values Reference

Business Areas

• operations - Operational systems and frameworks
• sales - Lead generation, conversion, and transaction processes
• systems - Workflow documentation and technology implementation
• training - Onboarding, coaching, and skill development

Content Levels

• article - Standard documentation content
• process - Process documentation and workflows
• component - Component and feature documentation
• resource - Templates, checklists, and downloadable resources
• guide - Step-by-step implementation guides
• reference - Technical reference documentation

Implementation Difficulty

• easy - Can be implemented in under an hour with minimal preparation
• medium - Requires several hours and moderate preparation
• hard - Requires significant planning and implementation time

Technical Levels

• basic - Suitable for all users, no technical knowledge required
• intermediate - Requires some technical knowledge or experience
• advanced - Requires significant technical expertise

Validation Rules

The following validation rules apply to frontmatter:

1. title and description fields are required for all content
2. description should be between 50-160 characters for optimal SEO
3. businessArea must be one of the predefined values
4. contentLevel must be one of the predefined values
5. lastUpdated must be a valid date in YYYY-MM-DD format
6. implementationDifficulty must be "easy", "medium", or "hard" when used
7. tags should contain at least one tag and no more than 10
8. slug must be a valid URL path starting with a slash

Automation Support

Several frontmatter fields can be automatically generated or validated:

• lastUpdated can be auto-populated from git history
• businessArea can be inferred from file location
• id can be generated from the file path
• relatedPages can be suggested based on content similarity
• tags can be suggested based on content analysis

Best Practices

1. Be Concise: Keep frontmatter values brief and to the point
2. Be Consistent: Follow naming conventions for related content and resources
3. Be Complete: Include all relevant metadata fields for the content type
4. Be Accurate: Ensure information like implementation time and difficulty is accurate
5. Be Specific: Choose specific tags rather than generic ones
6. Be Structured: Follow the YAML syntax precisely (spacing matters)

Migration Strategy

For existing content, apply these standards gradually:

1. Add required fields to all content
2. Add common fields to high-traffic content
3. Add specialized fields based on content type
4. Validate and refine all frontmatter fields

Implementation Roadmap

1. Update documentation templates with standard frontmatter
2. Create validation scripts to enforce standards
3. Implement automated metadata generation
4. Develop relationship management system
5. Create metadata extraction system