diff --git a/.agents/skills/ax-blog-markdown-typesetting/SKILL.md b/.agents/skills/ax-blog-markdown-typesetting/SKILL.md new file mode 100644 index 0000000..904f3b3 --- /dev/null +++ b/.agents/skills/ax-blog-markdown-typesetting/SKILL.md @@ -0,0 +1,91 @@ +--- +name: ax-blog-markdown-typesetting +description: Format, rewrite, sanitize, and normalize Markdown articles for this AX Blog repository. Use when Codex needs to draft a new blog post, convert rough notes into publishable AX Blog Markdown, repair frontmatter, reorganize headings, clean up code/math blocks, remove sensitive paths/IPs/secrets by default, or make an article compatible with this repo's static Markdown pipeline. +--- + +# AX Blog Markdown Typesetting + +## Overview + +Use this skill to produce Markdown that matches the actual AX Blog parser and article layout in this repository. +Base decisions on the repo's supported frontmatter, heading behavior, code fences, math syntax, link rewriting, and raw-HTML restrictions. + +## Workflow + +1. Read the target Markdown draft or article file. +2. Silently remove or generalize sensitive information before publication. +3. Normalize frontmatter to the supported keys only. +4. Restructure the article into a clean `#` title plus `##` and `###` sections. +5. Convert examples, commands, formulas, links, and images into AX Blog-compatible Markdown. +6. Remove dependence on raw HTML. +7. Preserve the author's meaning while tightening structure and readability. + +## Core Rules + +- Use only supported frontmatter fields: + `title`, `date`, `tags`, `collections`, `summary`, `draft`, `featured`, `pinned`. +- Prefer `date` in `YYYY-MM-DD`. +- Keep `summary` to one compact sentence suited for archive cards and search snippets. +- Prefer one body `#` heading that matches the article title. +- Keep the real structure at heading levels 2 and 3. +- Use fenced code blocks with language labels when known. +- Use `$...$` and `$$...$$` for math. +- Use normal Markdown tables, lists, blockquotes, links, and images. +- Do not rely on raw HTML because the renderer escapes it. + +## Privacy Defaults + +- Treat drafts as publishable by default: do not leave private or environment-specific identifiers in the final Markdown. +- Remove or generalize IP addresses, private hostnames, internal Git remotes, usernames, home/NAS/workstation paths, API tokens, passwords, secret keys, emails, phone numbers, and other local identifiers unless the user explicitly asks to keep them. +- Prefer relative paths, environment variables, or neutral placeholders such as `/path/to/project`, `private-git-host`, `user@example.com`, or `TOKEN_VALUE` when a command still needs a usable shape. +- Do not add prose saying that content was hidden, redacted, anonymized, or replaced. Sanitization is an editing step, not article content. +- If removing a value would break a command's meaning, keep the command pattern and replace only the sensitive segment. + +## Rewrite Heuristics + +- Turn messy headings into short, scannable section names. +- Split oversized paragraphs when they hide structure. +- Promote important enumerations into lists. +- Keep examples near the paragraph that explains them. +- Preserve technical precision; do not simplify away important qualifiers. +- If the source uses HTML for callouts or layout, rewrite it into Markdown-native sections or blockquotes. +- If tags or collections are implied but missing, infer conservatively from the content. +- Remove meta-notes about sanitization unless the article is explicitly about data privacy or redaction. + +## Default Article Shape + +Use this shape unless the source material strongly suggests another structure: + +1. frontmatter +2. `#` article title +3. short opening paragraph +4. `##` sections for background, method, result, checklist, takeaway, or next step +5. fenced code, tables, math, and images where needed +6. short closing section + +## Resources + +- Read [references/ax-blog-markdown-reference.md](references/ax-blog-markdown-reference.md) for the concrete syntax and behavioral constraints of this repo. +- Start from [assets/article-template.md](assets/article-template.md) when creating a new article from scratch. + +## Output Requirements + +- Output plain Markdown, not HTML. +- Keep frontmatter valid YAML. +- Keep article structure readable in raw source form. +- Prefer concise, publishable prose over note-dump formatting. +- When editing an existing article, preserve facts, links, and code semantics. + +## Final Check + +Before finishing, verify: + +- frontmatter keys are supported +- summary is present and useful +- heading depth is reasonable +- code blocks are fenced +- math syntax is valid Markdown math +- image and link paths are plausible for the repo +- no required meaning depends on raw HTML +- no sensitive IPs, hostnames, credentials, user names, or local absolute paths remain +- the article does not mention that sanitization was performed unless the user explicitly requested that wording diff --git a/.agents/skills/ax-blog-markdown-typesetting/agents/openai.yaml b/.agents/skills/ax-blog-markdown-typesetting/agents/openai.yaml new file mode 100644 index 0000000..846ce94 --- /dev/null +++ b/.agents/skills/ax-blog-markdown-typesetting/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "AX Blog Markdown" + short_description: "按 AX Blog 语法编排文章与 frontmatter。" + default_prompt: "Use $ax-blog-markdown-typesetting to rewrite this draft into AX Blog-compatible Markdown with clean frontmatter and stable article structure." diff --git a/.agents/skills/ax-blog-markdown-typesetting/assets/article-template.md b/.agents/skills/ax-blog-markdown-typesetting/assets/article-template.md new file mode 100644 index 0000000..0551aab --- /dev/null +++ b/.agents/skills/ax-blog-markdown-typesetting/assets/article-template.md @@ -0,0 +1,49 @@ +--- +title: 示例标题 +date: 2026-05-16 +tags: [标签一, 标签二] +collections: [合集名] +summary: 用一句话概括文章价值、主题或结论。 +draft: false +featured: false +--- + +# 示例标题 + +用一小段说明这篇文章回答什么问题，或者给出核心判断。 + +## 背景 + +交代上下文、问题来源或使用场景。 + +## 主体 + +分段展开核心内容。需要代码时使用 fenced code block： + +```ts +export function example(name: string): string { + return `hello, ${name}`; +} +``` + +需要公式时使用： + +行内公式 $E = mc^2$。 + +块级公式： + +$$ +\sum_{i=1}^{n} i = \frac{n(n+1)}{2} +$$ + +## 补充材料 + +- 可以放列表 +- 可以放表格 +- 可以放相对图片 + +![示例图片](../assets/example.png) + +## 结论 + +用两三句话收束文章，给出结果、建议或下一步。 diff --git a/.agents/skills/ax-blog-markdown-typesetting/references/ax-blog-markdown-reference.md b/.agents/skills/ax-blog-markdown-typesetting/references/ax-blog-markdown-reference.md new file mode 100644 index 0000000..1835f4a --- /dev/null +++ b/.agents/skills/ax-blog-markdown-typesetting/references/ax-blog-markdown-reference.md @@ -0,0 +1,208 @@ +# AX Blog Markdown Reference + +## Frontmatter + +Use YAML frontmatter at the top of each article. + +Supported keys: + +- `title`: string. Prefer a clear title that can stand alone in archive pages. +- `date`: string or date-like value. Prefer `YYYY-MM-DD`. +- `tags`: array of strings or comma-separated string. +- `collections`: array of strings or comma-separated string. +- `summary`: string. Keep it short enough to read well in cards and tables. +- `draft`: boolean. `true` excludes the article from public output. +- `featured`: boolean. Marks the article as recommended on the home page. +- `pinned`: boolean. Moves the article ahead of normal chronological order. + +Minimal example: + +```yaml +--- +title: 本地搜索索引如何设计 +date: 2026-04-20 +tags: [搜索, 前端, 性能] +collections: [前端工程] +summary: 一个小型博客可以用构建期 JSON 索引完成站内搜索，不一定需要引入搜索服务。 +draft: false +featured: false +--- +``` + +## Heading behavior + +- The system reads the article title from frontmatter. +- Article pages drop the first Markdown `#` heading if present. +- Prefer one top-level `#` in the body that matches or closely tracks the frontmatter title. +- Use `##` and `###` for the real article structure. +- The right-side table of contents includes headings up to level 3. + +Recommended pattern: + +```md +# 文章标题 + +导语段落。 + +## 背景 + +内容。 + +## 方法 + +内容。 + +### 细节 + +内容。 +``` + +## Supported Markdown features + +- CommonMark-style paragraphs and headings +- Ordered and unordered lists +- Fenced code blocks with language labels +- Inline code +- Tables +- Blockquotes +- Relative and absolute links +- Relative and absolute images +- Inline math with `$...$` +- Block math with `$$ ... $$` + +## Code blocks + +Always use fenced code blocks. Add a language label when possible. + +Example: + +````md +```ts +export function hotness(views: number, likes: number): number { + return views + likes * 5; +} +``` +```` + +The renderer uses `highlight.js`. Unknown languages fall back to plaintext. + +## Math + +Math is rendered with KaTeX when `enableMath` is on. + +Inline example: + +```md +行内公式：$E = mc^2$ +``` + +Block example: + +```md +$$ +\sum_{i=1}^{n} i = \frac{n(n+1)}{2} +$$ +``` + +Keep math expressions clean and avoid mixing them with raw HTML. + +## Links and images + +Absolute paths such as `/posts/` stay as-is. + +Relative Markdown links are rewritten: + +- `./next.md` becomes a same-article route like `/a//next/` +- relative asset paths such as `../assets/diagram.svg` become public asset URLs under the article output path + +Use: + +```md +[返回首页](/) +![示例配图](../assets/diagram.svg) +``` + +Avoid linking to local absolute filesystem paths. + +## Sensitive information + +AX Blog articles should be publishable after rewriting. Silently remove or generalize sensitive values from drafts: + +- IP addresses and private hostnames +- internal Git remotes, registry URLs, SSH hosts, and service ports +- usernames, personal Home directories, NAS paths, workstation paths, and local absolute paths +- API tokens, passwords, secret keys, cookies, private emails, phone numbers, and similar identifiers + +When a command needs the shape of a value, use a neutral replacement instead: + +```bash +git clone ssh://git@private-git-host:port/group/project.git +python /path/to/project/script.py --config /path/to/project/config.yaml +export API_TOKEN="TOKEN_VALUE" +``` + +Do not add article text that says the original values were hidden, redacted, anonymized, or replaced. The final Markdown should read naturally without exposing the sanitization step. + +## Raw HTML and safety + +Raw HTML inside Markdown is disabled. + +This means: + +- `