Porting an HTML Site to Gatsby
This guide focuses on the parts of Gatsby that are applicable to a static website. For a more comprehensive walk through Gatsby’s features check out the Gatsby tutorial. By following the example on this page, you will complete the key stages of porting an HTML website to Gatsby and establish your Gatsby development workflow.
Note: This guide can also be used to migrate a section of a site, to be served next to existing files. Pay extra attention to the section on hosting for guidance.
Here is the structure of an example static HTML/CSS website that this guide will walk through porting:
The example site uses global CSS files (
normalize.css); styling structures like Sass architectures or CSS-in-JS can be accommodated but will not be covered here.
Gatsby generates websites and web applications for production through a compilation and build process, and it also has tools optimized for local development. To set up the Gatsby CLI and development environment (if you haven’t already) check out Part Zero of the Gatsby tutorial.
Now that you are set up, you can use the Gatsby and npm CLI tools in your terminal to get this site ported! Make a new project using the Gatsby hello world starter with the following command:
You should now have a folder called
gatsby-site containing a basic Gatsby application. Open the new folder in your code editor and
cd (change directory) into the folder in your terminal to continue:
src folder contains most of the front-end code for the Gatsby site. In the Gatsby build process, every component file in the
src/pages folder will automatically create an HTML page. In your new Gatsby application, the only page created is from the index page component in
Run the development server with
gatsby develop in the command line to see the website in your browser.
You can now visit the page running in your browser at
http://localhost:8000. Hello Gatsby! 👋
index.html from the example site structure above:
In the following sections, you’ll convert this block of HTML into its equivalent code in Gatsby.
static folder of your new Gatsby project, you can see a
favicon.ico file, this is the Gatsby favicon! All files within
static will be served at the root of the app, you can put yours in there and watch it show up in the browser. The other image file in this example,
person.png, should also be moved to the
static folder for later use.
Gatsby’s bundling system negates the need for manual CSS
<link> tags for local CSS. Within the
src/pages/index.js file, before the page component is defined, you can add a line for importing each CSS file. Gatsby will then efficiently deliver the CSS with your site.
Create a folder at
src/styles in the Gatsby project. All the CSS files for the project can be moved into this new folder. Add an
import line for each CSS file to the Gatsby home page:
You might have noticed that the component in
src/pages/index.js doesn’t include
<body>. Gatsby makes a default HTML structure for each page and places the output from
/src/pages/index.js into its body. More
<head> child elements and HTML attributes are added to the output page with the Gatsby Head API.
Now you can place
<main> elements for the existing HTML. Copy over the contents of the
<head> tag: you’ll no longer need the
<link> tags for the CSS files. The Gatsby components must have a single root parent in their code structure so one technique is to add a React Fragment component around them:
Note the mix of components and native HTML elements in the React markup here: this is the JSX templating language, which Gatsby compiles into HTML that browsers can parse and render to users. Further sections of this guide will explain it even more.
Gatsby itself provides a number of core building blocks:
<Link> is one of them. The
<Link> component is imported at the top of the file to use in place of
<a> tags for internal links, with a
to prop instead of the
href attribute. When the site builds,
<Link> produces native HTML anchors with added performance optimizations like prefetching page content before a user activates a link.
Copy over the
<header> element contents, changing
<a> elements to
The contents of the
<main> tag can be copied over from
index.html to your new
index.js file mostly unchanged. Your pasted HTML needs a small change to be valid:
class attributes must be renamed to
className for usage with React, as
Opening the site in a browser again at
Porting a sub-index page
There are 4 pages in the
who section of Taylor’s Tidy Trees for members of Taylor’s tree team. Here is the index page:
The foundational building block for building and styling pages in Gatsby is the
<Layout> component. The
<Layout> component wraps around page content, providing the common structure that appears on all pages. Looking at the
/who/index.html you can see that most of the page is identical. Other than the title of the page, everything except for the contents of the main block is repeated.
Create a folder inside
src, next to
components make a file called
The common elements between the
/who/index.html files can now copied from
src/index.js into the
You can now use the
<Layout> component to create a
src/who/index.js page file:
Who We Are link in
index.js should now work! Now use the
<Layout> component in the
index.js page file too:
Have a check that the
Who We Are link is still working. If not, check that the content is wrapped correctly with the
<Layout> component as shown above.
Porting other pages
Now it’s time for the work to really pay off! Ella’s page is a matter of using your
<Layout> component again and copying in the main content. Don’t forget to change
The other 2
Who We Are pages for Marin and Sam can now be made with a similar structure. Maybe you are even thinking about another component for the Bio Card!
services and the root level HTML files are ported, here is what the finished Gatsby project file structure looks like:
Building & Deploying
With your new Gatsby application taking shape, it’s time to integrate it into your existing HTML website.
Gatsby build step
With all of the pages ported over, you now have a site that mirrors the existing HTML site. Stop the development server if it’s still running; it’s time to run the production build! 🎉
Once a build is complete, the compiled set of files can be found in
Hosting the new website
Once built, the contents of the
public folder are ready to be hosted at the root (
/) of a domain. The files can be deployed in similar ways to how your existing HTML site may have been deployed. The best way to deploy Gatsby sites is Gatsby Cloud.
What about migrating a section of a site? No problem. The Gatsby build output in
/public can be mixed with existing files.
If the Gatsby site is to be hosted at a non-root path, e.g.
example.com/blog, Gatsby needs to be informed so page and asset links in the built output can be prefixed, see the path prefix documentation.
New website file structure
Gatsby can handle images through direct imports to page and component files too! The asset import documentation covers this. There is also gatsby-plugin-image component for even deeper optimizations. Once assets are handled through Gatsby, plugins can be used to optimize their processing and delivery.
The building with components doc has information about why Gatsby uses React component architecture and how it fits into a Gatsby application.
Sourcing content and data is a great next step if you are interested in separating your content from your website code, such as sourcing the site title from
gatsby-config.js with GraphQL and writing content in Markdown.
Gatsby is dedicated to making you feel welcome! Learn more and engage with the community by starting a conversation or contributing yourself. The contributing page has further information and channels where you can get support.