nanosite

tutorial

In this tutorial, we'll make a simple blog from scratch. Along the way, you'll acquire a complete working knowledge of nanosite.

1. Set up site

After you've downloaded nanosite, create a new site as follows:

mkdir MyBlog
cd MyBlog
nanosite

nanosite will prompt you to pick a site title, tagline and author name. You are free to change these later.

2. Start the server

nanosite comes with a development server so you can preview your site as you create it. Start the server by running nanosite serve. Now you can navigate to http://localhost:8000/ in your favorite browser. You'll want to disable caches in your web browser during development, since new files are constantly being updated.

You'll notice that we start out with a blank white page. Time to add some content!

3. Edit the master template

meta/master.tmpl contains the master template, the base HTML code that ends up on every page of your site. You'll notice that right now, it just contains a single line:

{{{ content }}}

This is a template that says to simply output the raw contents of each file. However, we can let templates do more for us than this. Replace master.tmpl with this:

<!DOCTYPE html>
<html>
  <head>
    <title>{{ site.title }}{{ #if title }} - {{ title }}{{ #endif }}</title>
    <link rel="stylesheet" href="{{site.url}}/style.css">
  </head>
  <body>
    <header>
      <h1><a href="{{site.url}}/index.html">{{ site.title }}</h1></a>
      <small>{{ site.tagline }}</small>
    </header>
    <section>
      {{{ content }}}
    </section>
  </body>
</html>

This is the base HTML code that will be copied over to every page in our site. This lets us give each page <html> tags and a consistent header. Notice that templates allow us to access attributes of each page, such as {{ title }} and {{{ content }}}.

{{{ content }}} is central as this is what actually displays the contents of the current page. Note that triple braces are used for attributes containing HTML code.

Learn more about the templating language.

4. Add some style

For some nicer formatting, download this stylesheet: style.css. Put it in the top directory of your site.

During site generation, all files besides HTML and Markdown files are simply copied to their respective positions in the output folder. Learn more: the pipeline.

5. Create macros

meta/macros.py is used to define Python macros, which you can call from templates (like master.tmpl). We'll need some simple date manipulation for our blog, so use nanosite import date to import these functions (you'll have to exit the server with Ctrl+C first). Specifically, we now have access to functions formatDate, which formats a date into a string, and newest, which gives the newest X pages in a directory.

After importing, take a look at macros.py. The key is the use of macro("newest", newest) to connect a template macro name to a corresponding Python function. Learn more about macros.

6. Create a test post

It's time for your first blog post! Create a folder called posts/ in your site directory. Now create posts/my-first-post.md with the following:

title: My first post!

Hello, world! ...

You can now visit http://localhost:8000/posts/my-first-post.html to view your post.

Note that we're creating a plain .md file here, whereas files like index.html+ contain a + in the extension. What's the difference? Use a + when you want templates {{ }} turned on for the page; leave it out if you don't.

7. Create a post template

We'd like to show the title and date of the post along with its contents. So, let's create a "local template" to give specific formatting to each post. Create a file posts/template.tmpl with the following:

<article>
  <small>{{ formatDate date }}</small>
  <h2>{{ title }}</h2>
  {{{ content }}}
</article>

If a template.tmpl file lives in a directory, all the files in the directory will be compiled against this template before going to the master template. This way, you can create a template specific to a group of related pages.

Notice that we call formatDate with the date parameter, an in-built attribute which gives the date of the file being compiled. Furthermore, we use {{ title }} to get the file's title attribute, which we defined on the first line of our post file: title: My first post!.

Visit http://localhost:8000/posts/my-first-post.html again and observe the formatted date and title appear along with the post itself.

Learn more about the site generation pipeline: the pipeline.

8. Show posts on the front page

While individual post pages are nice, what we'd really like is to show a list of newest posts on the front page of our site. Thus, let's edit index.html+:

{{ #for post in newest 5 posts }}
  <article>
    <small>{{ formatDate post.date }}</small>
    <h2><a href="{{site.url}}/{{post.path}}">{{ post.title }}</a></h2>
    {{{ post.content }}}
  </article>
{{ #endfor }}

Notice the #for loop which loops through all items in a collection. In this case, we're iterating through newest 5 posts, a macro call.

Also notice the use of dot syntax to access the date, path, title and content attributes, which are now members of the post object.

Where does variable posts come from? Each file gets a view of the entire site's directory tree, so the posts/ folder gets encoded as a variable called posts. You could even iterate through the posts directly: {{ #for post in posts }}...{{ #endfor }}. Each post has a date and path sub-attribute: post.date and post.path. Learn more about what attributes are available to you: the context.

Create some more posts in posts/. Now open http://localhost:8000/ to check out your new post feed. We've created a complete simple blog!

9. Publish your blog

There are many ways to publish your site. GitHub Pages is one good option. A simple method is to create a GitHub Pages site with the contents of your output/ folder as a repository. If you're more Git-savvy, you may want to use a Git subtree to maintain separate repositories for your project files and your output files.

For this tutorial, we'll use the first option (make a repository out of the output/ folder). After following the GitHub Pages setup instructions, we can make a publish script to automatically push updates to your live site. Add this to meta/publish (meta/publish.bat on Windows):

nanosite clean
nanosite build

pushd output
git add .
git commit -m "autopublish"
git push origin master
popd

We can now publish our site via nanosite publish. Congratulations, your site is live!

Learn more about publishing.

10. Next steps

You can download the completed tutorial project here: My Blog.

The pieces you've used in this project are most of what you'll need in your own site. For a real site, you may want to try nanosite import blog, which contains a ready-made blog and is compatible with custom theme packages.

For detailed information, check out the full documentation.

Go create your dream site!