This section will guide you through all the steps required to get a blohg-based blog up and running.
Make sure that you read all the content available here in order to know how to use blohg properly.
blohg will install a script called blohg for you. This script is capable to create a new Mercurial repository, using the default template and/or run the development server. It will be your main tool to interact with blohg.
To create a new repository, type:
$ blohg initrepo --repo-path my_blohg
Where my_blohg is the directory where the new repository will be created.
Make sure that the directory doesn’t exists, or is empty, before try to initialize the repository.
When the repository is created, do the initial commit:
$ hg commit -Am 'initial commit'
The repository structure is pretty easy to understand:
my_blohg/
|-- config.yaml
|-- content
| |-- about.rst
| |-- attachments
| | `-- mercurial.png
| `-- post
| |-- example-post.rst
| `-- lorem-ipsum.rst
|-- static
| `-- screen.css
`-- templates
|-- base.html
|-- post_list.html
`-- posts.html
| Directory/File | Description |
|---|---|
| config.yaml | The main configuration file. |
| content/ | The main content directory (for pages, posts and attachments). |
| content/post/ | The posts directory. Any content stored here is handled as blog post, instead of page. |
| content/attachments/ | The attachments directory. Any images or static files used in posts and pages should be here. |
| static/ | The directory with static files used in the templates, like CSS files or images. |
| templates/ | The directory with the Jinja2 templates. |
You can heavily change the behavior of blohg by changing some configuration options.
These are the built-in configuration options for the config.yaml file:
| Configuration option | Description | Default value |
|---|---|---|
| POSTS_PER_PAGE | Number of posts per page. Used by the posts pagination and the Atom feeds. | 10 |
| AUTHOR | The name of the main author of the blog. Used by the Atom feeds. | 'Your Name Here' |
| TAGLINE | A short tagline for the blog. | 'Your cool tagline' |
| TITLE | The title of the blog, without HTML tags. | 'Your title' |
| TITLE_HTML | The title of the blog, with HTML tags. | 'Your HTML title' |
| CONTENT_DIR | The directory of the repository where the content is stored. | content |
| TEMPLATES_DIR | The directory of the repository where the templates are stored. | templates |
| STATIC_DIR | The directory of the repository where the static files are stored. | static |
| ATTACHMENT_DIR | The directory of the repository where the attachments are stored. | content/attachments |
| ROBOTS_TXT | Enable robots.txt, to prevent search engines to index source files, a.k.a. don’t follow “View Source” hiperlinks. | True |
| SHOW_RST_SOURCE | Enable the view that shows the reStructured text source of your posts and pages. | True |
| POST_EXT | The extension of your post/page files. | '.rst' |
The default values are used if the given configuration key is ommited (or commented out) from the config.yaml file.
If you look at the my_blohg directory you’ll see a templates directory. It stores some Jinja2 templates that are used by blohg.
Take a look at the Jinja2 documentation to learn how it works. The default templates provided by blohg initrepo are a good start point.
These are the blohg built-in variables globally available for your templates:
| Variable | Description |
|---|---|
| version | A string with the current version. |
| is_post | A function with one argument, that returns True if the given argument is a the path of a post. |
| current_path | A string with the path of the current page/post. |
| active_page | A string with the first piece of the current path, useful to highlight the menu link for the current page. |
| tags | An iterable with all the available tags, ordered alphabetically. |
| config | A dictionary with all the configuration options. |
These are the built-in templates, that can be overrided from the repository:
Template for the 404 error page. You don’t need to override it on your Mercurial repository if you don’t want to customize something.
Template with some Jinja2 blocks that can be used by your custom templates. If you don’t want to use the custom blocks just don’t call them from the templates, and they will be ignored. You don’t need to override this file in the repository.
These are the custom blocks available:
| Type | Block name | Where to place |
|---|---|---|
| Disqus | disqus_header | inside the html header, in base.html. |
| disqus_post | after the post contents, in posts.html. | |
| disqus_footer | at the end of base.html, before the </body> tag. | |
| Pagination | pagination | at the end of posts.html, inside the main div. There’s a CSS class, called pagination, to help you when changing the style. |
Disqus support depends on the a DISQUS configuration variable, that should contain the value of the Disqus identifier of your blog. To get it, create an account at http://disqus.com/.
The main template file, it’s mandatory to be provided in the Mercurial repository. This template is inherited by all the other ones.
Template used by the views that show partial/full content of pages and posts.
It’s inherited by _posts.html and can make use of his Jinja2 blocks.
Local variables available for this tempalte:
| Variable | Description |
|---|---|
| title | A string with the page/post title. |
| posts | A list with all the posts (Metadata objects). |
| full_content | A boolean that enable display full content of posts and not just the abstracts. |
| pagination | A dictionary with 2 items (num_pages: number of pages, and current current page), used by the pagination block. |
| tag | A list of strings with tag identifiers, used by the view that list posts by tags. |
Template for the page with the listing of blog posts, without content, just the name, the date and the link.
Local variables available for this template:
| Variable | Description |
|---|---|
| title | A string with the page title (usually “Posts”). |
| posts | A list with all the posts (Metadata objects). |
The static/ directory will store your static files, like CSS and images. You should avoid store big files inside the Mercurial repository.
blohg will disallow search engines from index your source files (/source/ path), creating a robots.txt file in the root of your blohg instance. If you isn’t running blohg from the root of your domain, you should make the requests pointing to /robots.txt redirect to /path-to-your-blohg/robots.txt in your webserver configuration.
If you don’t want this robots.txt file, you can just add the following content to your config.yaml file:
ROBOTS_TXT: False
blohg enables a /source/ endpoint by default, that shows the reStructuredText source for any post/page of the blog. You can disable it by setting the SHOW_RST_SOURCE configuration parameter to False. It will raise a 404 error.
You can use blohg to manage your “static” website, without the concept of blog posts. Actually the default setup of blohg is already pretty much like a CMS, but the initial page is a list of posts (or abstracts of posts), and you don’t want it if you don’t have blog posts at all.
You can use a static page as the initial page. You just need to save the text file as content/index.rst on your repository.
You can also use a static initial page for your blog, if you want, but you’ll need to create a menu link pointing to the page with the list of posts. You can use the views.posts endpoint to build it:
<a href="{{ url_for('views.posts') }}">Posts</a>
Each tag will have its own HTML page with all the posts:
It is also possible to combine multiple tags and get a HTML page: