Developer Specs

Syntaxis Platform Documentation

Comprehensive guide to writing content, managing frontmatter schemas, PWA features, theme customization, and static site deployment.

1. Platform Overview

Syntaxis is a high-performance technical publication engine built on top of Astro 5, Tailwind CSS v4, and MDX. It delivers static site generation (SSG) with zero JavaScript client-side bloat by default.

Key Architecture Features:

Content Collections Layer: Type-safe MDX content loading with Zod validation.
CSS Variables Theme Engine: Dark/Light mode switching powered by global CSS variables with zero FOUC.
Offline PWA Support: Service Worker caching (/sw.js) and Web App Manifest (/manifest.json).
LocalStorage Bookmark Store: Save articles locally without server authentication.
Web Share API: Native device sharing with clipboard copy fallback.

2. Article Frontmatter Schema Specification

All articles reside inside category subfolders in src/content/blog/ (e.g. src/content/blog/artificial-intelligence/my-article.mdx).

Every .mdx or .md file must include the following YAML frontmatter header:

---
title: "Mastering Distributed Systems in Rust"
description: "A production guide to consensus protocols, Raft implementation, and network RPCs."
category: "Software Engineering"
author: "Senior Systems Architect"
publishedAt: "2026-08-06"
readingTime: "8 min read"
tags: ["rust", "distributed systems", "raft", "backend"]
keywords: ["rust", "systems design", "consensus"]
heroImage: "../../assets/blog-placeholder-1.jpg"
---

Frontmatter Field Specs:

Field	Type	Required	Description
`title`	String	Yes	Main headline of the article
`description`	String	Yes	Short snippet summary for SEO and feed preview cards
`category`	String	Yes	Topic category (e.g. Artificial Intelligence, Web Development, Cloud & DevOps)
`author`	String	Optional	Author name (Defaults to "Senior Writer")
`publishedAt`	Date (YYYY-MM-DD)	Yes	Publication date
`readingTime`	String	Optional	Estimated reading duration (e.g. "6 min read")
`tags`	Array of Strings	Optional	Topic tags array

3. Code Block Copy & Formatting

Code blocks are rendered using standard Markdown triple backticks. Syntax highlighting and instant Copy buttons are applied automatically:

function calculateThroughput(requests: number, seconds: number): number {
  return Math.round(requests / seconds);
}

4. Building & Deployment Instructions

To build the static production bundle for deployment on Vercel, Netlify, Cloudflare Pages, or AWS S3:

# 1. Run type check and build command
npm run build

# 2. Preview production build locally
npm run preview

The generated output will be placed inside the dist/ folder ready for static hosting.