Back to all blogposts

JavaScript static site generator: let’s build a website from scratch! (1/3)

Andrzej Herok

Andrzej Herok

Operations Manager

Have you heard about static site generators? If you haven’t followed this topic for the past couple of years, the first thing that may be coming to your mind right now is Microsoft Frontpage and a lot of bad code. However, modern static site generators have nothing to do with that. They are sleek, elegant and, most importantly, you can use them to develop a fast and beautiful website/blog and make it possible for a non-technical person to use on an everyday basis. Sounds good? So let’s make a website with a static site generator!

In today’s article, I’m going to show you how to create a website using a JavaScript static site generator tool called Hexo. This is the first part of my tutorial. In the subsequent parts, I’ll tell you more about deploying and managing such websites as well as about making them even more accessible for non-technical users. Let’s get to the point.

See also: Functional programming on frontend

What is a static site generator – introduction to modern static site generators

According to the latest stats, WordPress powers 33,6% of the web (as of April 2019) and is the most commonly used CMS platform of all time. It’s almost a natural choice when it comes to creating a blog or a documentation website. But we’re not average developers, are we? We are destined to make things fancier than others!

As you may have already figured out, we’re going to use a tool commonly known as a static site generator. What is it? In simple words, it’s a tool that, given content and a template, generates static HTML+CSS+JS website.

Seems a bit 1990ish? Well, yeah, the truth is that we’ve already been there. But the tools were different. Content editing won’t require Dreamweaver or Notepad++. We’ll make it a whole lot of more elegant. Let’s delve deeper into the modern static website generator.

Static website – project scope

Before we get to code, let’s describe our target website and define tools we’ll use to accomplish our goal. We’re going to create a blog that has text and images. An inline gallery would also be great.

The whole project can be split into a few parts:

  • the site generator itself – deciding which tool to use to generate the website,
  • making the actual website – content plus template,
  • hosting solution – finding a nice little place that can host our website,
  • editorial flow – figuring out how to ease content management for the masses.

Choosing a JavaScript static site generator

Here’s a task that will be absolutely fundamental for the quality of the end result – let’s find a tool that suits our needs. How to do it?

Check out the StaticGen website – a place which collects information on the latest open-source static site generator tools. There are dozens of tools to choose from, sorted by popularity, programming and templating language, or even a license used. I wanted a pure JavaScript static site generator, which offers clean code, quick setup and satisfying performance. I’ve decided to use a tool named Hexo. Why is that?

Hexo is written entirely in Javascript. It supports custom post types and multiple purpose plugins. In addition, its templating capabilities are similar to WordPress, so we won’t get lost that easily. It also produces clean HTML code without any gibberish inside (HI there, MS Frontpage fans!).

If you’d like something even fancier, you can check out Gatsby, which is a React.js-powered site generator. For VueJS fans, nuxt.js or VuePress will provide similar capabilities and experience.

Hexo installation

First things first – we need to install the hexo command (globally):

npm install hexo-cli -g # yarn global add hexo-cli

Now, we can initialize our new project:

hexo init hexo-gallery

cd hexo-gallery

npm install # yarn install

And that’s it! Our newly created website is almost ready to be served! Just run a command to test it locally:

hexo server

Our new website is now being served on localhost:4000.

Hexo website on a local server

We’re good to go. We can now start writing interesting content and gather visitors!

Creating a blog with Hexo static site generator

After a clean installation, we will only see the “Hello World” post inside. Let’s create a new one. First, let’s run a command (remember to stop the server beforehand):

hexo new "second post"

Now, refresh the page (running the hexo server command again). Voilà! Our newly created content is already there!

Already thinking where our posts are located? They’re inside the source/_posts dir. Open the freshly created file source/_posts/ and edit its contents:

After refreshing the page, the contents will be instantly updated. Magic!

Hexo website updated with new content

As you can see, all posts use the Markdown format. Editing them is quite easy even for people with just a basic grasp of its syntax.

Frontmatter – making static site generators more powerful

The last thing to explain is the intriguing topmost part of the Markdown file. It’s not clean markdown and its contents are not explicitly displayed on the page. This part is called frontmatter – a common way of providing metadata for posts employed static site generators. Can it be used for anything more sophisticated than inserting the post title and date? Of course, it can! In fact, we’ve already used it to attach tags to our post. Just take a look at the bottom of our article – the tags are already there.

Let’s make something less trivial. We’re going to edit the file above as follows:

*In order to see exactly how to write markdown for this, please view the raw version of the gist above.

If we refresh the page, nothing will change. The frontmatter is not visible by default. We still need to update the template to display the images. Let’s make two changes:

In the file: themes/landscape/layout/_partial/article.ejs find the following line:

and put the following block right above it:

Some styling for the images is also necessary. Let’s get to the file…


… and paste the code below at the end of it:

(Don’t mind the Stylus syntax. I’m not a fan of it either, but for the purposes of this tutorial, it’s fine. For your next template, you can use SCSS simply by installing a proper SCSS renderer plugin).

Now, let’s refresh the page and see the magic happen! We’ve created a gallery!

Hexo website and a newly created gallery of images

That’s it! We can now fully utilize our website by adding new posts and galleries.

(It’s high time we make a snapshot of our changes. Let’s commit them to the repository.  Here’s one that I’ve also created.)

Making our static site production-ready (let’s generate html, css and js!)

We’ve created a few posts and run the website in development mode. But we still don’t know how to make it production-ready. At the beginning, we’ve agreed that the final product will be plain old HTML+CSS files. So where are they? The thing is, so far we’ve only been using Hexo in development mode. Let’s generate the final product by issuing a single command:

hexo generate

What happened?

Hexo parsed all markdown posts and generated final HTML files along with CSS and JS inside the public directory. We can now test it by serving the contents of the above dir – let’s run http-server tool:

http-server public/

(Hint: you may not have the http-server tool installed; in this case, run first npm install -g http-server to fix it.)

There it is! We’ve created a static website that’s easily extendable and editable. In just a couple minutes, we succeeded in creating a good-looking and full-featured blog that offers good performance and clean codebase. Site generation with a tool like this is easy. It can be used for a personal blog or even an open-source project documentation (a good example of that is TSH’s very own open-source project Kakunin, which uses another static site generator tool called Docusaurus). But in order to do all that, we also need to deploy it.

And this is exactly what we’re covering in the second part of the tutorial.

On a side note, if you are also interested in developing a dynamic CMS-based website, read our best PHP CMS comparison article published on TSH’s blog a couple of weeks ago. Enjoy!

You may also like

What would you like to do?

    This site is protected by reCAPTCHA and the Google
    Privacy Policy and Terms of Service apply.

    We regard the TSH team as co-founders in our business. The entire team from The Software House has invested an incredible amount of time to truly understand our business, our users and their needs.

    Eyass Shakrah

    Co-Founder of Pet Media Group


    Thank you for your inquiry!

    We'll be back to you shortly to discuss your needs in more detail.