I'm having some difficulty getting Jekyll to use a particular theme and I think there's something fundamental I'm missing about how {{ content }} works with posts.
So, in a generic Jekyll site, index.html has a layout specified in its front matter. When the site is generated, the layout includes index.html as {{ content }}. It's kind of inverted, where the page specifies the layout and then the layout calls the page, but simple enough.
Posts, on the other hand, are all generated via a file, post.html, which resides in the _layouts folder even though it isn't really a layout. Like index.html it's essentially just a for loop. This is where I'm running into trouble.
Is post.html a required file? Could I rename it story.html?
Why does post.html require a layout in the front matter? The actual post, that is, the markdown that contains the text for said post, also requires a layout in its front mater. Is there a circumstance where post.html would have a different layout than the layout specified in the markdown file?
Edit: one other question. Why is {{ content }} called in multiple places? index.html and the layout file both have {{ content }}. Why doesn't the layout simply {% include %} index.html and let index.html call {{ content }}
I think you largely figured it out by yourself, but I'll still explain it in my own words.
You're right that {{ content }} is the placeholder in the layout file where the content of the actual page will go.
What probably confused you is the fact that you can build a set of nested layout files where one "inherits" from the other, and each layout has its own {{ content }}.
And yes, I didn't find anything about this in the docs, I figured it out by myself or better, by looking at examples.
So here's an example for you.
First, a default layout and a page:
/_layouts/default.html:
<!DOCTYPE html>
<html>
<head>
<title>{{ page.title }}</title>
</head>
<body>
<h1>{{ page.title }}</h1>
{{ content }}
</body>
</html>
/index.md:
---
title: example page
layout: default
---
This is the page content.
The generated HTML will look like this:
<!DOCTYPE html>
<html>
<head>
<title>example page</title>
</head>
<body>
<h1>example page</h1>
<p>This is the page content.</p>
</body>
</html>
Now let's create another layout file that "inherits" from the first one.
You'll probably want to use something like this if you're building a blog with Jekyll.
The layout file shown above is the default for all pages, blog posts and regular ones.
When you want all blog posts to contain additional information like post date and user, tags and so on.
For this, you can create a second layout file which uses the first one:
/_layouts/post.html:
---
layout: default
---
<div class="blogpost">
<i>post date: {{ page.date }}</i>
{{ content }}
</div>
And a blog post which uses this layout:
/_posts\2015-04-08-example-post.md:
---
title: example post
layout: post
---
This is the post content.
And the generated HTML:
<!DOCTYPE html>
<html>
<head>
<title>example post</title>
</head>
<body>
<h1>example post</h1>
<div class="blogpost">
<i>post date: 2015-04-08 00:00:00 +0200</i>
<p>This is the post content.</p>
</div>
</body>
</html>
In other words, something like this happened:
Jekyll used the post layout and put the content of the post into {{ content }}
Jekyll used the default layout and put the complete generated HTML from step 1 into {{ content }}
(no idea if Jekyll really does things in this order under the hood, but you get the idea)
You can see another example if you create a new Jekyll project as shown in the "Quick-start Instructions" on the home page of the Jekyll site.
The example site that Jekyll (version 2.1.1 on my machine) creates has three layout files, two of which (page and post) inherit from the default one.
I have an answer for myself, sort of. Each markdown file is assigned a layout in the front matter. But this "layout" isn't really a layout at all or it's a partial layout?
The terminology escapes me, so I'll just list the steps.
1) The markdown file has layout: post
2) Whatever is in the markdown file gets processed and then sent over to the logic residing in post.html. Here's the part that I wasn't getting right off: post.html has it's own layout. That's what's up in the front matter. Essentially we have the layout's layout.
3) The outer "layout" (default.html in a vanilla jekyll install), wraps itself around the inner "layout" (post.html), which wraps itself around the actual {{ content }}.
post.html could be named whatever, so long as the various layout lines are properly set.
I still don't know why {{ content }} winds up at the top of the layout stack only to be passed all the way back down. I'm not even sure "passed" is the right word when dealing with liquid. I like Jekyll, but it's kind of a nest of snakes.
Related
Here is my base.html.twig
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>{% include 'flashes/page-title.html.twig' %}</title>
</head>
<body>
<h1>{% include 'flashes/page-title.html.twig' %}</h1>
</body>
</html>
I'm wondering why twig includes only once this file ?
When you get a flash message from the flashbag, the message gets cleared at the same time. You can see this in Symfony's documentation of flash messages as well as in the FlashBagInterface API.
So my guess is that Twig includes the file twice, but the second time the flashbag is just empty. That's why you don't get anything for the h1 tag. You can confirm this by putting something static (e.g. simply Hello world) to the flashes/page-title.html.twig file and see whether the file gets included twice.
You could instead use the peek() method to retrieve the message while keeping it in the bag, i.e. something like {% for title in app.flashes.peek('title') %} or {% for title in app.session.flashbag.peek('title') %} if the former doesn't work. But then the message wouldn't get cleared. It might or might not be a problem in your case.
Could something else than flash messages be a better approach in this case?
My goal is to convert a markdown document to html, with a table of contents at the top. I saw that Redcarpet has a HTML_TOC option, which is really nice. But when I use it, it only renders the TOC, it does not include the rest of the document.
renderer = Redcarpet::Render::HTML_TOC.new(with_toc_data: true)
markdown = Redcarpet::Markdown.new(renderer)
html = markdown.render(File.read(input_file))
How do I render both the TOC and document itself in the same html page?
The only thing I can think of is to render two separate html objects, then combine them. But that is a little messy because I'd have to parse out the head/body tags properly before combining them. Is there a better way?
The only thing I can think of is to render two separate html objects, then combine them.
That would be exactly what you need to do. As a reminder, Markdown does not render a complete HTML document anyway. You only get an HTML fragment. For example a simple Markdown document:
A simple Markdown document.
gets rendered as the following HTML fragment:
<p>A simple Markdown document.</p>
However, for a complete, valid HTML document you need (at least) the following:
<!DOCTYPE html>
<html>
<head>
<title>Page Title</title>
</head>
<body>
<p>A simple Markdown document.</p>
</body>
</html>
Considering that you need to generate all of that anyway, how is it "messy" to obtain the TOC and the body separately?
In fact, in more sophisticated systems, the TOC may be in a sidebar or something. Therefore, using a templating system, the TOC can be passed to a template separately anyway, where it is then placed in a container which separates it from the document body for positioning and styling by CSS.
The exact template syntax might vary depending on which tools you use, but perhaps something like this:
<!DOCTYPE html>
<html>
<head>
<title>{{ page.title }}</title>
</head>
<body>
<aside>
{{ page.toc }}
</aside>
<div id="body">
{{ page.body }}
</div>
</body>
</html>
Of course, you don't have to use a template, but is certainly is a "clean" way to generate a document.
I want to use a theme cloned from GitHub into my themes directory for almost all pages and articles and automatically-generated pages except for my landing page whose template is not part of the cloned theme and which uses its own particular css..
Currently my working site uses a new template file and related images, js and css files added to the cloned theme. But that's not what I want.
I want to keep separate the landing page's template and related files from the cloned theme but don't understand what settings and / or content file's metadata to use to point to a different theme path just for that one page
i.e. I want to override the THEME settings on just one page.
Settings THEME, CSS_FILE, DIRECT-TEMPLATE and TEMPLATE_PAGES don't seem to be exactly what I want. But maybe they are?
You have a couple of different options. Personally, I'd go with the first method, but I've used all three of these in different situations.
The index.html method
With this method, you create an index.html file that is straight up HTML - exactly how you want your index.html page to look. You can use Jinja variables in it, which is important if you're including CSS that's in your theme (as opposed to using hosted libraries), but mostly, it just looks exactly like you want it to look. A very simple example:
<html>
<head>
<title>My Title</title>
<link href="{{ SITEURL }}/theme/css/mystyles.css" rel="stylesheet" type="text/css">
<body>
<h1>Hello world!</h1>
</body>
</html>
You can then tell Pelican not to render .html files by including this line in your pelicanconfig.py:
READERS = {'html': None}
This will not prevent Jinja from processing Jinja templates in the HTML document.
Finally, because you aren't including any metadata about the HTML file in the HTML file itself (that's what the READERS = {'html': None} business is all about), you have to tell Pelican where to put the final index.html, by setting the TEMPLATE_PAGES variable, also in your pelicanconf.py file:
TEMPLATE_PAGES = {
'index.html' : 'index.html'
}
Now you can see your page by going to localhost/ in your browser.
If you wanted to put the file at a different location, you can specify any location you want:
TEMPLATE_PAGES = {
'index.html' : 'mydirectory/mypage.html'
}
which would make your page accessible at localhost/mydirectory/mypage.html.
Include alternate CSS file in Markdown
Since most HTML works verbatim in Markdown posts, you could also modify your landing page Markdown file to include a CSS file at the top,
Title: My Index
Author: Clark Kent
Date: 2010-12-03 10:20
Category: StackOverflow
<link href="{{ SITEURL }}/theme/css/mystyles.css" rel="stylesheet" type="text/css">
# Hello World
Welcome to the landing page!
Add metadata to control theme
Lastly, you could modify the theme directly to include a metadata attribute that controls what stylesheets the theme uses. For example, let's use the WhichTheme: metadata flag. We'll specify WhichTheme: index for our index Markdown page, and WhichTheme: notindex (or nothing) for all other pages. Then in our theme files, we'll look for the template used to render all pages (usually pages.html), and we'll add a Jinja conditional to check for our new variable, which is accessible at page.WhichTheme:
{% if page.WhichTheme=='index' %}
<link href="{{ SITEURL }}/theme/css/mystyles.css" rel="stylesheet" type="text/css">
<h1>{{ page.title }}</h1>
{% else %}
<h1>{{ page.title }}</h1>
{% endif %}
I have a boilerplate that has various includes, one being:
#include('nav')
I would like to use the same boilerplate for the CMS of my site, but use a different nav.
What would be the best way of getting the boilerplate to include a different nav when the user is using the CMS:
#include('nav-cms')
This is more of an architectural question, and the answer is that you can probably do this many, many ways. However, the answers can be Laravel specific, so here goes:
One method would be to change the include statement to be:
#include($navView)
And then either in your controller, or using view composer, you should set that variable appropriately.
Alternatively, you can do it using sections:
// layout.blade.php
<html>
<head></head>
<body>
#section('nav')
#include('nav')
#show
#yield('content')
</body>
</html>
// some-frontend-view.blade.php
#extends('layout')
#section('content')
Content here
#stop
// some-cms-view.blade.php
#extends('layout')
#section('nav')
#include('nav-cms')
#overwrite
#section('content')
CMS content here
#stop
That way it assumes frontend nav, and then you override it in the CMS for the CMS nav. Alternatively, instead of defaulting to 'nav' in the layout, you could use #yield, and specify it in the some-frontend-view.blade.php file as in the some-cms-view.blade.php file.
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.