Issue #14 resolved

Build crashes when a {#CrashTag} is present in the body of a post

Sergey Astanin
created an issue

This is an example of a post which causes trouble:

---
title: "Crash Tag"
date: 2013-09-26 23:52:58
tags: [ obraz, test ]
layout: post
published: true

---

This will crash the Obraz build process:

    Hello Obraz! Meet a {#CrashTag}!

Try compiling a blog with this post and you'll get this:

    Processing tags...
    Sort and interlink posts...
    Generate pages with YAML front matter...
    Error: Cannot render '_posts/2013-09-26-crash-tag.md': Missing end of comment tag

The problem is due to `{#` sequence in the code block, because it's a
start of Jinja2 comment. Other Jinja2 users have experienced
[the same problem too][same-problem].  The sequence is frequent in
LaTeX code.

It is a valid sequence, and it should be allowed in blog posts. Jinja2
should not see the body of the post as a template. Obraz should quote
such magic sequences automatically if necessary.

[same-problem]: http://rhinocerus.blogspot.it/2012/08/erro-causado-por-hashtag-em-templates.html

Comments (14)

  1. Sergey Astanin reporter

    Relying on Jinja2 for rendering is an implementation detail. It obviously affects templates (representation), but should not affect the content.

    I suppose Jinja2 tags and syntax should not appear within a post (unless it's a post about Jinja2). The only reasonable default is to escape them and render verbatim. Could you name at least one use case where tags within text are necessary? Plugins and normal templates (where Jinja2 tags are ecpected) are enough to do everything I can think of.

    Disadvantages of enabling Jinja2 tags within user's content:

    1) it allows for messy configurations: content is not separated from representation 2) need to escape code-like contents -> need to invent and document escaping rules -> effectively blessing an incompatible markdown dialect 3) switching to a different templating mechanism is going to be more difficult (templating tags in the user content, incompatible md dialect) 3) build errors due to invalid templates are misterious for a writing user (why? what's wrong? how do I fix it?) 3b) it requires all writers to know the templating language (to avoid its syntax they have to learn it first); it goes against use-cases where a writer gets a preconfigured theme/layout, or uses the software as a service

    Advantages of disabling Jinja2 tags in posts:

    1) Any valid Markdown content is rendered as expected. 2) No need to escape or distort the content in any other way. Writers may stick to the conventional Markdown or HTML. 3) Messy configurations are discouraged. 4) It's possible to separate the duty of configuring a blog and creating its design from writing posts. Preconfigured installations and SaaS become possible. 5) Plugins will be used more. They are a more reusable approach for content-aware layout. Il giorno 27/set/2013 19:45, "Andrey Vlasovskikh" <

  2. Sergey Astanin reporter

    Can you suggest a workaround for users who'd like to write about LaTeX or Lua? In particular, how do you post this code verbatim in Obraz:

    \newcommand{\myvec}[1]{\vec{#1}}
    

    That's pretty common. I encountered this problem when trying to convert posts from my older blog to Obraz.

    Any good reason to have Jinja2 template inflation within (mostly) plain-text content?

  3. Sergey Astanin reporter

    It would be a good reasong, if Jinja2 was completely compatible with Liquid, and Obraz was compatible with Jekyll in all other aspects. As it is, migration of any Jekyll blog will likely require changing templates, reimplementing missing plugins etc.

    Is there evidence that Jekyll blogs which use template tags within posts exist? How many of them are likely to switch to Obraz? I doubt they're the main user base for Obraz.

    I can name many reasons why they still render posts with Liquid: laziness, no one cared to file an issue, Jekyll crowd rarely writes about LaTeX... But I don't care what Jekyll does. I need a tool which allows me to concentrate on writing, not on how the tool works. Right now it's a show stopper for me with no workaround.

  4. Andrey Vlasovskikh repo owner

    Jinja2 templates are important not only for templates (inside _layouts), but for regular pages, like doc/index.html in the Obraz sources. Some pages are easier to write in Markdown, like doc/plugins.md. So I am against turning rendering off for a) anything except _layouts, b) Markdown pages. Posts are different, probably you don't need to use templates there often. But it is still useful: consider prefixing your URLs in posts with your site's baseurl.

    What's your opinion on adding an option to the YAML front matter for disabling rendering the contents of a page, just applying a layout template to it?

  5. Sergey Astanin reporter

    Any solution which will allow to disable template expansion for posts, is a valid workaround for me. I'd prefer a global site option in _config.yml over having to insert it in every YAML front matter.

    consider prefixing your URLs in posts with your site's baseurl

    Sounds like a plugin should do it.

  6. Andrey Vlasovskikh repo owner

    I don't like the way Jekyll insists on using Liquid for disabling Liquid via {% raw %}. I would like to introduce a new YAML front matter variable for disabling rendering the page contents. A custom plugin (@processor) could easily put it to all posts via 2 lines of code.

  7. Log in to comment