add-blog-posts

name

add-blog-posts

description

Use this skill to add, import, or migrate one or more blog posts, notes, essays, articles, Markdown files, Word documents, or rich-content writing folders into an existing static personal website or blog while preserving the site's current article style, content structure, navigation, indexes, archives, tags, assets, math, links, tables, code blocks, embeds, and homepage entry points. Use it for pasted posts, local Markdown files, Obsidian notes, .docx drafts, old static HTML posts, exported blog content, or small-to-medium batches of posts after a site has already been created.

Add Blog Posts

Goal

Add user content to an existing static blog without forcing a new blog system.

This skill must first understand how the current site already represents posts, then add new content in that style. It is not a generic Markdown-to-HTML converter.

Contract

Inputs:

• Existing static site folder and its current post/index/template system.
• One or more source posts: Markdown, Obsidian notes, Word documents, old HTML, pasted text, images, attachments, or content folders.
• Optional metadata such as title, date, tags, summary, slug, cover image, and import scope.

Outputs:

• New article/detail pages that match the site's existing article style.
• Updated entry points such as blog index, archive, tags/categories, homepage recent posts, search data, RSS, or sitemap when those systems already exist.
• Copied/relinked local images and attachments with page-relative paths.
• Updated EDITING.md post instructions when applicable.

Boundaries:

• Do not redesign the site or create a new post system when an existing one is clear.
• Do not invent metadata, dates, authors, or claims that the source does not support.
• Do not add remote math/CDN dependencies silently.
• Do not publish; use publish-static-site.

Success gate:

• New posts render in the existing style and are reachable from the appropriate indexes.
• Images, math, links, code, tables, and rich content work or unresolved items are explicitly reported.
• Paths are page-relative from article and index pages.
• Affected pages pass browser validation and review-static-site can pass or only report accepted limitations.

If gate fails:

• Fix conversion, metadata, paths, assets, or index wiring in this skill.
• Use edit-site-part for small visual fixes caused by the import.
• Use review-static-site again after fixes.

Use When

Use this skill when the user wants to:

• Add one new article, note, essay, or blog post.
• Import several Markdown files into a static site.
• Move posts from an old blog into a new generated site.
• Convert pasted article text into a site article page.
• Update the blog index, archive, tags, homepage recent posts, or related entry points.
• Preserve the current site's visual language while adding content.

Do not use this skill to choose a theme, build a new site from scratch, recreate a website's style, personalize profile/about content, make a tiny visual tweak, publish the site, or convert the project to a framework.

Inputs

Use whatever is available:

• Static site folder, usually site/, dist/, out/, or public/.
• One or more Markdown files, Word documents, pasted posts, old HTML files, image folders, or content folders.
• EDITING.md, page map, or handoff notes from previous skills.
• Existing article template pages or representative posts.
• User-provided title, date, tags, category, summary, slug, cover image, and publication preference.
• Whether to import all posts, a selected subset, or a representative batch first.

If source content is large, inspect the structure first and avoid importing everything blindly.

1. Understand The Existing Post System

Before writing new posts, inspect how the site currently works.

Check for:

• Post files such as posts/*.html, notes/*.html, articles/*.html, or nested route folders.
• Index pages such as blog.html, archive/index.html, notes/index.html, tags/index.html, or category/index.html.
• Data files such as data/posts.json, data/notes.json, data/site.json, or profile.json.
• JavaScript data arrays in assets/script.js or similar files.
• Homepage sections for recent posts, featured posts, notes, reading lists, or writing highlights.
• Existing article/detail pages that can be used as templates.
• Existing path strategy: whether templates use page-relative links such as ../assets/style.css or server-root links such as /assets/style.css.
• RSS, Atom, sitemap, search index, or tag/category pages if already present.
• EDITING.md instructions for adding posts.
• Existing image and attachment conventions, such as assets/images/posts/, colocated post folders, cover fields, figure classes, lightbox markup, captions, or responsive image wrappers.
• Existing rich-content conventions, such as math rendering, code highlighting, tables, footnotes, callouts, heading anchors, table of contents, link cards, embeds, diagrams, and citation/reference sections.

Follow the existing structure. Do not invent a new post system when the site already has one.

2. Extract Post Metadata

For each source post, extract or derive:

• Title.
• Date.
• Slug.
• Tags or category.
• Summary or excerpt.
• Cover image or hero image, if present and usable.
• Source path.
• Reading time, only if the current site already uses it or it is easy to compute consistently.

Use frontmatter when present. Otherwise infer from the first heading, filename, surrounding folder, visible date text, or first paragraph.

Do not invent specific dates, tags, authors, or claims. If a field is missing and cannot be inferred, use a clear placeholder or omit the field when the site style allows it.

3. Convert Content To The Site's Style

Create new article pages by matching the existing article template and reading experience.

Preserve:

• Header, navigation, footer, sidebars, and shared shell.
• Article typography, spacing, metadata layout, tags, back links, and related links.
• Any special theme language, such as log entries, field notes, cards, terminal/archive framing, or minimal essays.
• Existing CSS class conventions and data structures.

For Markdown:

• Convert headings, paragraphs, blockquotes, lists, task lists, tables, code blocks, links, footnotes, callouts, and images into semantic HTML.
• Preserve code language labels when available.
• Keep image references page-relative and copy local images only when needed.
• Keep Chinese, Japanese, Korean, accented Latin, and other non-ASCII text as readable UTF-8.

For old HTML:

• Extract the article body and metadata.
• Remove old site chrome, analytics, comments, unrelated navigation, and source-site identity.
• Rewrap the content in the new site's article template.

3.5. Preserve Static Path Compatibility

When adding posts, compute paths from each generated page's location. Do not copy paths from index.html blindly into nested article pages.

Default rules:

• New article pages should use page-relative links for shared CSS, JavaScript, fonts, images, and navigation.
• If the post is generated at posts/my-post.html, shared assets usually need ../assets/style.css, ../assets/script.js, and post images such as ../assets/images/posts/my-post/figure.png.
• Links from root pages to the post should usually be posts/my-post.html.
• Links from the post back to root pages should usually be ../index.html, ../blog.html, or ../archive/index.html, depending on the structure.
• Do not introduce root-absolute paths such as /assets/..., /posts/..., /data/..., or /images/... unless the existing site intentionally uses them and the user accepts that direct file:// opening and subpath hosting may break.
• Update JavaScript-generated links, search results, tag filters, related-post links, cover paths, RSS/sitemap entries, and any data files with the same path strategy.
• If the existing site already has root-absolute links by accident, report it and prefer fixing the affected paths instead of extending the problem.

Avoid local-file fetch problems:

• Do not make newly added posts depend on fetch() of local JSON/Markdown for the article body.
• If indexes are rendered from data, keep essential post links visible in HTML or use a relative JavaScript data object that works with direct-open preview.

4. Handle Rich Content Formats

Preserve rich content intentionally instead of flattening everything into plain paragraphs.

First inspect whether the current site already supports:

• Math rendering with KaTeX, MathJax, custom CSS, or raw TeX blocks.
• Code highlighting, language labels, copy buttons, or terminal-style code frames.
• Tables, responsive table wrappers, footnotes, callouts, admonitions, quotes, and task lists.
• Heading anchors, table of contents, backlinks, related notes, or section links.
• Link cards, bookmark lists, URL index pages, citations, reference lists, or bibliography sections.
• Embedded media such as video, audio, PDFs, iframes, Mermaid diagrams, Excalidraw/SVG diagrams, or downloadable attachments.

Follow the existing pattern when one exists. If no pattern exists, use simple semantic HTML and report any feature that needs an additional renderer.

Math and formulas:

• Preserve inline and display math from $...$, $$...$$, \(...\), \[...\], or Word equation exports.
• Use the site's existing math renderer if present.
• If the source contains many formulas and no renderer exists, prefer a local KaTeX integration for plain static sites: store KaTeX CSS/JS/fonts under a local vendor folder, add a small local render script, and do not rely on a CDN.
• Do not silently add a remote MathJax/KaTeX dependency to an otherwise dependency-free site.
• Preserve the original TeX inside math-marked elements as a fallback, then render it in the browser. If rendering fails for a formula, the readable TeX fallback should remain visible instead of breaking the page.
• Normalize obvious source syntax that KaTeX needs, such as softmax arrows, \cdot, \times, punctuation accidentally mixed into formulas, and common Q/K/V expressions.
• Do not leave formula-heavy posts as code-looking TeX boxes when a math renderer has been added.
• Keep formulas readable in source and in the browser fallback.

Code blocks:

• Preserve fenced code language names.
• Escape HTML inside code blocks.
• Keep long code lines scrollable rather than breaking the page layout.
• Reuse existing code block styling, copy buttons, and syntax-highlighting conventions.
• Do not execute source code from posts.

Tables:

• Convert Markdown, Word, or HTML tables into semantic tables.
• Wrap wide tables in the site's existing responsive table container or add a small local wrapper.
• Preserve header rows, alignment intent, and captions when available.

Links, URL indexes, and internal references:

• Preserve external links with clear link text.
• Convert relative links and Markdown .md links to the generated static HTML path when the target post is imported.
• Convert Obsidian wikilinks such as [[Note]], [[Note#Heading]], and [[Note|Alias]] into normal links when the target can be resolved.
• Preserve unresolved internal links as visible placeholders or plain text, and report them.
• Generate stable heading IDs when the site uses anchor links or table of contents.
• For URL index, bookmark, or link-roundup posts, keep the list structure. Use the site's existing link-card/list style when present; do not invent preview cards that require fetching remote metadata unless the user asks.

Footnotes, citations, and references:

• Convert Markdown footnotes into a footnotes section using the site's existing style if present.
• Preserve citation labels, bibliography entries, and reference links.
• If source text uses unresolved citation keys such as [@paper2024], keep them visible and report that citation metadata is missing unless a bibliography file is provided.

Callouts, admonitions, and block types:

• Convert Obsidian/GitHub-style callouts such as > [!NOTE], > [!TIP], > [!WARNING], and > [!IMPORTANT] into the site's closest callout/card/blockquote pattern.
• Preserve task lists as checklists when the current site has checklist styling; otherwise use disabled checkbox markup or plain lists.

Embeds and attachments:

• For PDFs, slides, datasets, downloads, audio, and video, prefer a clear link or download card unless the site already embeds that media type.
• Copy local attachments only when provided by the user.
• Keep remote embeds only when the user owns or intentionally references them.
• For Mermaid or diagram blocks, use the existing renderer if present. If no renderer exists, preserve the source block and report it, or convert to a static SVG/PNG only when practical and appropriate.

5. Handle Post Images And Assets

Handle images according to the current site's asset conventions.

First inspect how existing posts store and render images:

• Shared assets folder such as assets/images/posts/<slug>/.
• Colocated post assets such as posts/<slug>/images/.
• Data fields such as cover, heroImage, thumbnail, or images.
• Figure markup, captions, lightbox links, lazy loading, width/height attributes, and responsive CSS classes.

Prefer the existing pattern. If no pattern exists, use a simple static convention such as:

assets/images/posts/<post-slug>/

For Markdown sources:

• Resolve relative image links from the Markdown file's folder.
• Copy local images into the site's post image folder when needed.
• Rewrite Markdown image references to the new relative site paths.
• For nested article pages, include the correct ../ depth in image paths.
• Preserve alt text from Markdown when present.
• Convert image captions if the source uses nearby italic text, title attributes, or Obsidian-style embeds.
• Do not leave links pointing to absolute local disk paths.

For Obsidian notes:

• Support common embeds such as ![[image.png]] and relative attachment folders.
• Search likely attachment folders near the note, such as attachments/, assets/, images/, or the vault's configured attachment folder when visible.
• Rewrite embeds into normal HTML image or figure markup.

For Word .docx sources:

• Extract embedded images from the document package or use available document tooling.
• Preserve image order relative to the surrounding text when possible.
• Save extracted images under the post image folder with stable names.
• Use nearby captions or alt text when available; otherwise create neutral alt text that describes the role, such as the post title plus image number.
• Do not embed images as base64 in HTML unless the existing site already does this.

For old HTML sources:

• Copy local images only when they are part of the article content and the user has provided or owns them.
• For remote images, download or preserve them only when the user owns them, the license allows reuse, or the user explicitly confirms permission.
• Replace unavailable or unlicensed images with a clear placeholder and report them.
• Remove tracking pixels, avatars, ads, comment images, badges, and unrelated old-site chrome.

For cover or thumbnail images:

• Use the current site's existing cover field or card markup.
• If the source has a clear cover image, wire it into the article and index card.
• If no cover exists, omit it or use the site's existing placeholder pattern; do not invent decorative stock images.

Always verify that copied image paths resolve from the generated article page and from any index card that references them. A path that works from the homepage may still be wrong from posts/<slug>.html.

6. Update Entry Points

Update the places the current site uses to expose posts.

Possible entry points:

• Blog or notes index.
• Archive page.
• Tag or category pages.
• Homepage recent posts.
• Homepage featured posts, only when the user asks or the current site needs a representative item.
• Search index or JavaScript data file.
• RSS/Atom/sitemap only if these already exist.

Do not create complex new tag, search, RSS, or pagination systems unless the site already has them or the user explicitly asks.

Do not put every imported post on the homepage. Use the site's existing limit or choose a small recent/featured subset.

7. Batch Strategy

For one post, add it fully and wire it into the relevant indexes.

For small batches, import all posts if the structure is clear and low-risk.

For large batches:

• Inspect file count, formats, frontmatter consistency, rich-content features, images/assets, and date/tag quality first.
• Import a representative subset if the user did not explicitly ask for full migration.
• Preserve a clear mapping from source files to generated pages.
• Avoid overwhelming the homepage or hand-written index pages.
• Report what was imported and what remains.

When there are conflicts, such as duplicate slugs or missing assets, choose safe names and report the issue.

8. Editing Guide

Update EDITING.md when posts are added.

Record:

• Where new article files live.
• How post metadata is represented.
• Which indexes or data files must be updated for future posts.
• Where homepage recent/featured posts are controlled.
• How tags/categories are handled.
• Where post images and covers are stored, and how to reference them.
• How math, code blocks, tables, footnotes, callouts, internal links, URL indexes, embeds, and attachments are represented.
• Any omitted fields, unresolved assets, or posts not imported.

9. Validation

Use an actually available interactive browser tool as the first-choice way to inspect the affected pages. "Available" means it is exposed in the current turn's callable tool list. In Codex this may be the Browser/in-app browser plugin when routed into the turn; in other agents it may be an equivalent visible browser, browser-use tool, or devtools-backed browser.

If no interactive browser tool is callable, do not pretend the browser inspection happened. Ask the user to enable or invoke the browser tool if post rendering, math, images, or links need visual confirmation; for Codex, that may mean sending a request that explicitly mentions @browser. If the user does not re-route or the client has no such tool, fall back to Playwright, screenshots, static audits, or source checks and state the limitation.

Do not default to Playwright or screenshots-only validation when an interactive browser tool is actually callable. Use Playwright only as a fallback when no interactive browser tool is callable, when the user explicitly asks for it, or when repeatable scripted regression is specifically needed. Screenshots may be captured after the interactive browser pass as evidence.

Check:

• At least one newly added article page.
• The blog/index/archive page that links to it.
• The homepage if it was updated.
• Tag/category/search pages if they were updated.

Confirm links work, article text is readable, layout matches the existing style, images and covers resolve, paths are page-relative from both the article and index pages, no accidental root-absolute site-local paths remain, and non-ASCII text is readable in source.

For posts with rich content, also check representative formulas, code blocks, tables, footnotes, callouts, internal links, URL lists, and embeds in the browser. For math-heavy posts, verify rendered math visually in the browser and confirm the browser DOM contains rendered math output from the chosen renderer, not only raw TeX text.

Call or suggest using review-static-site at the end.

Output

Keep the final report concise:

• Which posts were added or imported.
• Which indexes or entry points were updated.
• Which files changed.
• What browser/local validation was done.
• Any posts, assets, rich-content features, tags, links, or metadata that still need attention.