Word to Markdown for Jekyll and Hugo — Static Site Workflow
- Jekyll and Hugo use Markdown files with YAML frontmatter
- Convert .docx to .md in browser, then add frontmatter manually
- Headings, lists, links, and tables all convert to correct Markdown syntax
- No upload — process Word files privately in your browser
Table of Contents
Jekyll and Hugo build static sites from Markdown files. Getting Word documents into those systems means two steps: convert .docx to .md, then add YAML frontmatter. The browser converter handles the first step in seconds; the frontmatter takes about a minute to add manually. Here is the complete workflow for both Jekyll and Hugo.
Why Word Content Ends Up in Static Sites
Static site generators are common in developer blogs, documentation sites, and technical publications. The content lives in Markdown files in a Git repository. But content does not always originate there — blog posts drafted by non-developers, documentation written by product managers, technical guides written by support teams all commonly start in Word.
The conversion workflow bridges the gap. Non-developers write in the tool they know (Word), hand the file to the developer or site maintainer, who converts and adds it to the repository. It is simpler than teaching non-developers to write Markdown directly and more reliable than copy-pasting content manually.
Converting the Word Document to Markdown
The conversion step:
- Open the Word to Markdown converter
- Drop the .docx file
- Click Download .md
The .md file you get back has clean Markdown: headings as # syntax, body text as paragraphs, bold/italic preserved, lists as - and 1. syntax, links as [text](url), and tables as pipe tables.
Save this .md file with a slug-based filename: my-post-title.md or 2026-04-14-my-post.md — the filename conventions vary by how your Jekyll or Hugo project is configured.
Adding Jekyll Frontmatter
Jekyll requires YAML frontmatter at the top of every post and page file. Open the downloaded .md file in any text editor (VS Code, Sublime Text, nano, vim) and add this block at the very top, before any Markdown content:
--- layout: post title: "Your Post Title Here" date: 2026-04-14 10:00:00 -0500 categories: [documentation, tutorial] author: Author Name excerpt: "A brief summary of this post for listing pages." ---
Jekyll's standard post format goes in the _posts directory with the filename format YYYY-MM-DD-title.md. For pages (not posts), use the layout: page value and place the file in the project root or a subdirectory.
After adding the frontmatter, run bundle exec jekyll serve to preview the result locally before deploying.
Adding Hugo Frontmatter
Hugo also requires frontmatter, supporting YAML, TOML, and JSON formats. YAML is the most common:
--- title: "Your Post Title" date: 2026-04-14 draft: false description: "Brief post description." categories: ["documentation"] tags: ["tutorial", "workflow"] author: "Author Name" ---
Hugo content files go in the content/ directory, organized into subdirectories that match your site structure. For a blog post, the path might be content/blog/my-post-title.md or content/posts/my-post-title/index.md depending on your Hugo theme's structure.
Run hugo server to preview locally after adding the frontmatter and placing the file.
Handling Images From Word in Static Sites
Images from Word documents do not convert directly to Markdown in a way that works for static sites — Markdown image syntax needs a file path or URL, not base64 data. The recommended workflow for images:
- Rename the .docx file to .zip and unzip it
- Find images in the word/media/ folder
- Copy the images to your static site's image directory — for Jekyll typically
assets/images/, for Hugo typicallystatic/images/or alongside the content file if using Page Bundles - In the Markdown file, add image references:
For Hugo with Page Bundles, placing the .md file and images together in a folder (index.md + image.jpg) and referencing images relatively () is the cleanest approach for portable, self-contained content.
Once the frontmatter is added and images are wired up, the file is ready to commit to the repository. The static site builder handles the rest.
Convert Word Docs to Markdown for Your Static Site — Free
Drop your .docx and get .md output ready for Jekyll, Hugo, or MkDocs. No upload, no account, just clean Markdown.
Open Free Word to MarkdownFrequently Asked Questions
Does this workflow also work for MkDocs and Docusaurus?
Yes. MkDocs uses Markdown files in a docs/ directory with a mkdocs.yml config. Docusaurus uses Markdown in a docs/ directory with frontmatter. The Word to Markdown conversion step is identical; the frontmatter format differs slightly per platform.
Can I automate the frontmatter addition as part of a build pipeline?
Yes. A simple shell script can prepend frontmatter to a .md file using echo or cat. For larger workflows, Pandoc can inject frontmatter via its --metadata flag during conversion. The browser tool is for manual conversions; scripted workflows benefit from Pandoc.
What is the best way to handle shortcodes and Hugo-specific syntax in converted content?
The converter produces standard Markdown only — no shortcodes. After conversion, add Hugo shortcodes manually where needed (e.g., {{< figure >}} for styled images, {{< youtube >}} for embedded video). These are site-specific additions that cannot be automated from a generic Word source.
Does the Markdown output handle code blocks for a technical blog?
If your Word document has code samples formatted in a monospace font, they typically convert as code-fenced blocks. Add the language identifier manually after conversion (python, bash, javascript) for syntax highlighting in your static site.
