Gatsby vs Hexo vs VuePress: Choosing the Right Static Site Generator

All three tools — gatsby, hexo, and vuepress — generate static HTML from source files, but they target different workflows, architectures, and developer preferences. Let’s compare them through real engineering lenses.

🧱 Core Architecture: Framework Coupling and Data Flow

gatsby is deeply integrated with React and uses GraphQL as its central data orchestration layer. Every piece of content — whether from Markdown, a CMS, or an API — must be queried via GraphQL in your components.

// gatsby: Querying Markdown data with GraphQL
import { graphql } from "gatsby";

export const query = graphql`
  query {
    allMarkdownRemark {
      edges {
        node {
          frontmatter { title }
          html
        }
      }
    }
  }
`;

export default function Blog({ data }) {
  return (
    <div>
      {data.allMarkdownRemark.edges.map(({ node }) => (
        <article key={node.frontmatter.title} dangerouslySetInnerHTML={{ __html: node.html }} />
      ))}
    </div>
  );
}

hexo uses a template engine (like EJS, Pug, or Swig) and treats Markdown as standalone content. There’s no centralized data layer — instead, you access post metadata directly in templates via global variables like page or site.

<!-- hexo: Using EJS template with post data -->
<% page.posts.each(function(post){ %>
  <article>
    <h2><%- post.title %></h2>
    <%- post.content %>
  </article>
<% }) %>

vuepress blends Vue components directly into Markdown files. You write .md files that can include Vue single-file components, and the entire site is rendered using Vue’s reactivity system during build.

<!-- vuepress: Markdown with embedded Vue component -->
# My Docs

Here's a live demo:

<MyComponent :count="5" />

<script setup>
import MyComponent from './components/MyComponent.vue'
</script>

📂 Project Structure and Configuration

gatsby uses a gatsby-config.js file to declare plugins and options. Its structure is flexible but can become complex as plugins multiply.

// gatsby-config.js
module.exports = {
  plugins: [
    `gatsby-plugin-react-helmet`,
    {
      resolve: `gatsby-source-filesystem`,
      options: { path: `${__dirname}/src/posts`, name: "posts" }
    },
    `gatsby-transformer-remark`
  ]
};

hexo relies on _config.yml (or .yml) for global settings. Themes and plugins are configured separately, often requiring manual file overrides.

# _config.yml
theme: landscape

plugins:
  - hexo-generator-feed
  - hexo-prism-plugin

vuepress uses a docs/.vuepress/config.js (or .ts) file. It supports TypeScript out of the box and organizes theme customization under .vuepress/theme/.

// docs/.vuepress/config.js
export default {
  title: 'My Docs',
  themeConfig: {
    nav: [{ text: 'Guide', link: '/guide/' }],
    sidebar: ['/guide/']
  }
}

⚙️ Build Performance and Scalability

gatsby offers incremental builds (via Gatsby Cloud or premium features) and image optimization out of the box, but full builds can slow down with large content sets due to GraphQL schema generation.

// gatsby: Optimized image
import { GatsbyImage, getImage } from "gatsby-plugin-image";

function Hero({ data }) {
  const image = getImage(data.file);
  return <GatsbyImage image={image} alt="Hero" />;
}

hexo is extremely fast for small to medium sites because it avoids heavy transformation layers. However, it lacks built-in asset optimization — you must add plugins manually.

# hexo: Install image optimization plugin
npm install hexo-asset-image --save

vuepress rebuilds only changed pages in dev mode (HMR), but production builds process all Markdown. It doesn’t include image optimization by default, though you can extend the Webpack config.

// .vuepress/config.js: Extend Webpack for image handling
export default {
  configureWebpack: {
    module: {
      rules: [
        {
          test: /\.(png|jpe?g|gif)$/i,
          use: ['file-loader']
        }
      ]
    }
  }
}

🧩 Extensibility and Ecosystem

gatsby has the richest plugin ecosystem (e.g., gatsby-source-contentful, gatsby-plugin-mdx). Plugins can hook into every stage of the build lifecycle.

// gatsby: Using MDX for JSX in Markdown
{
  resolve: `gatsby-plugin-mdx`,
  options: {
    extensions: [`.mdx`, `.md`]
  }
}

hexo uses npm packages as plugins, but the ecosystem is smaller and less standardized. Many themes require manual tweaking.

// hexo: Custom plugin example (in scripts/)
hexo.extend.filter.register('after_post_render', function(data) {
  // Modify post content
});

vuepress allows you to write custom Vue components, theme enhancements, and Webpack extensions. Plugins are less common than in Gatsby, but Vue composables offer powerful logic reuse.

// .vuepress/components/Counter.vue
<template>
  <button @click="count++">{{ count }}</button>
</template>

<script setup>
import { ref } from 'vue';
const count = ref(0);
</script>

📚 Best-Fit Use Cases

• gatsby: Enterprise marketing sites, hybrid apps needing SSR fallbacks, content hubs pulling from multiple sources (CMS + GitHub + APIs).
• hexo: Personal blogs, simple project pages, legacy documentation sites where minimal setup is critical.
• vuepress: Open-source library docs, internal developer portals, any technical guide needing live examples powered by Vue.

⚠️ Important Notes on Maintenance

As of 2024, all three projects are actively maintained:

• gatsby continues major releases with focus on performance and cloud integration.
• hexo receives regular updates, though its core hasn’t changed significantly in years.
• vuepress v2 (based on Vue 3) is stable and recommended; avoid v1 for new projects.

None are deprecated, but evaluate based on team expertise and long-term needs.

🆚 Summary: Key Differences

💡 Final Recommendation

• If your team knows React and needs scalable content architecture, go with gatsby.
• If you want zero-config blogging and don’t need interactivity, hexo gets you there fastest.
• If you’re writing developer docs and love Vue, vuepress gives you the smoothest blend of content and code.

Choose not just by features, but by how well the tool aligns with your team’s daily workflow and long-term maintenance strategy.