Home ZMediumToJekyll



Move your Medium posts to a Jekyll blog and keep them in sync in the future.

This tool can help you move your Medium posts to a Jekyll blog and keep them in sync in the future.

It will automatically download your posts from Medium, convert them to Markdown, and upload them to your repository, check out my blog for online demo zhgchg.li .

One-time setting, Lifetime enjoying❤️

Powered by ZMediumToMarkdown .

If you only want to create a backup or auto-sync of your Medium posts, you can use the GitHub Action directly by following the instructions in this Wiki .


  • You can follow along with each step of this process by watching the following video tutorial

How to move your Medium blog to Jekyll blog

  1. Click the green button Use this template located above and select Create a new repository.
  2. Repo Owner could be an organization or username.
  3. Enter the Repository Name, which usually uses your GitHub Username/Organization Name and ends with .github.io, for example, my organization name is zhgchgli then it’ll be zhgchgli.github.io.
  4. Select the public repository option, and then click on Create repository from template.
  5. Grant access to GitHub Actions by going to the Settings tab in your GitHub repository, selecting Actions -> General, and finding the Workflow permissions section, then, select Read and write permissions, and click on Save to save the changes.

*If you choose a different Repository Name, the GitHub page will be https://username.github.io/Repository Name instead of https://username.github.io/, and you will need to fill in the baseurl field in _config.yml with your Repository Name.

*If you are using an organization and cannot enable Read and Write permissions in the repository settings, please refer to the organization settings page and enable it there.

First-time run

  1. Please refer to the configuration information in the section below and make sure to specify your Medium username in the _zmediumtomarkdown.yml file.
  2. ⌛️ Please wait for the Automatic Build and pages-build-deployment GitHub actions to finish before making any further changes.
  3. Then, you can manually run the ZMediumToMarkdown GitHub action by going to the Actions tab in your GitHub repository, selecting the ZMediumToMarkdown action, clicking on the Run workflow button, and selecting the main branch.
  4. ⌛️ Please wait for the action to download and convert all Medium posts from the specified username, and commit the posts to your repository.
  5. ⌛️ Please wait for the Automatic Build and pages-build-deployment actions will also need to finish before making any further changes, and that they will start automatically once the ZMediumToMarkdown action has completed.
  6. Go to the Settings section of your GitHub repository and select Pages. In the Branch field, select gh-pages, and leave /(root) selected as the default. Click Save, you can also find the URL for your GitHub page at the top of the page.
  7. ⌛️ Please wait for the Pages build and deployment action to finish.
  8. 🎉 After all actions are completed, you can visit your xxx.github.io page to verify that the results are correct. Congratulations! 🎉

*To avoid expected Git conflicts or unexpected errors, please follow the steps carefully and in order, and be patient while waiting for each action to complete.

*Note that the first time running may take longer.

*If you open the URL and notice that something is wrong, such as the web style being missing, please ensure that your configuration in the _config.yml file is correct.

*Please refer to the ‘Things to Know’ and ‘Troubleshooting’ sections below for more information.


Site Setting


medium_username: # enter your username on Medium.com

Please specify your Medium username for automatic download and syncing of your posts.

_config.yml & jekyll setting

For more information, please refer to jekyll-theme-chirpy or jekyllrb .

Github Action


You can configure the time interval for syncing in ./.github/workflows/ZMediumToMarkdown.yml .

The default time interval for syncing is once per day.

You can also manually run the ZMediumToMarkdown action by going to the Actions tab in your GitHub repository, selecting the ZMediumToMarkdown action, clicking on the Run workflow button, and selecting the main branch.


All content downloaded using ZMediumToMarkdown, including but not limited to articles, images, and videos, are subject to copyright laws and belong to their respective owners. ZMediumToMarkdown does not claim ownership of any content downloaded using this tool.

Downloading and using copyrighted content without the owner’s permission may be illegal and may result in legal action. ZMediumToMarkdown does not condone or support copyright infringement and will not be held responsible for any misuse of this tool.

Users of ZMediumToMarkdown are solely responsible for ensuring that they have the necessary permissions and rights to download and use any content obtained using this tool. ZMediumToMarkdown is not responsible for any legal issues that may arise from the misuse of this tool.

By using ZMediumToMarkdown, users acknowledge and agree to comply with all applicable copyright laws and regulations.


My GitHub page keeps presenting a 404 error or doesn’t update with the latest posts.

  • Please make sure you have followed the setup steps above in order.
  • Wait for all GitHub actions to finish, including the Pages build and deployment and Automatic Build actions, you can check the progress on the Actions tab.
  • Make sure you have the correct settings selected in Settings -> Pages.

Things to know

  • The ZMediumToMarkdown GitHub Action for syncing Medium posts will automatically run every day by default, and you can also manually trigger it on the GitHub Actions page or adjust the sync frequency as needed.
  • Every commit and post change will trigger the Automatic Build & Pages build and deployment action. Please wait for this action to finish before checking the final result.
  • You can create your own Markdown posts in the _posts directory by naming the file as YYYY-MM-DD-POSTNAME and recommend using lowercase file names.
  • You can include images and other resources in the /assets directory.
  • Also, if you would like to remove the ZMediumToMarkdown watermark located at the bottom of the post, you may do so. I don’t mind.
  • You can edit the Ruby file at tools/optimize_markdown.rb and uncomment lines 10–12. This will automatically remove the ZMediumToMarkdown watermark at the end of all posts during Jekyll build time.
  • Since ZMediumToMarkdown is not an official tool and Medium does not provide a public API for it, I cannot guarantee that the parser target will not change in the future. However, I have tried to test it for as many cases as possible. If you encounter any rendering errors or Jekyll build errors, please feel free to create an issue and I will fix them as soon as possible.

If you have any questions or comments, feel free to contact me.




This article was first published in Traditional Chinese on Medium ➡️ View Here

This post is licensed under CC BY 4.0 by the author.

The Craft of Building a Handmade HTML Parser

Travelogue 2023 Kyoto, Osaka, Kobe 8-Day Free Trip