23 April, 2019
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!
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.
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?
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.
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
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:
Our new website is now being served on localhost:4000.
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!
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!
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 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:
(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!