---
name: format-for-publish
description: Format a draft with WordPress shortcodes and export to .docx
argument-hint: "[draft-file]"
---

# Format for Publish Skill

Transform a finished draft into a WordPress-ready document with Ahrefs shortcodes, then export to .docx format.

## Input

**Draft file path** - Path to a cited draft file (e.g., `./5-drafts-cited/pinterest-seo.md`)

## Dependencies

**pandoc** is required for .docx export:
```bash
brew install pandoc
```

---

## WordPress Shortcodes Reference

### Content Structure
- `[intro_text][/intro_text]` - Wraps the intro paragraph
- `[intro_toc]` - Auto-generates table of contents
- `[post_nav_link]` - Section navigation anchor (wraps each H2)

### Callouts & Highlights
- `[recommendation title="Tip"][/recommendation]` - Highlighted tip box
- `[sidenote][/sidenote]` - Side note callout
- `[editor_note][/editor_note]` - Editor attribution

### Quotes & Attribution
- `[blockquote]` - Styled quote with author

### Media & Widgets
- `[caption][/caption]` - Image with caption
- `[toolWidget]` - Ahrefs tool embed

### End Matter
- `[further_reading][/further_reading]` - Related articles list

---

## Shortcode Syntax

### post_nav_link
```
[post_nav_link link_text="Section Title" section="section-slug"]

## Section Title

[/post_nav_link]
```

### recommendation
```
[recommendation title="Tip"]

Your tip content here.

[/recommendation]
```

### blockquote
```
[blockquote size="small" author="John Mueller" author_photo="URL" author_job="Search Advocate," link_text="Google" link_url="https://google.com"]

_The quoted text goes here._

[/blockquote]
```

### toolWidget
```
[toolWidget tool="Keyword Generator" heading="Find thousands of keyword ideas in seconds"]
```

Available tools: "Website Traffic Checker", "Website Authority Checker", "Backlink Checker", "Keyword Generator", "Keyword Difficulty Checker"

---

## Workflow

### Phase 1: Read and Analyze Draft

Identify elements needing shortcodes: intro paragraph, H2 headings, tips, expert quotes, image placeholders, Ahrefs tool mentions.

### Phase 2: Apply Shortcodes

Transform content:
- First paragraph → `[intro_text]...[/intro_text]` + `[intro_toc]`
- H2 headings → wrapped in `[post_nav_link]`
- Tips/Pro tips → `[recommendation title="Tip"]`
- Expert quotes → `[blockquote]`
- Screenshot placeholders → `[caption]`
- End of article → `[further_reading]`

### Phase 3: Clean Up

Remove metadata header, Draft Notes section, HTML comments. Ensure proper spacing around shortcodes.

### Phase 4: Export to .docx

```bash
pandoc input.md -o output.docx --from markdown --to docx
```

---

## Output

1. **Formatted markdown** saved to `7-publish/[slug].md`
2. **Word document** saved to `7-publish/[slug].docx`

## Example Usage

```
/format-for-publish ./5-drafts-cited/youtube-seo.md
```

---

## Image Handling

The draft may contain inline markdown images from three sources:

1. **Uploaded images** — `![alt](/applications/seo_pipeline/uploads/filename.png)` or `![alt](/applications/seo_pipeline/api/upload-source/token/raw)`
2. **LinkedIn post screenshots** — `![alt](/applications/linkedin_scrapbook/api/pipeline/embeds/filename.png)`
3. **External images from source URLs** — `![alt](https://example.com/image.png)`

### Conversion rules

**Preserve all images in the output.** Do not remove, skip, or replace images with `[SCREENSHOT: ...]` placeholders.

**Convert each `![alt](src)` to the WordPress `[caption]` shortcode** when the image has context (a lead-in sentence or a follow-up caption). Format:

```
[caption id="" align="aligncenter" width="auto"]
<img src="IMAGE_URL" alt="Alt text" />
Caption text here.
[/caption]
```

- Use the image’s alt text as both the `alt` attribute and the basis for the caption.
- If the draft has a line of text immediately after the image that reads like a caption (italicized, starts with "Source:", or is a short observation), use that as the caption text and remove the standalone line.
- If there’s no natural caption, use the alt text as the caption.

**Images without context** (no lead-in, no caption — just a bare `![alt](src)` on its own line) can stay as plain `<img>` tags without `[caption]` wrapping:

```
<img src="IMAGE_URL" alt="Alt text" />
```

**External image attribution:** If the image is from an external source and the draft includes a "Source: [Title](url)" line, include that attribution inside the `[caption]` shortcode.

**Do not rewrite image URLs.** The URLs are stable Console routes — leave them exactly as they appear in the draft. WordPress editors will replace them with uploaded media URLs before publishing.