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

4 min

read

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!

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

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.

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/second-post.md 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…

themes/landscape/source/css/_partial/article.styl

… 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. It can be easily 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!

Estimate your project





Thanks

Thank you!

Your message has been sent. We’ll get back to you in 24 hours.

Back to page
24h

We’ll get back to you in 24 hours

to address your needs as quick as possible.

Estimation

We’ll prepare an estimation of the project

describing the team compostition, timeline and costs.

Code review

We’ll perform a free code review

if you already have an existing system or a part of it.

Our work was featured in:

Tech Crunch
Forbes
Business Insider

Aplikujesz do

The Software House

Aplikuj teraz

wyślij CV na adres: [email protected]

CopiedTekst skopiowany!

Nie zapomnij dodać klauzuli:

Kopiuj do schowka Copy

Jakie będą kolejne kroki?

Phone

Rozmowa telefoniczna

Krótka rozmowa o twoim doświadczeniu,
umiejętnościach i oczekiwaniach.

Test task

Zadanie testowe

Praktyczne zadanie sprawdzające dokładnie
poziom twoich umiejętności.

Meeting

Spotkanie w biurze

Rozmowa w biurze The Software House,
pozwalająca nam się lepiej poznać.

Response 200

Response 200

Ostateczna odpowiedź i propozycja
finansowa (w ciągu kilku dni od spotkania).

spinner