Reasons for Migration, Operation Scripts, Common Error Fixes…

Migrating from NotionNext to Zola

Recently, I migrated my personal website from NotionNext to Zola and would like to share some thoughts.

Background

Experience with NotionNext

Previously, I used NotionNext to host my personal blog. Notion is indeed an excellent text editing tool—writing articles is smooth, and having a cross-platform app for instant writing and syncing is very convenient. As long as you set an article to “published,” it appears on the frontend.

Reasons for Migration

As the number of articles grew, managing them with NotionNext became less efficient for me. The Notion database became large and difficult to maintain. Since I have frontend development experience, managing the frontend with CSS in static site generators like Zola is more intuitive and convenient than editing in Notion. For better article management, content customization, and multilingual support, I decided to migrate my blog to Zola.

Migration Process

Installing Zola

The official Zola documentation is clear and straightforward. Setting up a local Zola development environment usually takes just one command. Note: If you need support for Chinese/Japanese, you must build a custom binary index; otherwise, site search won’t work for those languages. For local installation and GitHub Actions compilation with Chinese support, see my article: Enable Chinese Indexing in Zola.

My setup is local Windows development with deployment on GitHub Pages. The blog code is in repository A, deployed via GitHub Actions to public repository B, and then pushed to GitHub Pages.

    flowchart TD
    %% ---- Nodes ----
    subgraph Local["Local Development"]
        W[Windows Local Development]
    end

    subgraph GitHub["GitHub"]
        A[Repo A（Blog Source Code）]
        GA[GitHub Actions（CI/CD）]
        B[Repo B（Static Site Files）]
        GP[GitHub Pages（Online Hosting）]
    end

    U[Visitor / Browser]

    %% ---- Connections ----
    W  -->|git push| A
    A  -->|trigger workflow| GA
    GA -->|build static files → push| B
    B  -->|gh-pages branch| GP
    U  -->|HTTPS request| GP

    %% ---- Styles (optional) ----
    classDef local  fill:#e5e5e5,stroke:#888,stroke-width:1px,rx:6,ry:6;
    classDef repo   fill:#fef6e4,stroke:#a9a9a9,stroke-width:1px,rx:6,ry:6;
    classDef action fill:#cbf3f0,stroke:#0096c7,stroke-width:1px,rx:6,ry:6;
    classDef page   fill:#ffd6a5,stroke:#ff8800,stroke-width:1px,rx:6,ry:6;

    class W local;
    class A,B repo;
    class GA action;
    class GP page;

    linkStyle default stroke-width:2px;

Article Structure - Multilingual Support

Normally, your blog can use the following structure:

content/
└── blog/
    ├── 2025-07-01-zola-migration.md
    ├── 2025-06-20-new-feature.md
    └── 2025-05-10-performance-tips.md

However, for multilingual support, you need to create corresponding language files. For example, if your site’s main language is English (en) and you want to support Chinese (zh), create an index.zh.md file for the Chinese version. My structure looks like this:

content/
└── blog/
    ├── 2025-07-01-zola-migration/
    │   ├── index.md
    │   └── index.zh.md
    ├── 2025-06-20-new-feature/
    │   ├── index.md
    │   └── index.zh.md
    └── 2025-05-10-performance-tips/
        ├── index.md
        └── index.zh.md

This way, Zola recognizes both English (default) and Chinese versions under 2025-07-01-zola-migration. If a language version is missing, it won’t cause errors, but the article won’t appear in that language.

Article Migration

Currently, I manually export articles from NotionNext as markdown and then edit them in Zola. In the future, I may consider automating the process from Notion editor to markdown.