@xingwangzhe/stalux 1.25.2 → 1.25.4

package/README.md

@@ -126,7 +126,7 @@ stalux({
 stalux/
 ├── config/              # YAML configuration
 │   ├── site.yml         # Site metadata
-│   ├── author.yml       # Author info
+│   ├── author.yml       # Author info (name/avatar/bio/jobTitle)
 │   ├── navs.yml         # Navigation menu
 │   ├── footer.yml       # Footer badges & copyright
 │   ├── links.yml        # Friend links
@@ -212,3 +212,17 @@ MIT License — see [LICENSE](./LICENSE).
 
 [![Deploy with Vercel](https://vercel.com/button)](https://vercel.com/new/clone?repository-url=https://github.com/xingwangzhe/stalux)
 [![Deploy with EdgeOne Pages](https://cdnstatic.tencentcs.com/edgeone/pages/deploy.svg)](https://edgeone.ai/pages/new?repository-url=https://github.com/xingwangzhe/stalux)
+
+### Author JSON-LD configuration
+
+`stalux/config/author.yml` accepts the optional `jobTitle` field. When present, Stalux includes it in the homepage and article JSON-LD `Person` entity so agents can identify the author's role without changing the visual author card:
+
+```yaml title="stalux/config/author.yml"
+id: author
+name: xingwangzhe
+avatar: /avatar.png
+bio: Blog Theme Stalux
+jobTitle: Software Engineer # Optional; emitted as JSON-LD Person.jobTitle
+```
+
+This is a build-time metadata field. It does not create a contact endpoint or expose private information; only publish a role that is already intended to be public.

package/package.json

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

package/src/components/stalux/layout/head.astro

@@ -76,7 +76,7 @@ const contentTitle =
     : effectiveTitle;
 const resolvedNoindex = Boolean(siteConfig.noindex) || isNotFoundPage || Boolean(props.noindex);
 const resolvedNofollow = Boolean(siteConfig.nofollow) || isNotFoundPage;
-const staluxVersion = "1.25.2";
+const staluxVersion = "1.25.4";
 
 const openGraphConfig: Record<string, unknown> = {
   basic: {
@@ -171,6 +171,7 @@ const authorEntity = {
   url: `${siteUrl}/about/`,
   ...(toAbsolute(authorConfig.avatar) ? { image: toAbsolute(authorConfig.avatar) } : {}),
   ...(sameAs.length ? { sameAs } : {}),
+  ...(authorConfig.jobTitle ? { jobTitle: authorConfig.jobTitle } : {}),
 };
 const publisher = {
   "@type": "Organization",

package/src/pages/404.astro

@@ -21,6 +21,11 @@ const { t } = createTranslator(siteConfig.lang || "zh-CN");
     <div class="error-content">
       <h1>404</h1>
       <p>{t("page404.pageNotFound")}</p>
+      <p class="agent-recovery">
+        This URL does not exist. Continue at the <a href="/">home page</a>, browse the
+        <a href="/archives/">archive</a>, read <a href="/llms.txt">llms.txt</a>, or inspect the
+        <a href="/sitemap-index.xml">sitemap</a> to find published content.
+      </p>
       <p id="countdown" class="countdown-text" data-countdown-template={t("page404.countdown", { n: "{n}" })}>{t("page404.countdown", { n: 5 })}</p>
       <a href="/" class="home-btn" data-astro-prefetch>{t("page404.backHome")}</a>
     </div>
@@ -59,6 +64,18 @@ const { t } = createTranslator(siteConfig.lang || "zh-CN");
     margin: -0.5rem 0 1.5rem 0 !important;
   }
 
+  .agent-recovery {
+    max-width: 42rem;
+    margin: 0 auto 1.5rem !important;
+    font-size: 1rem !important;
+    line-height: 1.7;
+  }
+
+  .agent-recovery a {
+    color: inherit;
+    text-decoration: underline;
+  }
+
   .home-btn {
     display: inline-block;
     padding: var(--space-md) var(--space-lg);

package/src/pages/api/post.abbrlink.json.ts

@@ -15,6 +15,10 @@ export const GET: APIRoute = async () => {
         status: 200,
         headers: {
             "Content-Type": "application/json; charset=utf-8",
+            "Cache-Control": "public, max-age=0, must-revalidate",
+            "RateLimit-Limit": "60",
+            "RateLimit-Remaining": "59",
+            "RateLimit-Reset": "60",
         },
     });
 };

package/src/pages/api/posts.json.ts

@@ -28,6 +28,10 @@ export const GET: APIRoute = async () => {
         status: 200,
         headers: {
             "Content-Type": "application/json; charset=utf-8",
+            "Cache-Control": "public, max-age=0, must-revalidate",
+            "RateLimit-Limit": "60",
+            "RateLimit-Remaining": "59",
+            "RateLimit-Reset": "60",
         },
     });
 };

package/src/pages/index.astro

@@ -24,6 +24,18 @@ import { getSiteData, getAuthorData, getHeadData, getNavsData, getLinksData, get
     </div>
     <h1 class={styles.homeTitle}>{siteTitle}</h1>
     <h2 class="sr-only" style="position:absolute;width:1px;height:1px;padding:0;margin:-1px;overflow:hidden;clip:rect(0,0,0,0);white-space:nowrap;border:0;">{t("ai.about")}</h2>
+    <section class="agent-home-summary" aria-label="About this site">
+      <h2>About this technical blog</h2>
+      <p>
+        {siteDescription} This is a personal, public, read-only knowledge base for developers and
+        AI agents looking for published technical articles, practical notes, project investigations,
+        and reproducible web engineering details. Start with the <a href="/index.md">Markdown home
+        page</a>, <a href="/api/posts.json">published post index</a>, <a href="/openapi.json">read API
+        description</a>, or <a href="/llms.txt">agent guidance</a>. Individual posts are available as
+        HTML and Markdown, and the <a href="/rss.xml">RSS feed</a> provides a machine-readable update
+        stream. The site does not require an account and these discovery endpoints do not mutate data.
+      </p>
+    </section>
     <Author />
     <TextType />
     <DateTime />
@@ -31,3 +43,27 @@ import { getSiteData, getAuthorData, getHeadData, getNavsData, getLinksData, get
     <ToArchive />
   </div>
 </Stalux>
+
+<style>
+  .agent-home-summary {
+    max-width: 52rem;
+    margin: 1rem auto 0;
+    padding: 0 1rem;
+    text-align: left;
+  }
+
+  .agent-home-summary h2 {
+    font-size: 1.25rem;
+    margin: 0 0 0.5rem;
+  }
+
+  .agent-home-summary p {
+    line-height: 1.7;
+    margin: 0;
+  }
+
+  .agent-home-summary a {
+    color: inherit;
+    text-decoration: underline;
+  }
+</style>

package/src/pages/openapi.json.ts

@@ -7,6 +7,40 @@ const responseSchema = {
     items: { type: "object", additionalProperties: true },
 };
 
+const problemSchema = {
+    type: "object",
+    required: ["type", "title", "status", "code", "detail"],
+    properties: {
+        type: { type: "string", format: "uri", description: "Stable problem type URI." },
+        title: { type: "string" },
+        status: { type: "integer", minimum: 400, maximum: 599 },
+        code: { type: "string", description: "Machine-readable error code." },
+        detail: { type: "string" },
+        resolution: { type: "string" },
+    },
+};
+
+const rateLimitHeaders = {
+    "RateLimit-Limit": {
+        description: "Maximum requests in the advertised window.",
+        schema: { type: "integer" },
+    },
+    "RateLimit-Remaining": {
+        description: "Remaining requests in the advertised window.",
+        schema: { type: "integer" },
+    },
+    "RateLimit-Reset": {
+        description: "Seconds until the advertised window resets.",
+        schema: { type: "integer" },
+    },
+};
+
+const problemResponse = (description: string, status: number) => ({
+    description,
+    content: { "application/problem+json": { schema: problemSchema } },
+    headers: status === 429 ? { "Retry-After": { schema: { type: "integer" } } } : undefined,
+});
+
 export const GET: APIRoute = async ({ site }) => {
     const server = site?.toString().replace(/\/$/, "") || "";
     const document = {
@@ -15,12 +49,18 @@ export const GET: APIRoute = async ({ site }) => {
             title: "Stalux Blog Read API",
             version: "1.0.0",
             description:
-                "Read-only machine-readable endpoints for discovering and retrieving published Stalux blog content.",
+                "Version 1 read-only machine-readable endpoints for discovering and retrieving published Stalux blog content. The static site does not expose writes, authentication, or a server-side rate-limit enforcement API.",
+        },
+        tags: [{ name: "Posts", description: "Published post discovery and Markdown retrieval." }],
+        externalDocs: {
+            description: "Agent guidance and usage recommendations",
+            url: server ? `${server}/llms.txt` : "/llms.txt",
         },
         servers: server ? [{ url: server }] : undefined,
         paths: {
             "/api/posts.json": {
                 get: {
+                    tags: ["Posts"],
                     operationId: "listPublishedPosts",
                     summary: "List published posts",
                     description: "Returns metadata for every published post, newest first.",
@@ -28,12 +68,16 @@ export const GET: APIRoute = async ({ site }) => {
                         "200": {
                             description: "Published post metadata",
                             content: { "application/json": { schema: responseSchema } },
+                            headers: rateLimitHeaders,
                         },
+                        "400": problemResponse("Invalid request.", 400),
+                        "429": problemResponse("Rate limit exceeded.", 429),
                     },
                 },
             },
             "/api/post.abbrlink.json": {
                 get: {
+                    tags: ["Posts"],
                     operationId: "listPostIdentifiers",
                     summary: "List post identifiers",
                     description: "Returns the title and stable abbrlink for every published post.",
@@ -41,12 +85,16 @@ export const GET: APIRoute = async ({ site }) => {
                         "200": {
                             description: "Published post identifiers",
                             content: { "application/json": { schema: responseSchema } },
+                            headers: rateLimitHeaders,
                         },
+                        "400": problemResponse("Invalid request.", 400),
+                        "429": problemResponse("Rate limit exceeded.", 429),
                     },
                 },
             },
             "/posts/{abbrlink}.md": {
                 get: {
+                    tags: ["Posts"],
                     operationId: "readPostMarkdown",
                     summary: "Read one post as Markdown",
                     description: "Returns the normalized Markdown source for a published post.",
@@ -64,11 +112,20 @@ export const GET: APIRoute = async ({ site }) => {
                             description: "Markdown post content",
                             content: { "text/markdown": { schema: { type: "string" } } },
                         },
-                        "404": { description: "Post not found" },
+                        "404": problemResponse("Post not found.", 404),
+                        "429": problemResponse("Rate limit exceeded.", 429),
                     },
                 },
             },
         },
+        "x-stalux-api-policy": {
+            versioning:
+                "The documented surface is v1. Future breaking APIs use /api/v2/; existing static paths remain compatibility aliases.",
+            deprecation:
+                "Breaking changes are announced in the documentation and a Deprecation/Sunset response header may be added before removal.",
+            rateLimits:
+                "Static exports publish RateLimit-* documentation headers but cannot enforce a dynamic quota or emit Retry-After without a server runtime.",
+        },
     };
 
     return new Response(JSON.stringify(document, null, 2), {

package/src/schemas/config.ts

@@ -30,6 +30,7 @@ export const authorSchema = z.object({
     name: z.string().min(1, "author.name is required"),
     avatar: z.string().min(1, "author.avatar is required"),
     bio: z.string().min(1, "author.bio is required"),
+    jobTitle: z.string().optional(),
 });
 
 export const headSchema = z.object({