2026-04-16

Word to Hugo Blog Workflow

Purpose

The purpose of this guide is to make your blog publishing workflow simpler:

  • write in Word as usual
  • export the document to Markdown
  • keep images with the post using a Hugo page bundle
  • avoid manual renaming or relinking of images

Step-by-step workflow

1. Create a new post folder

In your Hugo site, create a new folder for the post under content/blog/.

1mkdir -p content/blog/my-word-post

2. Save your Word file as .docx

Save the Word document from Microsoft Word as a .docx file. For example:

  • my-word-post.docx

3. Convert Word to Markdown with Pandoc

Use Pandoc to convert the .docx file to Markdown and extract images automatically.

1pandoc -f docx -t markdown --extract-media=. -o content/blog/my-word-post/index.md my-word-post.docx

This command does three things:

  • reads my-word-post.docx
  • writes Markdown to content/blog/my-word-post/index.md
  • extracts embedded images into a media/ folder inside the current directory

4. Move the Markdown and images into the page bundle

If Pandoc created a media/ folder beside index.md, move or keep it inside the post folder.

Your structure should look like this:

1content/blog/my-word-post/
2  index.md
3  media/
4    image1.png
5    image2.png

5. Add or update front matter in index.md

Make sure the top of content/blog/my-word-post/index.md contains Hugo front matter, for example:

1---
2title: "My Word Post"
3date: 2026-04-16
4draft: false
5categories: ["writeup"]
6tags: ["hugo","word","pandoc"]
7---

If Pandoc did not include front matter, add it manually.

6. Check the image references

Pandoc should generate image links automatically, like this:

1![Image description](media/image1.png)

If the image paths are already correct, you do not need to rename the files.

7. Preview the post locally

Run Hugo to preview the site and confirm the new post renders correctly.

1hugo server -D

Open the local URL shown in the terminal and verify the post content and images.

Why this is easier

This method is easier because it avoids manual image labeling after export:

  • Pandoc extracts images automatically
  • image links are inserted into Markdown for you
  • the page bundle keeps everything together
  • you can continue writing in Word without changing your workflow

Optional tip

If you want a cleaner image folder name, move media/ into the page bundle and use the same location for the Markdown file:

1mv media content/blog/my-word-post/

Then the full structure stays self-contained inside content/blog/my-word-post/.