{"id":14457595,"url":"https://github.com/ashishb/wp2hugo","last_synced_at":"2026-04-19T11:01:15.201Z","repository":{"id":229421972,"uuid":"769482911","full_name":"ashishb/wp2hugo","owner":"ashishb","description":"The best WordPress to static site migrator","archived":false,"fork":false,"pushed_at":"2026-04-19T09:08:50.000Z","size":739,"stargazers_count":295,"open_issues_count":0,"forks_count":25,"subscribers_count":3,"default_branch":"main","last_synced_at":"2026-04-19T09:30:25.317Z","etag":null,"topics":["hugo","hugo-utility","static-site","static-site-generator","static-website"],"latest_commit_sha":null,"homepage":"https://ashishb.net/tech/wordpress-to-hugo/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ashishb.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2024-03-09T07:45:42.000Z","updated_at":"2026-04-19T09:08:34.000Z","dependencies_parsed_at":null,"dependency_job_id":"3e820ea0-a286-4630-8a4d-fe6003774ce2","html_url":"https://github.com/ashishb/wp2hugo","commit_stats":null,"previous_names":["ashishb/wp2hugo"],"tags_count":39,"template":false,"template_full_name":null,"purl":"pkg:github/ashishb/wp2hugo","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashishb%2Fwp2hugo","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashishb%2Fwp2hugo/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashishb%2Fwp2hugo/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashishb%2Fwp2hugo/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ashishb","download_url":"https://codeload.github.com/ashishb/wp2hugo/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ashishb%2Fwp2hugo/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32004043,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-18T20:23:30.271Z","status":"online","status_checked_at":"2026-04-19T02:00:07.110Z","response_time":55,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hugo","hugo-utility","static-site","static-site-generator","static-website"],"created_at":"2024-09-01T17:01:28.698Z","updated_at":"2026-04-19T11:01:15.194Z","avatar_url":"https://github.com/ashishb.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# WordPress to Hugo Static site migrator\n\n[![Featured on Hacker News](https://hackerbadge.now.sh/api?id=41377331)](https://news.ycombinator.com/item?id=41377331)\n\n![GitHub contributors](https://img.shields.io/github/contributors/ashishb/wp2hugo?logo=GitHub)\n![GitHub downloads](https://img.shields.io/github/downloads/ashishb/wp2hugo/total?logo=GitHub)\n\n[![Build wp2hugo](https://github.com/ashishb/wp2hugo/actions/workflows/build-go.yaml/badge.svg)](https://github.com/ashishb/wp2hugo/actions/workflows/build-go.yaml)\n[![Validate Go code formatting](https://github.com/ashishb/wp2hugo/actions/workflows/format-go.yaml/badge.svg)](https://github.com/ashishb/wp2hugo/actions/workflows/format-go.yaml)\n[![Lint and Test Go](https://github.com/ashishb/wp2hugo/actions/workflows/lint-and-test-go.yaml/badge.svg)](https://github.com/ashishb/wp2hugo/actions/workflows/lint-and-test-go.yaml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/ashishb/wp2hugo/src/wp2hugo)](https://goreportcard.com/report/github.com/ashishb/wp2hugo/src/wp2hugo)\n\n[![Lint Markdown](https://github.com/ashishb/wp2hugo/actions/workflows/lint-markdown.yaml/badge.svg)](https://github.com/ashishb/wp2hugo/actions/workflows/lint-markdown.yaml)\n[![Lint YAML](https://github.com/ashishb/wp2hugo/actions/workflows/lint-yaml.yaml/badge.svg)](https://github.com/ashishb/wp2hugo/actions/workflows/lint-yaml.yaml)\n[![Lint GitHub Actions](https://github.com/ashishb/wp2hugo/actions/workflows/lint-github-actions.yaml/badge.svg)](https://github.com/ashishb/wp2hugo/actions/workflows/lint-github-actions.yaml)\n[![Validate Release config](https://github.com/ashishb/wp2hugo/actions/workflows/check-goreleaser-config.yaml/badge.svg)](https://github.com/ashishb/wp2hugo/actions/workflows/check-goreleaser-config.yaml)\n\nThis is the best migrator for migrating WordPress export to Hugo.\nIt handles several weird edge cases that I encountered while trying to migrate my [personal website](https://v1.ashishb.net) to [Hugo-based site](https://v2.ashishb.net/).\n\nWhile this primarily targets Hugo-based code generation, one can use it to convert WordPress blogs to Markdown-based files that can be used with other systems,\nfor example, [Mkdocs](https://www.mkdocs.org/) or [Jekyll](https://jekyllrb.com/).\n\n## Following sites have migrated using `wp2hugo`\n\n1. [ashishb.net](https://ashishb.net/tech/wordpress-to-hugo/)\n1. [inliniac.net](https://inliniac.net/blog/posts/blog-moved-to-hugo/)\n1. [blog.polarweasel.org](https://blog.polarweasel.org/2025/01/09/bye-wordpress/)\n1. [open-bio.org](https://www.open-bio.org/posts/2025-03-04-new-website/) - more details from [Bastian Greshake Tzovaras](https://tzovar.as/migrating-from-wp/)\n1. [Virtual Andy](https://dev.ahill.net/posts/moving-away-from-wpdotcom/)\n1. [bjørn:johansen](https://bjornjohansen.com/wp2hugo/)\n1. [xf.is](https://www.xf.is/2025/01/19/blog-update/)\n1. [retro.moe](https://retro.moe/2025/01/15/migrate_wordpress_to_hugo_in_github_pages/)\n1. [Marcelo Fernandez (in Spanish)](https://blog.marcelofernandez.info/posts/migracion-a-hugo/)\n1. [Mountain Water (Chinese Traditional)](https://mountainandwater.blog/2025/04/15/migration-from-wordpress-to-hugo/)\n1. [Hit To Key](https://hit-to-key.net/posts/2024-10-10-migration/)\n1. [Chuyển địa chỉ](https://tuanbui.net/2024/07/10/chuyen-dia-chi/)\n1. [Cynarski.dev (Polish)](https://cynarski.dev/2024/12/22/migracja_na_hugo/)\n1. [It's a Binary World 2.0](https://www.ericsbinaryworld.com/posts/wordpress-to-hugo-migration-process/)\n1. [The Legal Beaver](https://legalbeaver.ca/2024/06/12/migration-to-hugo/)\n1. [Deuts Log](https://deuts.org/x/446-wp2hugo/)\n1. [cloudowski](https://cloudowski.com/articles/how-ai-helped-me-to-migrate-my-website/)\n1. [Population: One](https://popone.innocence.com/archives/2024/10/06/wordpress-and-migrations-oh-my.php)\n1. [Aurélien Pierre Engineering](https://eng.aurelienpierre.com)\n1. [Spinning Code](https://spinningcode.org/2025/welcome-to-hugo/)\n1. [ITTY](https://itty.nl/converting-wordpress-to-hugo/)\n1. [Sean Graham](https://sean-graham.com/2025/08/01/wordpress-to-hugo/)\n1. [skyboo.net](https://skyboo.net/2026/02/hello-hugo/)\n\n## Commercial usage\n\nI want this project to be as widely accessible as possible, while still funding the development costs.\nThis project is completely free for non-commercial and personal usage.\nCommercial usage is restricted via a license.\nFeel free to contact me if you want to license this commercially.\n\n## What does wp2hugo do better than other migration tools\n\n- wp2hugo is distributed as a single and portable binary executable, requiring no installation and no dependence. The binary is compiled code (written in Go), which provides _much_ better performance than scripted tools.\n- It can run locally on your computer, or on server with shell access, and processes WordPress XML export file. This makes it able to migrate very large blogs in a matter of minutes, while other migration tools (e.g. those running server-side PHP code, as WordPress plugins) may time-out, overflow RAM, overload server and fail completely on shared hosting.\n- It migrates all post metadata like GUID, custom fields, taxonomies, and more, so you retain all of your original posts' information, even hidden from user front-end. _(Posts front-matters may need some manual cleanup after migration)_\n- It converts a large range of native WordPress shortcodes and Gutenberg blocks to Hugo shortcodes.\n- It fully imports WordPress media library (files and metadata) and fully supports WordPress galeries (legacy and Gutenberg), which makes it particularly well-suited for photo blogs.\n- It supports translated pages and hierarchical pages and custom post types.\n\n## Usage\n\n### Binary\n\n- Install [hugo](https://github.com/gohugoio/hugo), verify it is `v0.146` or later with `hugo version` command\n- Download the `wp2hugo` tool from [releases](https://github.com/ashishb/wp2hugo/releases)\n- Export your WordPress website via `Tools -\u003e Export` in your admin dashboard\n- Let's say the downloaded file is `wordpress-export.xml` generate the website using `$ wp2hugo --source wordpress-export.xml --download-media`\n\n```bash\n$ wp2hugo\nUsage of wp2hugo:\n  --authors string\n    CSV list of author name(s), if provided, only posts by these authors will be processed (using author slug)\n  --color-log-output\n    enable colored log output, set false to structured JSON log (default true)\n  --continue-on-media-download-error\n    continue processing even if one or more media downloads fail\n  --download-media\n    download media files embedded in the WordPress content\n  --download-all\n    download all media files from the WordPress library, whether embedded in content or not\n  --font string\n    custom font for the output website (default \"Lexend\")\n  --media-cache-dir string\n    dir path to cache the downloaded media files (default \"/tmp/wp2hugo-cache\")\n  --output string\n    dir path to write the Hugo-generated data to (default \"/tmp\")\n  --source string\n    file path to the source WordPress XML file\n  --custom-post-types string\n    CSV list of additional WordPress custom post types to import (using type slug)\n```\n\n### Build from source\n\n```bash\n$ git clone git@github.com:ashishb/wp2hugo.git\n$ cd wp2hugo/src/wp2hugo\n$ make build_prod\n# `./bin/wp2hugo` will contain the binary and you can use it as `$ ./bin/wp2hugo --source wordpress-export.xml --download-media`\n```\n\n### Installation via Package Managers\n\n[![Packaging status](https://repology.org/badge/vertical-allrepos/wp2hugo.svg)](https://repology.org/project/wp2hugo/versions)\n\n## Documentation\n\nMore details on [the documentation](https://github.com/ashishb/wp2hugo/tree/main/doc).\n\n## Goals of `wp2hugo`\n\n### Migrate post types, taxonomies, and their archive pages\n\n1. [x] Migrate posts\n1. [x] Migrate pages in a hierarchical way, using Hugo [page bundles](https://gohugo.io/content-management/page-bundles/),\n1. [x] Migrate tags, categories and [custom taxonomies](https://learn.wordpress.org/lesson/custom-taxonomies/) for all types of posts,\n1. [x] Set the WordPress homepage correctly\n1. [x] Create WordPress author page\n1. [x] Migrate [WPML](https://wpml.org/) translated posts, pages, and custom post types that use the [URL parameter scheme](https://wpml.org/documentation/getting-started-guide/language-setup/language-url-options/#language-name-added-as-a-parameter) (switch the WPML language URL option prior to exporting your blog content to XML),\n1. [x] Migrate any arbitrary WordPress [custom post type](https://learn.wordpress.org/lesson/custom-post-types/) and store them into their own `/content/post-type` subfolder (hierarchical custom posts are fully supported):\n  - [Avada](https://themeforest.net/item/avada-responsive-multipurpose-theme/2833226) FAQ and Portfolios types are supported natively,\n  - [Woocommerce](https://woocommerce.com/) products and product variations types are supported natively,\n  - user can specify a CSV list of arbitrary post types, using the `--custom-post-types` argument when calling the executable. Only post types that have a publishing status (`\u003cwp:status\u003e` in export XML) matching one of the [values of native posts](https://wordpress.org/documentation/article/post-status/) are supported.\n\n### Migrate comments\n\nProvided you don't want to accept new comments, old comments are automatically migrated for all post types (posts, pages and custom). You will need to insert the provided snippet into your relevant theme's `single.html` template. See the [documentation](https://github.com/ashishb/wp2hugo/blob/main/doc/comments.md).\n\n### Migrate permalinks\n\n1. [x] Migrate all the URLs, including media URL,s correctly\n1. [x] Generate Nginx config containing GUID -\u003e relative URL mapping\n1. [x] Migrate the RSS feed with existing UUIDs, so that entries appear the same - this is important for anyone with a significant feed following, see more details of a [failed migration](https://theorangeone.net/posts/rss-guids/)\n1. [x] Map WordPress's RSS `feed.xml` to Hugo's RSS `feed.xml`\n\n### Migrate post content and shortcodes\n\n1. [x] Migrate [page excerpt](https://wordpress.com/support/excerpts/)\n1. [x] Migrate [\"Show more...\" of WordPress](https://wordpress.com/support/wordpress-editor/blocks/more-block/) -\u003e `Summary` in Hugo\n1. [x] Migrate [List Category posts(catlist)](https://wordpress.com/plugins/list-category-posts)\n1. [x] Migrate [WordPress table of content](https://wordpress.com/support/wordpress-editor/blocks/table-of-contents-block/) -\u003e Hugo\n1. [x] Migrate code blocks correctly - migrate existing code class information if available\n1. Migrate embeds:\n    1. [x] Migrate iframe(s) like YouTube embeds\n    1. [x] Migrate [YouTube embeds](https://support.google.com/youtube/answer/171780)\n    1. [x] Migrate WordPress-style [plain-text YouTube embeds](https://wordpress.org/documentation/article/youtube-embed/) in the post body\n    1. [x] Migrate [WP YouTube Lyte](https://wordpress.org/plugins/wp-youtube-lyte/) YouTube embeds\n    1. [x] Migrate [Google Map embed](https://developers.google.com/maps/documentation/embed/get-started) via a custom shortcode `googlemaps`\n    1. [x] Migrate [GitHub gists](https://gist.github.com/)\n1. Migrate WordPress shortcodes:\n    1. [x] Migrate [WordPress [caption] shortcode](https://codex.wordpress.org/Caption_Shortcode) to [Hugo's {{\u003c figure \u003e}}](https://codex.wordpress.org/Caption_Shortcode))\n    1. [x] Migrate [WordPress [audio] shortcode](https://wordpress.org/documentation/article/audio-shortcode/))\n    1. [x] Migrate Wordpress [gallery] shortcode, including [empty Gallery](https://github.com/ashishb/wp2hugo/issues/68)\n1. Migrate Gutenberg blocks and features:\n    1. [x] Migrate WordPress [footnotes](https://github.com/ashishb/wp2hugo/issues/24)\n    1. [x] Migrate Youtube embed Gutenberg blocks\n    1. [x] Migrate image and gallery Gutenberg blocks\n\nMore details on [the documentation](https://github.com/ashishb/wp2hugo/tree/main/doc/shortcodes.md).\n\n### Migrate post metadata and attributes\n\n1. [x] Maintain the draft status for draft and pending posts\n1. [x] Use draft date as a fallback date for draft posts\n1. [x] Featured images - export featured image associations with pages and posts correctly\n1. [x] WordPress [Post formats](https://developer.wordpress.org/advanced-administration/wordpress/post-formats/)\n1. [x] WordPress [Custom fields](https://wordpress.org/documentation/article/assign-custom-fields/), including PHP array deserialization for fields using them\n\n### Migrate media attachments\n\n1. [x] Migrate favicon.ico\n1. [x] Migrate `wp-content/uploads` images embedded in pages to Hugo static files while maintaining relative URLs\n1. [x] Migrate external images (on different hosts) to Hugo static files\n1. [x] Optionally import all media attachments from WordPress library\n1. [x] Import user-defined attachment titles into a Hugo database into `/data/library.yaml`\n\n### Misc\n\n1. [x] Ability to filter posts by author(s), useful for [WordPress multi-site](https://www.smashingmagazine.com/2020/01/complete-guide-wordpress-multisite/) migrations\n1. [x] Custom font - defaults to Lexend\n1. [x] Support for parallax blur backgrounds (similar to [WordPress Advanced Backgrounds](https://wordpress.org/plugins/advanced-backgrounds/))\n\n## Hugo Manager\n\nThis repository contains an experimental tool, `hugomanager`.\nI use this tool for the automatic generation of URLs from the title as well as for knowing which blog posts are still\nmarked as drafts or which ones are scheduled to be published soon.\n\nYou can build that via\n\n```bash\nsrc/wp2hugo $ make build_hugo_manager\n...\n```\n\n```bash\nsrc/wp2hugo $ ./bin/hugomanager\nA tool for managing Hugo sites e.g. adding URL suggestions, generating site status summary etc.\n\nUsage:\n  hugomanager [command]\n\nAvailable Commands:\n  analyze-backlinks                     Analyzes backlinks and shows good quality backlinks\n  completion                            Generate the autocompletion script for the specified shell\n  help                                  Help about any command\n  make-absolute-internal-links-relative Converts all the absolute internal links to relative links\n  move-post-next-to-attachments         Move markdown blog posts with attachments to a single directory\n  shrink-audio-files                    Shrinks all audio files to be below a certain bitrate\n  shrink-images                         Shrinks all images to be below a certain width/height\n  sitesummary                           Print site stats (e.g. number of posts, number of drafts etc.)\n  suggest-description                   Suggests description for all the posts that are missing a description in the front matter\n  suggest-image-alt                     Suggests image alt text for all the images if missing\n  suggest-url                           Suggests URLs for all the pending/future posts that are missing a URL\n  version                               Print the version number of HugoManager\n\nFlags:\n  -a, --author string   author name for copyright attribution (default \"YOUR NAME\")\n      --config string   config file (default is $HOME/.cobra.yaml)\n  -h, --help            help for hugomanager\n      --viper           use Viper for configuration (default true)\n\nUse \"hugomanager [command] --help\" for more information about a command.\n```\n\nFeel free to send a Pull request if you migrated your website using `wp2hugo`\n\n### Note\n\n1. To migrate comments, use [Remark42](https://remark42.com/docs/backup/migration/)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashishb%2Fwp2hugo","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fashishb%2Fwp2hugo","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fashishb%2Fwp2hugo/lists"}