I'm getting into Jekyll in a big way and would like to use it as a general front-end development platform, but am running up against the limitations of the Liquid templating language, specifically its difference to Django templating.
I discovered the liquid-inheritance gem, which adds the all-important Extends and Block syntax from Django. This blog post extends the gem further to suit Jekyll's file system:
http://www.sameratiani.com/2011/10/22/get-jekyll-working-with-liquid-inheritance.html
The problem is that it doesn't appear to implement blocks in exactly the same way Django does, which essentially renders the gem useless.
I have two jekyll "layouts" called - for the sake of understanding - parent.html and child.html. Neither of these contain YAML sections.
Parent
<html>
{% block foo %} {% endblock %}
</html>
Child
{% extends _layouts/parent.html %}
{% block foo %}
<div>
Bar comes next:
{% block bar %} {% endblock %}
</div>
{% endblock %}
And then I have a jekyll page which includes a YAML section thus:
---
title: test
---
{% extends _layouts/child.html %}
{% block bar %}My title is {{ page.title }} {% endblock %}
What I'd expect:
<html>
<div>
Bar comes next:
My title is test
</div>
</html>
What I get:
<html>
<div>
Bar comes next:
</div>
</html>My title is test
It seems something is failing to treat the blocks in mypage.html as being eligible for insertion into the suitable places of parent/child, although it's clearly still doing something.
I'm not a ruby developer and am reasonably new to Jekyll, so I need help identifying what part of this stack is failing. The liquid-inheritance issues on github suggest others are experiencing this block nesting problem: https://github.com/danwrong/liquid-inheritance/issues/3
I've tried several of the forks of liquid-inheritance, many of which apparently fix that problem regex, but none seem to solve this.
Is what i'm tring to do fundamentally impossible? It seems like I'm at least 85% of the way there and the final bit needs fixing.
I'm not sure this is ever going to work within Jekyll. I might be wrong, but here's my reasoning:
Each page is rendered out using do_layout in https://github.com/mojombo/jekyll/blob/master/lib/jekyll/convertible.rb
This works recursively - it processes the content of the page, then processes the page's layout, then that layout's layout and so on and so forth, passing the YAML variables up the chain (so they're always available in parent templates as {{ page.whatever}}).
This means that the only things which get passed up are the YAML values, and whatever the value of 'content' is after it has been processed by Liquid. I don't know how it is done elsewhere, but that seems incompatible with the idea of blocks, as they'd require you to pass up the two blocks separately.
Fundamentally, it seems to me that the issue is that Jekyll already has a simple form of inheritance - via the "layout" attribute that you can give to a layout. Fundamentally, I think that this is compatible with liquid-templating.
All that said, I'm not sure that you've exhausted the limits of using YAML, _includes, and template logic. If you're at the point of putting Django style blocks into your content, why not just do something like this:
Content:
---
title: some title
secondary_content: |
Here is some *secondary* content that will be [markdownified](http://example.com).
It can run to multiple lines and include
* Lists
* Good things
* Etc
---
And here is the main content, as per usual
Template:
<html>
<article>
<h1>{{ page.title }}</h1>
{{ content }}
</article>
<aside>
{{ page.secondary_content | markdownify}}
</aside>
If you wanted to keep your templates clean, and have different content for different types of pages, you could use various includes:
Template:
<aside>
{% include sidebar_negotiation.html %}
</aside>
_includes/sidebar_negotiation.html:
{% if page.type = 'foo' %}
{% include sidebar_foo.html %}
{% else if page.type = 'bar' %}
{% include sidebar_bar.html %}
{% endif %}
And then put your page type specific stuff in those files. Obviously you could include it directly, but it is probably nice to abstract it out. Those includes will get all of the variables in the YAML.
If none of this is a win, you could always try Hyde: http://hyde.github.com/ which is written in Python, uses Jinja2 (basically Django templates++), and does the same sort of thing.
Related
I have a website that consists out of a few 'slides'. Each has a fixed structure, used by some scripts, but variable content. I'm hosting it on github and am now trying to use Jekyll to make it easier to add new slides.
I already have each slide in a different html file, which I include in the main page: {% include_relative _slides/about.html %}. Now I'm trying to make it a markdown file, and I wanted to use front matter to make a layout that each slide's file could use. I can include a markdown file, and get it to render by doing:
{% capture myInclude %}{% include_relative _slides/test.md %}{% endcapture %}
{{ myInclude | markdownify }}
However, when I add a front-matter block to it with a layout defined in it, the layout doesn't get applied. It just gets rendered as a horizontal line (for the first ---) and then "layout: slide title: Test Slide —" in plain text.
Is there any way to fix this? Or perhaps a better way to break up my index.html and the slides in it?
Thanks a lot!
Note: Sorry if this was asked before, I Googled everything I could imagine it would be called.
I found something that works for me. I divided my template in two parts, the part above the content, and the part under it. Then in the file I include, there are two includes as well, one at the top and one at the bottom.
So my 'slide' files look like this:
{% include slide_start.html title="About" image="images/about.jpg" %}
... the content of the slide ...
{% include slide_end.html %}
As you can see, in the first include I give some parameters, these will be filled in and can be accessed with the liquid tags {{ include.something }}.
My slide_start.html looks like:
<div class="slide">
<div class="header">
<span>{{ include.title }}</span><!-- no whitespace
--><img src="{{ include.image }}" alt="{{ include.title }}"/>
</div>
<div class="content" markdown="1">
the slide_end.html is just two closing div tags.
You're trying to mix the page/post and the include strategies.
Page/post have a front matter and are decorated with a template, which can itself be decorated. `mypage.html -> layout: page -> layout: default.
Includes are included in page/post but they are only code parts. They cannot be decorated with a template.
You will have to choose.
Take a lool at https://github.com/shower/jekyller this can be helpfull.
On my blog that is powered by GitHub Pages, I'm trying to make it easy to include code snippets in my blog posts. For this, I have created code-snippet.html in the _includes-directory:
<pre><code>{% include {{include.file}} %}</code></pre>
To include a code snippet in a blog post, I use the following code:
Code snippet: {% include code-snippet.html file="snippets/MyPost/MySnippet.cs" %}
However, the content of the file _includes/snippets/MyPost/MySnippet.cs does not get included. If I output {{include.file}} in code-snippet.html I can see that the parameter is passed in correctly, but if I try to include it, I get nothing.
That's a good question. Here is my two cents.
Here, I took the example of your _posts/2012-11-16-idisposable.html post.
Storing code snippets
As code is part of the post's content I logically move it to the _posts folder. Storing it in the _includes folder is not so good as this is a template folder.
Let's copy the idisposable/TryFinallyDispose.cs.html from _includes/code-snippets to _posts/_code or anything you want.
As the code is stored in an underscored folder (_code), it will not be processed as is by Jekyll. We will just 'include' it in our posts.
Note : code snippet can be saved as code.cs
As we will use highligting from Jekyll dependancies (see below), we just rework code snippet by, removing <pre> and <code>.
It becomes :
var x = new X(); // X is a class that implements IDisposable
try
{
// do something with x
}
finally
{
x.Dispose();
}
Displaying code
Jekyll offers various ways to highlight code (markdown, pygments, rouge, ..). Here I demonstrate the pygments way, but it's up to you to explore other solutions.
The base template will be (_includes/code-snippet-csharp.html):
{% capture filePath %}_code/{{include.file}}{% endcapture %}
{% highlight csharp %}
{% include_relative {{filePath}} %}
{% endhighlight %}
note: one drawback here, in the {% highlight csharp %}, code name is hardcoded. I found no way to pass the language to the highlight tag as a variable. If you want to use multiple languages, you'll need to duplicate the include template as code-snippet-csharp.html, code-snippet-js.html, ...
Styling code
In order to beautify our code, we need an extra css file. The basic one is here, but there is many more.
Style is saved as assets/syntax.css and included in _layouts/default.hmtl :
<link rel="stylesheet" href="{{site.baseUrl}}assets/syntax.css">
And it can also be included in your sass process.
Including code in posts
We now just have to call our code in _posts/2012-11-16-idisposable.html.
{% include code-snippets/idisposable/TryFinallyDispose.cs.html %}
Is replaced by :
{% include code-snippet-csharp.html file="idisposable/TryFinallyDispose.cs.html" %}
Result
Better content structure and a nicely highlighted code !
You can include code like this
~~~
{% include snippets/MyPost/MySnippet.cs %}
~~~
In Jekyll, is there any way to access the rendered content of a post from another page?
Here's the scenario: Suppose I wanted to create a blog index page listing a bunch of posts. Each post uses a different layout (text, photo, tweet, etc). Is there a way to get Jekyll to render each post with the layout specified inside of that post and then hand me the rendered content so that I can put it into a summary page?
(I'm 97% sure I saw this exact question asked and answered somewhere here on Stack Overflow, but I cannot for the life of me find it. If anyone could point me to it, I would be most grateful! Of course, original solutions are also appreciated!)
(Edited to make it clear that I want dynamic access to rendered content. Not after the fact in the _sites directory, but while building the site.)
post.layoutis the layout of one post, it's default is post
So, i think, you can do this
{% for post in site.posts %}
{% if post.layout == 'layout1' %}
do something, such as put it into an array ...
{% else if post.layout == 'layout2' %} // here 'else if' may not correct liquid syntax
do something else
{% endif %}
{% endfor %}
I'm implementing a documentation using Sphinx (https://github.com/fridge-project/dbal-docs) & would like to override the html page of a specific document. My interest is to override all directory indexes to not only show a simple ul.
I have read the Sphinx documentation but I don't find something interesting about my issue... Does someone know a workaround?
For the record, this solution is much more a hack than a solution but for now, I don't find something better...
First, of all you need to understand my workaround is based on the theming. In your doc, you use a theme (the default one or a custom one) but anyway, you use a theme. This theme is divided in different part (page, toc, ...) which can be individually overridden. This override can be done at different level: the theme itself or in the custom template directory of the project (by default _templates) (configurable in the conf.py).
My workaround is to override the page.html template in the _templates dir which represents all pages in your documentation. In this template, you have access to the pagename (relative doc path of each file). Knowing that, you can make some conditional check in this template to detect if this is a file you want to override & then override it. If it is not a file which need to be overridden, simply fallback on the default behavior:
{% extends "layout.html" %}
{% block body %}
{% if pagename == 'index' %}
{% include 'custom/index.html' %}
{% else %}
{{ body }}
{% endif %}
{% endblock %}
As explain, it really sounds like a hack...
One should be able to use a variable to define the template to extend from.
In that way it might be less of a 'hack'. And you have full control about the generated output(not only the body block).
layout.html:
{% extends meta.page_template|default('basic/page.html') %}
And in your index.rst you use then page-level metadata:
index.rst:
:page_template: custom/index.html
<your normal index.rst content>
I have a basic layout page template:
---
layout: default
---
<header class="sidebar">
{{ page.title }}
</header>
<section class="content">
{{ content }}
</section>
My pages that use this as the page template are just Markdown that gets put into the <section> block.
I'm looking for a way to keep all my page content in one file but have it so I can define separate content that gets put into the <header> tag from the page template.
Is there any way to do this and keep all the page's content in one file?
You can do so by defining the content you wish to be separate and reused in the _includes/ directory.
You would then include it by calling for example: {% include file.ext %} to include the of the file name _includes/file.ext (almost as if you just copy and pasted it in).
See section pertaining to the _includes in the Jekyll documentation here.
The YAML Front Matter can be used to directly store additional content for the page. This is done by creating custom key/value variables. The layout/template uses liquid tags to check to see if the secondary content is available. If so, it gets output. Otherwise, the section is skipped.
Here's an example of a layout template that checks to see if a custom variable called myvar1 is set:
---
layout: default
---
<header class="sidebar">
<h2>{{ page.title }}</h2>
{% if page.myvar1 %}
<p>Secondary content here: {{ page.myvar1 }}</p>
{% endif %}
</header>
<section class="content">
{{ content }}
</section>
Note: To match your original example, this layout file calls a parent "default" layout. For this example, the above is in a layout file called "_layouts/nested_layout.html".
To use the new slot, a myvar1 variable is added to the front matter, like this:
---
layout: nested_layout
title: This is the post test layout
myvar1: More here <strong>including bold text</strong>.
---
And here is the page content: The quick brown fox jumps over the lazy dog.
When that page is processed, the secondary content will show up. If you create another page that doesn't have myvar1, nothing will be rendered at that part of the template.
You can add as many custom variables to your pages as necessary. The values can include HTML as shown in this example. (It works for me in Jekyll 0.11.2.) If you have a lot of code that you want to add (instead of something that easily fits on one line), or if you want to have the same content available to turn on/off for multiple pages, you can use the custom variable as a flag. Then, in the {% if %} tag, you would call an include if the value is set.