Ideas and bugs on MarkDownBlog

This article is only here as a reminder of what needs to be done next and what improvements I need to do on MarkDownBlog. This article will be edited as soon as I do something or an idea shows up in my mind.

I'm currently trying to figure out what are the most important parts I should do first. Some things are trivial to do, some are not and require a large refactoring of the application. For example, the migration to postgresql requires some work on the server part, even if it doesn't change the code (thanks SQLAlchemy :D).

Note : This is just a list and not a promise or anything like that. I can't guarantee that I'll find the time to do all those things.

There are several ways of asking me for a feature :

  • On Github, open a pull request asking for a feature.
  • Connect to irc on freenode and query and join #markdownblog

Last Updates

A list of the last changes to the platform

  • Blog description is now parsed as markdown.
  • Provide logs for the admin of the blog. (Raw nginx logs for now, need to work on a smarter system)
  • Changing the markdown engine from Misaka to Mistune.
  • Centered images.
  • Support MathJax.

Currently Doing

Things I'm currently working on.

  • Email Setup
    • Setup Postfix (Done, thanks haplo)
    • Email validation system (In progress)

Next Tasks

Things I intend to do next.

  • Easier way to find articles
    • Page of all articles written by a user. (user.markdownblog.com/all won't collide because of the 5 char minimum in the title + date)
    • Tag system. (To find relevent content on all blogs/a single blog)
    • Integrate Whoosh for search on all blogs/a single blog)
  • Create the FAQ page.
  • Per-article settings
    • Work in progress : Only the author can see the article and can decide to push it.
    • Contains MathJax : Determines whether or not to include the MathJax js lib in the page.
    • Image aligment : Left, right, centered, will be used to determine where to place the images in the article.

Carado's requests

Because carado can have his own part, because he writes articles. Unlike others.

  • View counter on articles.

To Do

Things I need to do. Later. At one point. Things that are written in bold are important things.

  • Search engine using Elasticsearch (or Whoosh which is better integrated with SQLAlchemy)
  • Migrate to Postgres
  • Add a blog profile page (with full info on the author)
  • Manage articles with uuid instead of date + slug (Or is that even a good idea ? Who knows. Need some feedback about that.)
  • UI
    • Translate the UI English and French (use the HTTP Header or the settings) with Flask-Babel
    • Refactor the explore page (carousel of recently registered users, etc...)
    • Collapsible blog info (slide right and left, hiding the panel)
    • Themes ?
    • Blog font chooser ?
  • Outside of the WebApp
    • Create a go program (with a config file) that can send articles with an input file written in markdown (make source code and binaries available)
  • Admin Interface - will see that later, requires the per-article setting stuff and other things
    • Create the admin interface with some roles available.
    • Admin can do whatever he wants
    • Anyone should be able to flag an article as inapropriate (if logged in)
    • If the blog or the article is marked as private, disable the inapropriate button ?
    • Moderators could delete an article with at least 5 inaproriate flags.
  • Tutorial
    • Create a tutorial about the UI (Intro.js)


Things that are crossed are things I won't do. There might or might not be an explanation next to the crossed entry.

  • Add a favicon.
  • README and LICENSE on GitHub.
  • Create a Rest API.
  • Implement Disqus for the comment thing.
  • Improve user settings : Linkedin, Github, G+, Twitter.
  • Changing the password.
  • Curses UI to read articles in a terminal Source Code + Binary (Go)
  • Fix background to be displayed on the per-article page when background is public.
  • Remember me option on login.
  • Fill the "Last Login" field in the DB on login.
  • WYSIWYG Editor Won't do. It kind of break the site's philosophy, plus there is a preview button.
  • Preview current markdown while editing.
  • User option to decide if the blog should be public or not. Meaning : Can the blog appear on the "Explore" page or not.
  • Fix contact email, point to the github repo.
  • Create a tutorial on how to write markdown.
  • Background
    • Ability to change the background per user (only for user).
    • Ability to change the background per blog (public).
    • Customizable layout (background-repeat for small images).
    • Change the default background picture (too heavy). Converted from png to jgp. Done. (thanks nado)
  • UI
    • Pagination (blog/ blog/article/)
    • Make the pagination a user setting. Activate / Deactivate and number of posts per-page should be customizable.
    • Collapsible articles ? Or shorten the content and display full on article page ?
    • Higher textarea and disable resizing.
    • Add tooltips on mutliple buttons (toggle raw markdown for example).
    • Make the tooltip thing a user setting ? Can't really remember what I meant here. But it would imply a large refactoring.
    • Put the notifications on the left of the screen (so it appears under the blog description and is more visible).
    • Error on forms should not be on the same line than the label of the said field.
    • Fix the table display.
    • User setting to select a syntax highlighter color palette.
05-02-2015 11:35 by depado

Syntax Highlighter

One of the main issue I had with the markdown interpreter Misaka was that there is actually only a few examples online on how to define a custom block renderer. Here is how I managed this.

Using pygments allows to syntax highlight many languages. When there is no language defined, it is rendered without any CSS classes or inline styles (which gives the colors to the keywords, operators, etc...).

# -*- coding: utf-8 -*-

import misaka
from misaka import HtmlRenderer, SmartyPants
from pygments import highlight
from pygments.lexers import get_lexer_by_name
from pygments.formatters.html import HtmlFormatter

class HighlighterRenderer(HtmlRenderer, SmartyPants):

    def block_code(self, text, lang):
        has_syntax_highlite = False
        if not lang:
            lang = 'text'
            lexer = get_lexer_by_name(lang, stripall=True)
            if lang != 'text':
                has_syntax_highlite = True
            lexer = get_lexer_by_name('text', stripall=True)

        formatter = HtmlFormatter()
        return "{open_block}{formatted}{close_block}".format(
            open_block="<div class='code-highlight'>" if has_syntax_highlite else '',
            formatted=highlight(text, lexer, formatter),
            close_block="</div>" if has_syntax_highlite else ''

    def table(self, header, body):
        return "<table class='table table-bordered table-hover'>" + header + body + "</table>"

markdown_renderer = misaka.Markdown(
    HighlighterRenderer(flags=misaka.HTML_ESCAPE | misaka.HTML_HARD_WRAP | misaka.HTML_SAFELINK),

Now this renderer is bootstrap-compliant. Meaning for examples that tables will be displayed using bootstrap and not raw html tables. Even though the code is quite simple it's really efficient. I ran some benchmarking on the edit and new article page. The ajax request for the preview takes a total time of 4ms. Isn't this a really efficient parser ? Additionnaly, before, it was only used to render blog posts. Now the markdown_renderer is available app-wide, allowing me to perform some markdown processing on any kind of data and not only on articles content.

The syntax highlighting system using pygments generates HTML. Now the "easiest" part to add colors is to tell the HtmlFormatter to create inline-style. The advantages of that technique is that you directly have the right colors in your generated HTML, no need to include some additionnal stylesheet. Though this advantage is also a disadvantage. This GitHub Repository contains several CSS files that you can include to create additional style. That allows customization. Plus the usage of inline-style can multiply the size of the generated html (because there is no re-usability of the generated inline-styles).

Click on the eye icon on the top-right border of this post to look at the raw markdown post. That will give you an example of the syntax accepted by this parser.