Skip to content

Commit 9e874c4

Browse files
groundh0ggroundh0g
committed
Addresses PR plusjade#206, tag cloud support. Splits sample post into multiple posts to showcase the tag cloud. Cloud example is included in bootstrap-3 template, but commented out.
1 parent e4f88a9 commit 9e874c4

File tree

8 files changed

+269
-197
lines changed

8 files changed

+269
-197
lines changed

‎_includes/JB/tag_cloud‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
{% comment %}
2+
Creates a tag cloud on your page.
3+
{% endcomment %}
4+
{% for tag in site.tags %}
5+
<span class="tag-cloud-{{ tag | last | size | times: 10 | divided_by: site.tags.size }}">
6+
<a href="{{ BASE_PATH }}{{ site.JB.tags_path }}#{{ tag | first | slugify }}-ref">{{ tag | first }}</a>
7+
</span>
8+
{% endfor %}

‎_includes/themes/bootstrap-3/default.html‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,19 @@
8181
{{ content }}
8282
</div>
8383

84+
{% comment %}
85+
<!-- EXAMPLE: Tag Cloud Usage -->
86+
<div class="cloud-container">
87+
<h2 class='title'>Tag Cloud</h2>
88+
<!-- start tag cloud -->
89+
<div>
90+
{% include JB/tag_cloud %}
91+
</div>
92+
<!-- end tag cloud -->
93+
<div class='clear'></div>
94+
</div>
95+
{% endcomment %}
96+
8497
</div>
8598

8699
<div id="footer">

‎_posts/core-samples/2011-12-29-jekyll-introduction.md‎

Lines changed: 0 additions & 195 deletions
Original file line numberDiff line numberDiff line change
@@ -215,198 +215,3 @@ This page will be available at `http://yourdomain.com/people/bob/essay.html`
215215
- **about.html**
216216
A nice about page is easy to do and gives the human perspective to your website.
217217

218-
219-
## Templates in Jekyll
220-
221-
Templates are used to contain a page's or post's content.
222-
All templates have access to a global site object variable: `site` as well as a page object variable: `page`.
223-
The site variable holds all accessible content and metadata relative to the site.
224-
The page variable holds accessible data for the given page or post being rendered at that point.
225-
226-
**Create a Template**
227-
Templates are created by properly formatting a file and placing it in the `_layouts` directory.
228-
229-
**Formatting**
230-
Templates should be coded in HTML and contain YAML Front Matter.
231-
All templates can contain Liquid code to work with your site's data.
232-
233-
**Rending Page/Post Content in a Template**
234-
There is a special variable in all templates named : `content`.
235-
The `content` variable holds the page/post content including any sub-template content previously defined.
236-
Render the content variable wherever you want your main content to be injected into your template:
237-
238-
{% capture text %}...
239-
<body>
240-
<div id="sidebar"> ... </div>
241-
<div id="main">
242-
|.{content}.|
243-
</div>
244-
</body>
245-
...{% endcapture %}
246-
{% include JB/liquid_raw %}
247-
248-
### Sub-Templates
249-
250-
Sub-templates are exactly templates with the only difference being they
251-
define another "root" layout/template within their YAML Front Matter.
252-
This essentially means a template will render inside of another template.
253-
254-
### Includes
255-
In Jekyll you can define include files by placing them in the `_includes` folder.
256-
Includes are NOT templates, rather they are just code snippets that get included into templates.
257-
In this way, you can treat the code inside includes as if it was native to the parent template.
258-
259-
Any valid template code may be used in includes.
260-
261-
262-
## Using Liquid for Templating
263-
264-
Templating is perhaps the most confusing and frustrating part of Jekyll.
265-
This is mainly due to the fact that Jekyll templates must use the Liquid Templating Language.
266-
267-
### What is Liquid?
268-
269-
[Liquid](https://github.com/Shopify/liquid) is a secure templating language developed by [Shopify](http://shopify.com).
270-
Liquid is designed for end-users to be able to execute logic within template files
271-
without imposing any security risk on the hosting server.
272-
273-
Jekyll uses Liquid to generate the post content within the final page layout structure and as the primary interface for working with
274-
your site and post/page data.
275-
276-
### Why Do We Have to Use Liquid?
277-
278-
GitHub uses Jekyll to power [GitHub Pages](http://pages.github.com/).
279-
GitHub cannot afford to run arbitrary code on their servers so they lock developers down via Liquid.
280-
281-
### Liquid is Not Programmer-Friendly.
282-
283-
The short story is liquid is not real code and its not intended to execute real code.
284-
The point being you can't do jackshit in liquid that hasn't been allowed explicitly by the implementation.
285-
What's more you can only access data-structures that have been explicitly passed to the template.
286-
287-
In Jekyll's case it is not possible to alter what is passed to Liquid without hacking the gem or running custom plugins.
288-
Both of which cannot be supported by GitHub Pages.
289-
290-
As a programmer - this is very frustrating.
291-
292-
But rather than look a gift horse in the mouth we are going to
293-
suck it up and view it as an opportunity to work around limitations and adopt client-side solutions when possible.
294-
295-
**Aside**
296-
My personal stance is to not invest time trying to hack liquid. It's really unnecessary
297-
_from a programmer's_ perspective. That is to say if you have the ability to run custom plugins (i.e. run arbitrary ruby code)
298-
you are better off sticking with ruby. Toward that end I've built [Mustache-with-Jekyll](http://github.com/plusjade/mustache-with-jekyll)
299-
300-
301-
## Static Assets
302-
303-
Static assets are any file in the root or non-underscored subfolders that are not pages.
304-
That is they have no valid YAML Front Matter and are thus not treated as Jekyll Pages.
305-
306-
Static assets should be used for images, css, and javascript files.
307-
308-
309-
310-
311-
## How Jekyll Parses Files
312-
313-
Remember Jekyll is a processing engine. There are two main types of parsing in Jekyll.
314-
315-
- **Content parsing.**
316-
This is done with textile or markdown.
317-
- **Template parsing.**
318-
This is done with the liquid templating language.
319-
320-
And thus there are two main types of file formats needed for this parsing.
321-
322-
- **Post and Page files.**
323-
All content in Jekyll is either a post or a page so valid posts and pages are parsed with markdown or textile.
324-
- **Template files.**
325-
These files go in `_layouts` folder and contain your blogs **templates**. They should be made in HTML with the help of Liquid syntax.
326-
Since include files are simply injected into templates they are essentially parsed as if they were native to the template.
327-
328-
**Arbitrary files and folders.**
329-
Files that _are not_ valid pages are treated as static content and pass through
330-
Jekyll untouched and reside on your blog in the exact structure and format they originally existed in.
331-
332-
### Formatting Files for Parsing.
333-
334-
We've outlined the need for valid formatting using **YAML Front Matter**.
335-
Templates, posts, and pages all need to provide valid YAML Front Matter even if the Matter is empty.
336-
This is the only way Jekyll knows you want the file processed.
337-
338-
YAML Front Matter must be prepended to the top of template/post/page files:
339-
340-
---
341-
layout: post
342-
category : pages
343-
tags : [how-to, jekyll]
344-
---
345-
346-
... contents ...
347-
348-
Three hyphens on a new line start the Front-Matter block and three hyphens on a new line end the block.
349-
The data inside the block must be valid YAML.
350-
351-
Configuration parameters for YAML Front-Matter is outlined here:
352-
[A comprehensive explanation of YAML Front Matter](https://github.com/mojombo/jekyll/wiki/YAML-Front-Matter)
353-
354-
#### Defining Layouts for Posts and Templates Parsing.
355-
356-
The `layout` parameter in the YAML Front Matter defines the template file for which the given post or template should be injected into.
357-
If a template file specifies its own layout, it is effectively being used as a `sub-template.`
358-
That is to say loading a post file into a template file that refers to another template file with work in the way you'd expect; as a nested sub-template.
359-
360-
361-
362-
363-
364-
## How Jekyll Generates the Final Static Files.
365-
366-
Ultimately, Jekyll's job is to generate a static representation of your website.
367-
The following is an outline of how that's done:
368-
369-
1. **Jekyll collects data.**
370-
Jekyll scans the posts directory and collects all posts files as post objects. It then scans the layout assets and collects those and finally scans other directories in search of pages.
371-
372-
2. **Jekyll computes data.**
373-
Jekyll takes these objects, computes metadata (permalinks, tags, categories, titles, dates) from them and constructs one
374-
big `site` object that holds all the posts, pages, layouts, and respective metadata.
375-
At this stage your site is one big computed ruby object.
376-
377-
3. **Jekyll liquifies posts and templates.**
378-
Next jekyll loops through each post file and converts (through markdown or textile) and **liquifies** the post inside of its respective layout(s).
379-
Once the post is parsed and liquified inside the the proper layout structure, the layout itself is "liquified".
380-
**Liquification** is defined as follows: Jekyll initiates a Liquid template, and passes a simpler hash representation of the ruby site object as well as a simpler
381-
hash representation of the ruby post object. These simplified data structures are what you have access to in the templates.
382-
383-
3. **Jekyll generates output.**
384-
Finally the liquid templates are "rendered", thereby processing any liquid syntax provided in the templates
385-
and saving the final, static representation of the file.
386-
387-
**Notes.**
388-
Because Jekyll computes the entire site in one fell swoop, each template is given access to
389-
a global `site` hash that contains useful data. It is this data that you'll iterate through and format
390-
using the Liquid tags and filters in order to render it onto a given page.
391-
392-
Remember, in Jekyll you are an end-user. Your API has only two components:
393-
394-
1. The manner in which you setup your directory.
395-
2. The liquid syntax and variables passed into the liquid templates.
396-
397-
All the data objects available to you in the templates via Liquid are outlined in the **API Section** of Jekyll-Bootstrap.
398-
You can also read the original documentation here: <https://github.com/mojombo/jekyll/wiki/Template-Data>
399-
400-
## Conclusion
401-
402-
I hope this paints a clearer picture of what Jekyll is doing and why it works the way it does.
403-
As noted, our main programming constraint is the fact that our API is limited to what is accessible via Liquid and Liquid only.
404-
405-
Jekyll-bootstrap is intended to provide helper methods and strategies aimed at making it more intuitive and easier to work with Jekyll =)
406-
407-
**Thank you** for reading this far.
408-
409-
## Next Steps
410-
411-
Please take a look at [{{ site.categories.api.first.title }}]({{ BASE_PATH }}{{ site.categories.api.first.url }})
412-
or jump right into [Usage]({{ BASE_PATH }}{{ site.categories.usage.first.url }}) if you'd like.

‎_posts/core-samples/2014-03-08-jekyll-templates-includes-and-themes.md‎

Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
layout: post
3+
category : lessons
4+
tagline: "Supporting tagline"
5+
tags : [intro, beginner, jekyll, tutorial]
6+
---
7+
{% include JB/setup %}
8+
9+
## Templates in Jekyll
10+
11+
Templates are used to contain a page's or post's content.
12+
All templates have access to a global site object variable: `site` as well as a page object variable: `page`.
13+
The site variable holds all accessible content and metadata relative to the site.
14+
The page variable holds accessible data for the given page or post being rendered at that point.
15+
16+
**Create a Template**
17+
Templates are created by properly formatting a file and placing it in the `_layouts` directory.
18+
19+
**Formatting**
20+
Templates should be coded in HTML and contain YAML Front Matter.
21+
All templates can contain Liquid code to work with your site's data.
22+
23+
**Rending Page/Post Content in a Template**
24+
There is a special variable in all templates named : `content`.
25+
The `content` variable holds the page/post content including any sub-template content previously defined.
26+
Render the content variable wherever you want your main content to be injected into your template:
27+
28+
{% capture text %}...
29+
<body>
30+
<div id="sidebar"> ... </div>
31+
<div id="main">
32+
|.{content}.|
33+
</div>
34+
</body>
35+
...{% endcapture %}
36+
{% include JB/liquid_raw %}
37+
38+
### Sub-Templates
39+
40+
Sub-templates are exactly templates with the only difference being they
41+
define another "root" layout/template within their YAML Front Matter.
42+
This essentially means a template will render inside of another template.
43+
44+
### Includes
45+
In Jekyll you can define include files by placing them in the `_includes` folder.
46+
Includes are NOT templates, rather they are just code snippets that get included into templates.
47+
In this way, you can treat the code inside includes as if it was native to the parent template.
48+
49+
Any valid template code may be used in includes.
50+
51+

‎_posts/core-samples/2014-03-09-using-liquid-for-templating.md‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
---
2+
layout: post
3+
category : lessons
4+
tagline: "Supporting tagline"
5+
tags : [jekyll, tutorial, liquid, templating]
6+
---
7+
{% include JB/setup %}
8+
9+
## Using Liquid for Templating
10+
11+
Templating is perhaps the most confusing and frustrating part of Jekyll.
12+
This is mainly due to the fact that Jekyll templates must use the Liquid Templating Language.
13+
14+
### What is Liquid?
15+
16+
[Liquid](https://github.com/Shopify/liquid) is a secure templating language developed by [Shopify](http://shopify.com).
17+
Liquid is designed for end-users to be able to execute logic within template files
18+
without imposing any security risk on the hosting server.
19+
20+
Jekyll uses Liquid to generate the post content within the final page layout structure and as the primary interface for working with
21+
your site and post/page data.
22+
23+
### Why Do We Have to Use Liquid?
24+
25+
GitHub uses Jekyll to power [GitHub Pages](http://pages.github.com/).
26+
GitHub cannot afford to run arbitrary code on their servers so they lock developers down via Liquid.
27+
28+
### Liquid is Not Programmer-Friendly.
29+
30+
The short story is liquid is not real code and its not intended to execute real code.
31+
The point being you can't do jackshit in liquid that hasn't been allowed explicitly by the implementation.
32+
What's more you can only access data-structures that have been explicitly passed to the template.
33+
34+
In Jekyll's case it is not possible to alter what is passed to Liquid without hacking the gem or running custom plugins.
35+
Both of which cannot be supported by GitHub Pages.
36+
37+
As a programmer - this is very frustrating.
38+
39+
But rather than look a gift horse in the mouth we are going to
40+
suck it up and view it as an opportunity to work around limitations and adopt client-side solutions when possible.
41+
42+
**Aside**
43+
My personal stance is to not invest time trying to hack liquid. It's really unnecessary
44+
_from a programmer's_ perspective. That is to say if you have the ability to run custom plugins (i.e. run arbitrary ruby code)
45+
you are better off sticking with ruby. Toward that end I've built [Mustache-with-Jekyll](http://github.com/plusjade/mustache-with-jekyll)

0 commit comments

Comments
 (0)