Developer Documentation
These are the developer resources for subramanya.ai, the personal site of
Subramanya N. This section is the human-readable counterpart to the
machine-readable /openapi.json,
/.well-known/api-catalog, and
/llms.txt endpoints. It describes how the site is built,
what data it depends on, how agents can consume it programmatically, and how
to contribute.
Pages
- Architecture - system overview, build flow, rendering model, and where to change things.
- Content Model - front-matter and data contracts for posts, books, data files, and top-level pages.
- Development - local setup, validation commands, content update workflow, and Python maintenance scripts.
- Deploy Checklist - pre-deploy verification: production build, content/link validation, API-vs-spec checks, and post-deploy live checks.
- API Versioning & Deprecation Policy - URL path versioning, additive-only guarantees, 6-month sunset timeline, and how deprecations are announced.
Agent-Readable Endpoints
For automated consumption, the site exposes several machine-readable endpoints.
These are also advertised via RFC 8288 <link> elements on every page and via
an RFC 9727 api-catalog Linkset.
| Endpoint | Purpose | Content Type |
|---|---|---|
/openapi.json | OpenAPI 3.1 spec of the read-only content API | application/json |
/api/v1/site.json | Site metadata + endpoint directory (versioned, typed JSON) | application/json |
/api/v1/posts.json | All blog posts (versioned, typed JSON) | application/json |
/api/v1/books.json | All book notes (versioned, typed JSON) | application/json |
/api/v1/tags.json | All topic tags with archive URLs (versioned, typed JSON) | application/json |
/.well-known/api-catalog | RFC 9727 catalog of all machine-readable endpoints | application/linkset+json |
/llms.txt | Short site summary for LLM ingestion | text/plain |
/llms-full.txt | Full site content for LLM ingestion | text/plain |
/search.json | Search index (posts and books) | application/json |
/feed.xml | Blog RSS 2.0 feed | application/rss+xml |
/sitemap.xml | Sitemaps 0.9 | application/xml |
/sitemapindex.xml | Sitemap index | application/xml |
/robots.txt | Crawler policy with AI content signals | text/plain |
All endpoints are read-only, served over anonymous HTTPS GET - no API key,
no sign-up, no rate-limit registration. Every operation in
/openapi.json has a unique operationId, a description,
and typed response schemas, so it can be loaded directly into LLM
function-calling or tool-use frameworks. Nonexistent paths return a real
HTTP 404 whose body links to /llms.txt, /sitemap.xml, and /search.json
for recovery.
RFC References
- RFC 8288 - Web Linking (the
Linkheader and<link>element). - RFC 9264 - Linkset format (
application/linkset+json). - RFC 9727 - API catalog well-known URI.
- RFC 8615 - Well-known URIs.
Source
The complete source of this site — including the agent configs (AGENTS.md,
plugin.json, skills/) — lives at
github.com/subramanya1997/subramanya1997.github.io.