Skip to content

Quick start

Jump to bottom
Tobi edited this page Apr 8, 2021 · 18 revisions

⚠️ This tutorial assumes you are working in a Unix environment with raptr added to your path. See installation. The tutorial will still work in terms of shown raptr commands, but system commands may differ. It's also recommended to have Git installed.

Chapters

To use raptr, you need two things: a project directory and a theme.

Inside the project directory, you can create and edit drafts, add and manage themes and also configure your installed themes to a certain extend. A theme is how your blog will look once you published it using the publish command, but more on that later.

Creating a new project

To start, let's create a new project using the --new command (short: -n) in your terminal:

$ raptr --new my-awesome-blog

or

$ raptr -n my-awesome-blog

Cool, now we got us a project!

Adding a theme

The next step is to add a theme. In this case, we use igor. The easiest method of adding igor to our project is using git:

$ cd my-awesome-blog
$ git init
$ git submodule add https://github.com/CodeF0x/igor themes/igor

You can of course also download igor as a zip archive and extract the contents to themes/igor inside your project directory. You can download igor here.

Now that we created a project directory and added a cool looking theme, it's to time tell raptr to actually use that theme. To do that, create a file named config.toml in the root of your newly created project directory:

$ touch config.toml

⚠️ touch won't work on a Windows system. Use echo "" > config.toml instead or create the file via Windows Explorer.

Using the GUI of your operating system or your favorite text editor works too of course. Speaking of which, let's add the theme to our config.toml file by adding the theme key:

theme = "igor"

This line will tell raptr to load and parse the igor theme, whose files are located at themes/igor inside our project directory.

⚠️ It is very important to save your config.toml file UTF-8 encoded or raptr can't work with it!

Customizing our blog

To fill our blog (landing page) with life, we need to add some more keys to our config.toml file:

# seo
copyright = "" # who ever has a copyright on your blog, probably you
description = "" # a short description of what readers can expect from your blog
keywords = [""] # a list of keywords your blog is about

# customization
index_title = "" # the text that's displayed in the browsers tab
home_title = "" # a big headline on the index page
home_sub_title = "" # a smaller sub-headline on the index page
custom_string_one = "" # this can be whatever you want it to be. maybe tell your readers a little about yourself?
custom_string_two = "" # maybe your readers also want to know why you started this blog?

To give you some ideas, consider this example:

# seo
copyright = "Tobias \"CodeF0x\" Oettl"
description = "A small blog where I put anything that comes to my mind and seems noteworthy!"
keywords = ["programming", "music", "gaming"]

# customization
index_title = "Welcome to my cyberspace!"
home_title = "Hi, I'm CodeF0x!"
home_sub_title = "Software engineer, metalhead, and passionate gamer"
custom_string_one = "Because I sometimes have the desire to write some nonsense on the internet, I started this blog!"
custom_string_two = "I'll be talking about my favorite video games, this one time a CocaCola (TM) bottle exploded right in my bed and more!"

Adding drafts

Because a blog without any actual posts would be boring, let's add a new draft using the --draft (short: -d) command:

raptr --draft hello-world.md

or

raptr -d hello-world.md

You now have a draft file named hello-world.md in the drafts directory inside your project directory.

When you open the draft file in your favorite text editor, you will notice a non-markdown text block like this:

+++
title = ""
date = "2021-02-09 21:53:12.862513 +01:00"

# seo
author = ""
author_link = ""
keywords = []
description = ""
draft = true
+++

It might look like a lot, but it's pretty straight forward. Let's iterate through it real quick:

  • title is, well, the title of your post
  • date is the date you generated the draft. Do not change this, unless you now what you are doing!
  • author is the author of the post
  • author_link can be any valid URL. Maybe it's the author's Instagram? -- you can leave it empty if you want
  • keywords are the SEO keyword of this specific post. They can differ from the keywords of other post or even keywords in config.toml
  • description is a small summary of what this post is about -- also used for SEO
  • draft is very important. It tells raptr if it should render this draft. If draft is set to true like now, raptr won't create an HTML file for this draft. If you are done writing your post, set draft to false

Okay, let's get to the actual post.

Simply write your markdown below the pluses (+++) and tell the world what's on your mind! For example, your draft file could look like this:

+++
title = "Why I created yet another blogging engine"
date = "2021-02-09 21:53:12.862513 +01:00"

# seo
author = "CodeF0x"
author_link = "https://codef0x.dev"
keywords = ["rust", "blogging"]
description = "In this post, I'll explain in depth why I think the world needs a new blogging engine."
draft = true
+++

# Why I created yet another blogging engine

Well, it's quite *simple*:

* I wanted something minimal and very fast to set up
* and I was really bored during the weekends

This leads us to...

If you're done editing your draft and you think it's ready for the internet, set draft to false.

⚠️ Don't forget to save all your drafts UTF-8 encoded as well!

Publishing your blog

Alright, now it's time for our blog to be seen by millions of people every day!

To get the HTML files of our blog, use the --publish command (short: -p) of raptr:

$ raptr --publish

or

$ raptr -p

raptr will now require a few seconds to create a complete website with the index page, your blog posts, and all required assets. Once it is done, you will find all files inside the output directory of your project directory.

If you want raptr to use a different output directory, for example, your already set-up web server, you can specify the directory where raptr should put the files:

$ raptr --publish /var/www/html/my-blog

or

$ raptr -p /var/www/html/my-blog

If the target directory does not exist, raptr will attempt to create it and its parent directories.

Conclusion

Now you know everything about the daily usage of raptr.

More articles on how to create your own theme and other thrilling topics will be added soon. Until that, have fun!

Clone this wiki locally