Notes Site Starter — Developer Resources

This page documents the developer- and agent-facing surface of Notes Site Starter (nss.qiyang.dev): the endpoints and machine-readable files it publishes, how the Markdown content negotiation works, where the source lives, and how the content pipeline runs.

Machine-readable endpoints

• Developer docsMachine-readable endpoints, the content pipeline, and setup instructions.

• llms.txtMarkdown index of everything on the site, for LLM tooling.

• OpenAPI specificationOpenAPI 3.1 description of this site’s public HTTP endpoints.

• RSS feedRSS 2.0 feed of published articles.

• SitemapXML sitemap of indexable URLs.

• Robots.txtCrawler access rules for the site.

• Source repositoryMIT-licensed source code, issues, and pull requests.

• Deploy on VercelOne-click deployment of the starter.

Markdown content negotiation

Every HTML page on this site also serves itself as Markdown. Send an Accept: text/markdown header, or append .md to any URL. The response is Content-Type: text/markdown; charset=utf-8 and carries Vary: Accept, so caches keep the HTML and Markdown variants separate. Nonexistent paths return a real HTTP 404 with a short Markdown recovery guide.

Source and deployment

• Notes Site Starter on GitHubMIT-licensed source code, issues, and pull requests.

• One-click deploy on VercelClone-and-deploy the starter with no configuration.

• Personalize guideA step-by-step checklist for turning a fresh clone into your own portfolio.

Content pipeline

Posts live as MDX files in app/blog/posts/ and are validated, compiled, and indexed by Content Collections at build time. A bundled script (scripts/sync-notes.mts) converts Apple Notes folders into those MDX files. Every post exports validated frontmatter plus a raw Markdown body, which is also what the site serves as the Markdown variant of each post page.