@xingwangzhe/stalux 1.25.0 → 1.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@xingwangzhe/stalux",
-    "version": "1.25.0",
+    "version": "1.25.1",
     "description": "A powerful, modern Astro blog theme — use as template or install as plugin",
     "keywords": [
         "astro",

package/src/index.ts

@@ -147,6 +147,7 @@ function getRoutes(baseDir: URL): RouteEntry[] {
         { pattern: "/atom.xml", entrypoint: resolvePage("./pages/atom.xml.ts") },
         { pattern: "/llms.txt", entrypoint: resolvePage("./pages/llms.txt.ts") },
         { pattern: "/llms-full.txt", entrypoint: resolvePage("./pages/llms-full.txt.ts") },
+        { pattern: "/openapi.json", entrypoint: resolvePage("./pages/openapi.json.ts") },
         {
             pattern: "/api/post.abbrlink.json",
             entrypoint: resolvePage("./pages/api/post.abbrlink.json.ts"),

package/src/pages/about.md.ts

@@ -10,6 +10,9 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const text = await renderAboutMd(site);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/archives.md.ts

@@ -19,6 +19,9 @@ export const GET: APIRoute = async (context) => {
     const { t } = createTranslator(lang);
     const text = await renderArchivesMd(site, exportMd, t);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/categories/[category].md.ts

@@ -29,6 +29,9 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const text = renderTaxonomyPageMd(category, posts, site, "categories", exportMd);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/categories/index.md.ts

@@ -22,6 +22,9 @@ export const GET: APIRoute = async (context) => {
     const map = buildTaxonomyMap(posts, "categories");
     const text = renderTaxonomyListMd(map, site, "categories", t("ai.allCategories"));
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/index.md.ts

@@ -13,6 +13,9 @@ export const GET: APIRoute = async (context) => {
     const { t } = createTranslator(lang);
     const text = await renderIndexMd(config, site, t);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/links.md.ts

@@ -13,6 +13,9 @@ export const GET: APIRoute = async (context) => {
     const { t } = createTranslator(lang);
     const text = renderLinksMd(config, site, t);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/llms-full.txt.ts

@@ -20,6 +20,7 @@ export const GET: APIRoute = async (context) => {
     return new Response(text, {
         headers: {
             "Content-Type": "text/plain; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
         },
     });
 };

package/src/pages/llms.txt.ts

@@ -21,6 +21,7 @@ export const GET: APIRoute = async (context) => {
     return new Response(text, {
         headers: {
             "Content-Type": "text/plain; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
         },
     });
 };

package/src/pages/openapi.json.ts

@@ -0,0 +1,77 @@
+import type { APIRoute } from "astro";
+
+export const prerender = true;
+
+const responseSchema = {
+    type: "array",
+    items: { type: "object", additionalProperties: true },
+};
+
+export const GET: APIRoute = async ({ site }) => {
+    const server = site?.toString().replace(/\/$/, "") || "";
+    const document = {
+        openapi: "3.1.0",
+        info: {
+            title: "Stalux Blog Read API",
+            version: "1.0.0",
+            description:
+                "Read-only machine-readable endpoints for discovering and retrieving published Stalux blog content.",
+        },
+        servers: server ? [{ url: server }] : undefined,
+        paths: {
+            "/api/posts.json": {
+                get: {
+                    operationId: "listPublishedPosts",
+                    summary: "List published posts",
+                    description: "Returns metadata for every published post, newest first.",
+                    responses: {
+                        "200": {
+                            description: "Published post metadata",
+                            content: { "application/json": { schema: responseSchema } },
+                        },
+                    },
+                },
+            },
+            "/api/post.abbrlink.json": {
+                get: {
+                    operationId: "listPostIdentifiers",
+                    summary: "List post identifiers",
+                    description: "Returns the title and stable abbrlink for every published post.",
+                    responses: {
+                        "200": {
+                            description: "Published post identifiers",
+                            content: { "application/json": { schema: responseSchema } },
+                        },
+                    },
+                },
+            },
+            "/posts/{abbrlink}.md": {
+                get: {
+                    operationId: "readPostMarkdown",
+                    summary: "Read one post as Markdown",
+                    description: "Returns the normalized Markdown source for a published post.",
+                    parameters: [
+                        {
+                            name: "abbrlink",
+                            in: "path",
+                            required: true,
+                            description: "Stable post identifier returned by the post index.",
+                            schema: { type: "string" },
+                        },
+                    ],
+                    responses: {
+                        "200": {
+                            description: "Markdown post content",
+                            content: { "text/markdown": { schema: { type: "string" } } },
+                        },
+                        "404": { description: "Post not found" },
+                    },
+                },
+            },
+        },
+    };
+
+    return new Response(JSON.stringify(document, null, 2), {
+        headers: { "Content-Type": "application/json; charset=utf-8" },
+    });
+};

package/src/pages/posts/[post].md.ts

@@ -98,6 +98,7 @@ export const GET: APIRoute = async ({ props }) => {
         status: 200,
         headers: {
             "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
         },
     });
 };

package/src/pages/tags/[tag].md.ts

@@ -29,6 +29,9 @@ export const GET: APIRoute = async (context) => {
     const site = getSite(config, context.site?.toString());
     const text = renderTaxonomyPageMd(tag, posts, site, "tags", exportMd);
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/tags/index.md.ts

@@ -22,6 +22,9 @@ export const GET: APIRoute = async (context) => {
     const map = buildTaxonomyMap(posts, "tags");
     const text = renderTaxonomyListMd(map, site, "tags", t("ai.allTags"));
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/pages/words.md.ts

@@ -9,6 +9,9 @@ export const GET: APIRoute = async () => {
 
     const text = await renderWordsMd();
     return new Response(text, {
-        headers: { "Content-Type": "text/markdown; charset=utf-8" },
+        headers: {
+            "Content-Type": "text/markdown; charset=utf-8",
+            Vary: "Accept, Accept-Encoding",
+        },
     });
 };

package/src/utils/ai-discovery.ts

@@ -468,6 +468,38 @@ export async function renderLlmsTxt(config: ConfigMap, site: string): Promise<st
     lines.push(buildMdLink("llms-full.txt", `${site}/llms-full.txt`, t("ai.llmsFullTxtDesc")));
     lines.push("");
 
+    // Developer resources and agent guidance. Keep these links predictable so an
+    // agent can discover the read API without scraping the HTML application shell.
+    lines.push("## Developer resources");
+    lines.push(
+        buildMdLink(
+            "OpenAPI specification",
+            `${site}/openapi.json`,
+            "Machine-readable description of the read-only blog API.",
+        ),
+    );
+    lines.push(
+        buildMdLink(
+            "Published post index",
+            `${site}/api/posts.json`,
+            "JSON metadata for published posts, including stable abbrlink identifiers.",
+        ),
+    );
+    lines.push(
+        buildMdLink(
+            "Post identifier index",
+            `${site}/api/post.abbrlink.json`,
+            "JSON mapping of published post titles to stable identifiers.",
+        ),
+    );
+    lines.push("");
+
+    lines.push("## When to use this site");
+    lines.push(
+        "Use the read API or Markdown endpoints when you need to search, cite, summarize, or retrieve the author's published technical articles. Start with `/openapi.json` or `/api/posts.json`, then fetch a specific `/posts/{abbrlink}.md` resource. The endpoints are read-only and do not require authentication.",
+    );
+    lines.push("");
+
     // Optional
     lines.push(`## ${t("ai.optional")}`);
     lines.push(buildMdLink(t("ai.rss"), `${site}/rss.xml`));