A simple Blog Example
For a primer on how to use foonoo, let's work through a simple blogging example. In addition to being an introduction, this tutorial will also going to provide some useful information about the internal workings of foonoo.
It is worth noting that a blogging example is also a good start for anyone interested in working with foonoo. After all, static site generators have always been staple of the personal blogging community—and if you've read this far, you're most likely interested in blogging with foonoo.
Initializing a Blog Directory
As already stated, foonoo builds sites by relying on dedicated site generators. When it comes to blogs, foonoo can rely on a built in blog
generator. This generator reads its input from a specially formatted source directory and writes its outputs as a static blog website.
The requirement of a special source directory means the first step in creating a blog is to initialize a "source" directory with the required file structure. To do this, switch to an empty directory and execute:
foonoo create blog
Once executed, this command creates a site.yml
file, which contains the the configuration details of the site and three other directories: _foonoo
, posts
, and pages
.
As its name suggests, the _foonoo
directory is required by the foonoo core; it is used internally by foonoo and every foonoo site will have one. Generally, it contains site meta-data, cached information, and it’s also where you can put your images, themes and other related assets.
The posts
and pages
directories, on the other hand, are required for the blog
generator. Those directories are used to hold the raw text files for individual blog posts and any additional stand alone pages you may create.
Testing your blog
With the initial directory structure in place, we can generate the HTML code for our first blog by executing foonoo generate
in the blog directory.
This command should create an output_site
directory containing the HTML code for your blog site. If successful, it should produce output similar to what is below:
Found 1 site in "/home/ekow/blog/"
Writing all outputs to "/home/ekow/blog/output_site/"
Generating blog site from "/home/ekow/blog/"
- Rendering content for /home/ekow/blog/output_site/index.html
- Rendering content for /home/ekow/blog/output_site/posts.html
- Writing content to /home/ekow/blog/output_site/index.html
- Writing content to /home/ekow/blog/output_site/posts.html
- Copying images from /home/ekow/blog/_foonoo/images to /home/ekow/blog/output_site/images
Total build time: 0.13s
At this point, you can open the output_site
directory and manually view the index.html
file, or you can additionally execute foonoo serve
on the command line to start a web server on http:////localhost:7000, through which you could access your blog.
Customizing Your Blog
You may have noticed that your blog currently has a default foonoo title. To change this, open the generated site.yml
file and modify the title to whatever you want. For the purposes of this tutorial, we can choose a title "My First Foonoo Blog." When it comes to changing your title, remeber to keep your title text in quotes and escape any special characters in the configuration file appropriately (as per the requirements of the YAML standards).
Writing Content
Now that your blog is named, you can start adding content. There are two main types of content you can add to blogs: pages
and posts
. For blogs, you must put periodic posts in the posts
directory, and fixed pages must be placed in the pages
directory. In the next few sections we are going to be looking at how to create pages and posts.
Pages
Let's start with adding pages to out blog. Assuming we wanted to create an "About" page to tell visitors what our blog contains, we can create an about.md
file in our pages
directory. In this file we can put the following content:
# About this Blog
Hello everyone! Welcome to our lovely little website. This is just an
example to show how pages can be incorporated to foonoo blogs.
After this page is added, we should have an about.html
file generated in our output_site
directory. Following this template, we can add any fixed page to our blog. You can use pages to store anything from lists of projects to privacy policies and resumes.
Posts
For posts, we can follow the same approach used with pages, as described above. This time however, instead of the pages
directory, we will place posts in the posts
directory. Also, post files must have a name that conforms with the format YYYY-MM-DD-post-id.md
. Here, YYYY
corresponds to the year, MM
corresponds to the month, DD
corresponds to the day, and the post-id
can be a unique ID for the post (typically the title of the post, containing only underscores and hyphens).
To illustrate this, let's create a simple welcome post for our blog. We can name this file as 2022-12-07-welcome-to-my-blog.md
and place it in the posts
directory. The content of this file could look something as shown below:
---
title: Welcome To My Blog
---
# Welcome!
Welcome to my little blog. If you are seeing this post, then my
installation of foonoo was succesful. Hopefully, we can progress to
learn more about how foonoo works.
Next steps
This short example was meant to provide a feel of how foonoo could be used. In the next sections we will look at the specific way in which content can be written for foonoo, and we will further look at the different site generators—including the blog generator—in more detail.