openapi: 3.1.0
info:
  title: Notes Site Starter site API
  version: "1.0.0"
  summary: Machine-readable HTTP surface of nss.qiyang.dev
  description: >
    Notes Site Starter (https://nss.qiyang.dev) is a personal site with a homepage (about, projects, experience), an MDX blog,
    and Apple Notes sync, built with the Next.js App Router. This OpenAPI description documents
    the public HTTP endpoints that pages, tools, and AI agents can rely on,
    including the Markdown content negotiation every HTML page supports.
  license:
    name: MIT
    url: https://github.com/qiyangdev/notes-site-starter
servers:
  - url: https://nss.qiyang.dev
paths:
  /:
    get:
      summary: Homepage — HTML by default, Markdown via content negotiation
      responses:
        "200":
          description: Homepage content
          content:
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
  /blog:
    get:
      summary: Index of published blog posts
      responses:
        "200":
          description: Blog index
          content:
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
  /blog/{slug}:
    get:
      summary: A single blog post
      parameters:
        - name: slug
          in: path
          required: true
          schema:
            type: string
      responses:
        "200":
          description: Blog post content
          content:
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
        "404":
          description: No post exists for this slug
  /docs:
    get:
      summary: Developer resources index
      responses:
        "200":
          description: Documentation page
          content:
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
  /llms.txt:
    get:
      summary: Markdown index of the site, following the llms.txt convention
      responses:
        "200":
          description: Plain-text Markdown index
          content:
            text/plain:
              schema:
                type: string
  /rss:
    get:
      summary: RSS 2.0 feed of published articles
      responses:
        "200":
          description: RSS XML document
          content:
            application/rss+xml:
              schema:
                type: string
  /sitemap.xml:
    get:
      summary: XML sitemap of indexable URLs
      responses:
        "200":
          description: Sitemap XML document
          content:
            application/xml:
              schema:
                type: string
  /robots.txt:
    get:
      summary: Crawler access rules
      responses:
        "200":
          description: Plain-text robots file
          content:
            text/plain:
              schema:
                type: string
  /md/{path}:
    get:
      summary: Markdown variant of any page (also reachable via Accept: text/markdown or a .md suffix)
      parameters:
        - name: path
          in: path
          required: true
          schema:
            type: string
            description: Original page path, e.g. blog/my-post
      responses:
        "200":
          description: Markdown rendering of the page
          content:
            text/markdown:
              schema:
                type: string
        "404":
          description: No page or post exists for this path — body is a short Markdown recovery guide
