Quickstart¶
PBlog
is constructed on two main parts.
The first one is a flask extension in the flask_pblog module.
The second one contains the command line interface and core functionalities
in the pblog module.
Install PBlog¶
For now, PBlog is not published on PyPI, so it must be installed from source.
$ python setup.py install
Building the web server¶
The next step is to build a Flask application that will use the flask_blog
extension.
# file app.py
from os import path
from flask import Flask
from flask_sqlalchemy import SQLAlchemy
import flask_pblog
from flask_pblog.storage import Storage
from markdown import Markdown
# the directory of the current file
BASE_PATH = path.dirname(path.abspath(__file__)à)
# default PBlog css is stored there.
static_folder = path.join(path.dirname(flask_pblog.__file__), 'static')
# resource_path is the directory where we will store posts related files
# (images, source code, ...)
# see the *Markdown Posts / Local resources* for more information on this
resource_path = path.join(BASE_PATH, 'resources')
app = Flask(__name__, static_folder=static_folder)
app.config['SECRET_KEY'] = 'not-so-secret'
# database configuration
app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///' + path.join(BASE_PATH, 'db.sqlite')
# PBlog configuration
app.config['PBLOG_CONTRIBUTORS'] = {
'admin': 'pbkdf2:sha256:.....',
}
# where are stored posts related resources
app.config['PBLOG_RESOURCES_PATH'] = resource_path
# we need a markdown instance to create or update posts
md = Markdown(
extensions={
'markdown_extra.meta',
'markdown_extra.summary',
'markdown_extra.resource_path',
},
extensions_config={
'markdown_extra': {
'root_path': '/resources/',
},
},
)
# create the SQLAlchemy extesions
db = SQLAlchemy(app)
flask_pblog.PBlog(app, storage=Storage(session=db.session), markdown=md)
if __name__ == '__main__':
app.run()
Before you can run the the web server, the database must be created. From a python terminal:
from app import db
from flask_pblog.models import Base
Base.metadata.create_all(bind=db.engine)
The resource directory (defined in PGLOG_RESOURCES_PATH) must also be created. The server can now be started with
$ mkdir resources
$ python app.py
User are stored in memory. There aren’t any session management on the server. Users are only here to allow to upload some new posts from the client application.
PBlog is shipped with some default static files (only CSS). You can use your own static files or use the provided ones as shown in the example.
Using the command line client¶
Once the web server is up and running, the command line part of the application can be setup.
A pblog.ini
file must be created.
This file is used to tell pblog where we will want to upload new posts.
When using P-Blog
command line interface, a pblog.ini
file must be
present in the current directory.
The url to the blog and the username to authenticate with will be stored in it. Several environment (PBlog instances) can be configured independently.
[pblog]
; using [pblog:default] section as default environment
env = default
[pblog:default]
username = admin
url = http://blog.example.org/
[pblog:testing]
username = admin
url = http://127.0.0.1:8000/blog/
wsgi = blog.app
You can then start writing some blog posts. Lets setup every posts in their own directory, so we will have the following structure:
app.py
/resources/
pblog.ini
/blog/
first-post/
first-post.md
imgs/
fancy-image.png
The blog post will have the following content:
---
title: This is the first blog post
topic: Testing
---
[summary]
This is my first blog post.
![A great picture](imgs/fancy-image.png)
We can link some images to the post.
Any resources that need to be shipped with the post must be defined by a path relative to the markdown file. Those path will be resolved when publishing the post.
When we are ready, we can publish the post.
$ python -mpblog publish blog/first-post/first-post.md
See Markdown Posts to see how to write posts.
$ python -mpblog --help
Usage: __main__.py [OPTIONS] COMMAND [ARGS]...
Options:
-i, --ini TEXT pblog.ini path
-e, --env TEXT pblog environment
-a, --app run local app
--help Show this message and exit.
Commands:
publish
The env
option can be used to select the environment to load.
The ini
option sets the pblog.ini
file to load.
The wsgi
option sets a local wsgi application that can be started in
background by using the -a
flag of the command line interface.