Getting started
Before you can generate your blog using Kart, you first need to write the templates and the static files. Fortunately kart provides a way to generate this files automatically. First of all you have to install an additional package called cookiecutter.
pip install cookiecutter
Then you can generate all the files with this command
cookiecutter gl:giacomocaironi/Kart --directory="cookiecutters/blog"
This has generated some folders. The one that interests one is the collections folder.
Write your first post
In the collections directory there is a subdirectory called posts. As the name suggests it will contain all the posts of your blog. Create a new markdown file in it. The name of the file doesn't have to be the same as the title, but be aware that the filename will be used to create the slug of the post.
The first thing you want to do when you write a post is choosing the title. It is also useful to add other type of information about the post, such as the date, the description or whether it is a draft or not. This type of information is called metadata. You can add metadata by using front matters. Front matter is a snippet of YAML which sits between two triple-dashed lines at the top of a file.
---
title: My first post
date: YYYY-MM-DD
description: This is my first post
draft: False
---
The title and date fields are mandatory, while the others are completely optional. If you set the draft flag to true the blog will not be processed.
Everything you write under the front matter is just markdown. It will be converted to html by kart and displayed in the finished site. Try writing some posts before moving to the next section.
---
title: My first post
date: YYYY-MM-DD
description: This is my first post
draft: False
---
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Build the site
It's finally the time to build the site. There are two ways to do it.
The first one simply generate the site but it does not display it automatically in the browser. Move to the root directory and type in the shell:
python main.py build
This will build your site in the _site folder. If you want to view it in the browser you can use a simple web server. With python you can create it by simpy typing in the browser(you must first move to the _site directory):
python -m http.server
This is useful when you want to push your static site to your production environment but it is not very useful for editing the site. For this there is another command
python main.py serve
This will create a development server that will autoreload when you change any file. It is very useful when modifying the templates. You can also specify which port to bind to using the -p option
python main.py serve -p 4000
You can then search in the browser 'localhost:' and the port you have chosen to see the blog.
Adding tags
Sometimes you want to group your posts in a way that posts talking about the same subject can be found together. To achieve this we use tags.
Grouping posts is a very difficult job for static site generators, especially when you want to paginate them. Kart does all of this automatically. Moreover the templates generated by the quickstart command automatically adapt to tags, so the only thing we have to do is create some tags and tell the posts which tag do they have.
First of all we have to crate a tag. Go to the taxonomies/tags folder and create a markdown file. The filename is very important, as Kart will use to identify the tag across the site.
---
name: First Tag
---
The only metadata required is the name of the tag, and it can be different from the filename. The name of the file is used internally by Kart, while the tag name will be displayed to the user. So keep the filename short and readable, while the tag name can be longer and more descriptive.
We can also write the description of the tag under the front matter. This data could be used by custom templates, for example in the page where all the posts tagged in the same way are listed. Achieving this with other static site generators is not always straightforward. Create some tags before moving to the next section.
Tag a post
Now that we have created a tag we need to assign it to some posts. Go to the posts folder and open a file.
---
title: My first post
date: YYYY-MM-DD
description: This is my first post
draft: False
---
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
Now we can add some tags with the following syntax
---
title: My first post
date: YYYY-MM-DD
description: This is my first post
draft: False
tags:
- first_tag
- second_tag
---
Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
It is very important that the name of the tag in the tags list is NOT the name of the tag, but instead its filename. This way we can have tag names with spaces, while having filenames with spaces is not recommended.
Look at the site in your browser. For each tag there is a page that will list every posts with the tag.
Create pages
In Kart, a page is a kind of content which desn't belong to a group(or it doesn't fit in a collection). An example of a page in a normal site is the contct or about page.
The process of writing pages is very similar to the one about posts. You have to create a markdown file in the pages folder
---
title: About
---
This is the about page
The only data which is required in the front matter is the title
Because of the templates created automatically in the navbar there will be a link for every page you write
The root folder
In this tutorial we haven't told about the "root" folder, which was created by the quickstart command. Every file you put in this folder will be copied in the _site directory. It is useful for files such as favicons or CNAMES(for custom domains). If you want to add this type of files now is the time to do it.
Publish your site
When you want to build your site for publishing it you must use a different command:
python main.py build
Now you can push your _site folder to your favourite host. You can find more information about it in the step by step guide
Where to go
You have only scratched the surface of what Kart is capable to offer. If you want how to create custom templates and mappers, to personalize the look of the site, you can look at the step by step tutorial section. You will learn how to pass custom data to your templates and how to use the jinja2 template engine to modify the look of your site as you like.