Quickstart

Eager to get started? Then follow instructions step by step and embrace the power of Holocron.

Installation

Holocron is distributed as a Python package and is available on PyPI. It requires Python 3.3+ and could be installed through the pip tool:

$ [sudo] pip3 install holocron

Create a New Site

Creating a new site with Holocron is a very simple task. Begin by creating a directory for your new site and switching to that directory.

$ mkdir -p ~/devel/mysite
$ cd ~/devel/mysite

Finish by initializing it with a blog skeleton.

$ holocron init

Simple, right? :)

Preview Your Site

Well, you have a directory with a Holocron-powered site, and it contains one post and one page. Sounds good, ha? Let’s preview them in your browser.

$ holocron serve

The serve command starts a development server and prints to a terminal an http address where your blog is available. In other words, you should just copy-paste this address from the terminal to a browser and that’s it.

But the serve command does even more - it watches for content changes and rebuilds blog if there’re any. That means you don’t need to run anything in order to preview latest changes, all you have to do is to refresh a web-page in your browser.

Manage Your Content

In order to understand how to manage Holocron’s content, let’s take a look at the blog skeleton and example content which was generated by init command.

|-- 2014
|   `-- 04
|       `-- 20
|           `-- holocron.mdown
|-- images
|   `-- young_obiWan.png
|-- about.mdown
`-- _config.yml

Ok, we have four files in the directory, each one represents a separate type. Here’s the key:

_config.yml

A Holocron’s configuration file. You can change here blog title, content paths, enabled extensions, theme options, etc. This is what Holocron’s looking for by default, you can pass another filename if you want.

Note

The filename starts with underscore because Holocron do not process any content started with underscore (_) or dot (.), and we don’t want to see this file in the output directory.

about.mdown
A sample page. Each file that could be parsed by one of enabled converters is considered as either Page or Post. Both Page and Post documents preserve their relative paths to the content directory and will be available under almost the same path (a file extension will be stripped) in the output directory. I.e. $content/a/b/page.mdown will be available under the $host/a/b/page/ url.
2014/04/20/holocron.mdown

A sample post. Each file that could be parsed by one of enabled converters and has YEAR/MONTH/DAY/FILE path pattern is considered a post.

It’s processed using almost the same rules as a page, but unlike last one it will appear in the feed and on the index page.

images/young_obiWan.png
A sample static file. Each file that could not be parsed by one of active converters is considered as a static file. It doesn’t mean it won’t be processed at all, but will be copied into output directory “As Is”.

What all that means? That means

  • If you want to add new page, just drop it anywhere in the content folder in the supported format (default: Markdown & reStructuredText).
  • If you want to add new post, just drop it anywhere in the content folder but use directory structure with date representation - YEAR/MONTH/DAY.
  • If you want to add new picture, just drop it anywhere in the content folder, and it will be copied to output directory “As Is”, so you can link to it without hesitation.

Compile Your Site

There’s a short command for compiling your site into a set of HTML files, and it’s called build.

$ holocron build

By default Holocron’s build procedure includes:

  • compiling content into HTML;
  • generating Atom feed;
  • generating sitemap.xml;
  • generating index page (with all posts)
  • generating index pages by tags (posts by tags)

All results will be placed in the output directory (default: _output), so you can share this folder with any web-server.