Eager to get started? Then follow instructions step by step and embrace the power of Holocron.
Holocron is distributed as a Python package and is available on PyPI. It
requires Python 3.3+ and could be installed through the
$ [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
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.
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
|-- 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:
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.
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.
- 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
$content/a/b/page.mdownwill be available under the
A sample post. Each file that could be parsed by one of enabled converters and has
YEAR/MONTH/DAY/FILEpath 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.
- 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 -
- 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
$ 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:
so you can share this folder with any web-server.