turblog.py
==========

Static blog generator from markdown files.

## What is it again?

It's a simple script that takes your markdown files and converts them to HTML and CSS only blog. No backend, no JS. Pure bliss.

## Why, tho?

I been rewriting my blog base so much, and I never was satisfied. First I made my whole blogging platform in PHP 5. Then I did what I did right now,
but in PHP 5 again. But it was in PHP and was server-side. I didn't want that.

Then I made blogging platform on django, but the deploy and updates were painful. I didn't like that.

Blogs are supposed to be simple text + images, no? Why bother with all of that? Just write markdown, run `python turblog.py`, copy the html to your
server and voila, that is that.

## Who is this for?

This is not intended for non-programming users. The script doesn't allow for much customization, it is designed to read a folder structure with your posts and pages in .md, CSS and images (and if you want to, JavaScript) and convert that to another folder filled with html and your static stuff.

It serves one simple purpose and that's that.

## How do I install it?

It's just one file. A script. It's not a library. Not a framework. Just a script.

It does have dependencies though:

* python-markdown2 - for parsing markdown;
* Pygments - for colorful code in your blog;
* PyRSS2Gen - for RSS feed generation.

Use `pip` or whatever else to install those.

## So, wait, I just execute it?


One of the first thing you'll see inside the script are a bunch of vars that serve as minimal config. 


```Python
# ==================================
# Main config
# ==================================

PROJECT_DIR  = "project"
POSTS_DIR    = "posts"
PAGES_DIR    = "pages"
TEMPLATE_DIR = "templates"
WWW_DIR      = "www"
COPY_DIRS    = ["css", "img"]

SITE_TITLE   = "blog"
SITE_URL     = "http://localhost/"
SITE_DESC    = "my blog"
SITE_AUTHOR  = "your-name-here"
BASE_URL     = "/blog"
MAX_POSTS_IN_INDEX = 3
```

The script expects a _project_ directory where all the other relevant directories reside.

* _posts_ directory are where you store the markdown blog posts, the script parses them and creates proper folder structure (based on date) and puts them there;
* _pages_ are where you store your static pages. Stuff like _"About me"_ and such;
* _templates_ is where you store your html templates. More on them later;
* _www_ is the directory the script will put the built site;
* You can put any static stuff that doesn't need processing into `COPY_DIRS` list, like CSS and images.

Then there are some basic configs that will effect links in the templates and RSS feed. I think they are self-explanatory.

`MAX_POSTS_IN_INDEX` decided how many posts are shown on main page before the link to archive is shown.

### Templates

Templates are pretty simple and easy. Write anything between `<%` and `%>`, and you can replace it in code using `template(text, dict)` function. The dict is a key-value container where key is what you wrote inside the tag, and value has the text to replace it with. You can have multiple tags with the same name, they all will be replaced with the same text.

Example:

_my_template.html_:
```HTML
<p><%TEXT%></p>
```

_turblog.py_:
```Python
...

vals = {"TEXT": "My text goes here!"}
html = template(my_template_text, vals)

...
```

And that will produce, you guessed it:

```HTML
<p>My text goes here!<p>
```

### Posts

Posts have a bit of special syntax. First two lines are reserved. 1st line is the title of the post, 2nd is the date in `YYYY-MM-DD` format.
After that feel free to write your markdown.

### Pages

Pages too have special syntax. First two lines are reserved. 1st is the title of the page, 2nd is the type.

There are 3 types supported:

* markdown - the page will be parsed with markdown, and html written.
* html - the page will be written as is.
* link - the body of the page is assumed to be pre-sanitized link. And will be just passed as is.


## Contact

If you really want to tell me something, shoot me an email at: `dweller 4t cabin d0t digital`

Made by me, dweller (C) 2018-2022

Licensed under MIT license (see LICENSE for full text)