Static-site generators

Static-site generators like Hugo, Jekyll, Middleman, Next.js, and VuePress are all popular platforms for building static sites quickly. This guide walks through how to configure each of these generators to build for deployment to IPFS.

Check out the IPFS Deploy GitHub Action Guide to automate the deployment of your static site to IPFS using GitHub Actions.

Next.js

When deploying a Next.js site to IPFS, make sure that your site uses Static Site Generation (SSG) (opens new window), so that it can be built as a static site (opens new window).

1. First, ensure your next.config.js file has the following settings:

module.exports = {
  output: 'export', // Enables static exports
  trailingSlash: true // Required for IPFS gateway compatibility
}

Key points about the configuration:

• output: "export" tells Next.js to generate a static site
• trailingSlash: true ensures routing works when the site is served from IPFS gateways (which require an index.html file per route)

To build your Next.js site:

npx next build

The static site will be generated in the ./out directory.

Important Considerations

• Only use Static Site Generation (SSG) (opens new window) features.
• Server-side features like getServerSideProps or API routes won't work.
• Dynamic routes need to be pre-rendered at build time.
• Use relative URLs for all internal links.

Hugo

Refer to Hugo's Quick Start (opens new window) to install and set up your project.

In config.toml add relativeURLs and set it to true.

relativeURLs=true

Build static pages

hugo -D

Output will be in ./public/ directory by default. Upload the public folder to IPFS.

VuePress

Refer to VuePress' Getting Started (opens new window) to install and set up your project.

To build a static site:

vuepress build

Output will be in ./.vuepress/dist directory by default.

Use a command to convert a static site to only use relative URLs. In this example, we'll be using all-relative (opens new window)

cd .vuepress/dist/
npx all-relative

Upload the dist folder to IPFS.

Middleman

Refer the Middleman's Installation (opens new window) guide to install Ruby and Middleman.

1. Enable relative links and disable index file strip in your project's config.rb file:

   set :relative_links, true
   set :strip_index_file, false
   

Links generated by the link_to helper or by Markdown will become relative.

1. Build your static site:

   middleman build
   

   Middleman will output your site to the ./build folder.

2. Upload the build folder to IPFS.

Jekyll

Refer to Jekyll's Installation (opens new window) guide to install Ruby and Jekyll.

Refer to Jekyll's Quickstart (opens new window) to set up your project.

To build a static site:

jekyll build

Output will be in ./_site by default.

Use a command to convert a static site to only use relative URLs. In this example, we'll be using all-relative (opens new window)

cd _site/
npx all-relative

Upload the _site folder to IPFS.

WordPress

While WordPress is not a static site generator, it is possible to turn it into a static website allowing deployment to IPFS.

There are several plugins available to help you generate a static version of your WordPress site:

• WP2Static (opens new window)
• Simply Static (opens new window)