jekyll / jekyll

:globe_with_meridians: Jekyll is a blog-aware static site generator in Ruby

Jekyll

Jekyll is a simple, blog-aware, static site generator perfect for personal, project, or organization sites. Think of it like a file-based CMS, without all the complexity. Jekyll takes your content, renders Markdown and Liquid templates, and spits out a complete, static website ready to be served by Apache, Nginx or another web server. Jekyll is the engine behind GitHub Pages, which you can use to host sites right from your GitHub repositories.

Philosophy

Jekyll does what you tell it to do — no more, no less. It doesn't try to outsmart users by making bold assumptions, nor does it burden them with needless complexity and configuration. Put simply, Jekyll gets out of your way and allows you to concentrate on what truly matters: your content.

See: https://jekyllrb.com/philosophy

Getting Started

• Install the gem
• Read up about its Usage and Configuration
• Take a gander at some existing Sites
• Fork and Contribute your own modifications
• Have questions? Check out our official forum community Jekyll Talk and #jekyll Channel on Libera IRC

Diving In

• Migrate from your previous system
• Learn how Front Matter works
• Put information on your site with Variables
• Customize the Permalinks your posts are generated with
• Use the built-in Liquid Extensions to make your life easier
• Use custom Plugins to generate content specific to your site
• Watch video tutorials from Giraffe Academy

Need help?

If you don't find the answer to your problem in our docs, or in the troubleshooting section, ask the community for help.

Code of Conduct

In order to have a more open and welcoming community, Jekyll adheres to a code of conduct adapted from the Ruby on Rails code of conduct.

Please adhere to this code of conduct in any interactions you have in the Jekyll community. It is strictly enforced on all official Jekyll repositories, websites, and resources. If you encounter someone violating these terms, please let one of our core team members know and we will address it as soon as possible.

Credits

Sponsors

Support this project by becoming a sponsor. Your logo will show up in this README with a link to your website. Become a sponsor!

Contributors

This project exists thanks to all the people who contribute.

Backers

Thank you to all our backers! 🙏 Become a backer

License

See the LICENSE file.

jekyll's Issues

Jekyll gets confused with two post at the same date

Jekyll gets confused, with two posts at the same date. This leads (for example) to a broken "next" / "previous" - list for the posts.

To fix this the slug is used for equality tests, if two posts share the same publication date. This nicely solves the problem.

Please pull from my repository (Changeset 0de96b8e9dec4b351b3db21a51f29ede5d45d7e1)

Jekyll catastrophically fails on empty _config.yml

jekyll.rb's config-file parsing fundamentally expects YAML.load of the config file to return a Hash. This does not happen if _config.yml is empty (or, for example, entirely commented-out), in which case YAML.load returns false. YAML.load may also return several other types (String, Array, etc.) depending on the type of the root element of the YAML document.

I've fixed this in a simple patch in my fork: jrk/jekyll@07930dc

The patch simply checks that the class of any loaded config is Hash. If not, it throws that it could not parse the config file, continuing in the appropriate rescue block. This rescue block has also been made safer by forcing config to default to {}, since the previous code seems to have assumed that any exception would have occurred before the default config = {} was overwritten in the local scope, which is not necessarily true.

cgi_escape filter

I created a filter that escapes characters so they can safely be used in URLs.

I.e. "hey! you!" will be escaped as "hey%21+you%21".

See this branch: http://github.com/vilcans/jekyll/tree/cgi_escape

This is useful if you want to link to a tag summary page where tags potentially have spaces in them. So if tag is "interesting stuff", <a href="/tags/{{tag|cgi_escape}"> would link to /tags/interesting+stuff. I guess it can be used to link to a search engine as well.

(Oh, and standard Jekyll doesn't support tags, but it should, so replace tag with category or topic in the description above.)

Timestamp from filesystem or git

When creating an atom/rss/sitemap xml it would be nice to pick up the last-updated timestamp from the file instead of relying on the date in the filename.

Permalinks for pages

Currently the permalink scheme and the "permalink" parameter in the yaml front matter are ignored for regular pages. They're just copied to the "_site" dir with extension replaced with ".html". So in case of pretty permalinks you get "path/to/your/post/index.html" for your posts and "/about.html" for regular pages which is not consistent. I've fixed it in my fork http://github.com/eugenebolshakov/jekyll/tree/permalinks_for_pages

Revamp Post Published Status

From a conversation with nirvdrum:

09:41 nirvdrum: qrush_: FWIW, that's not exactly the behavior I was looking for.  If I get some time, I'll work up a patch.  I basically want to make the post available live, but not linked to.
09:47 nirvdrum: qrush_: I'd like to make the page live so I can hand the link out, but not have it appear in the atom feed, the index, categories, etc.
09:47 qrush_: Yeah, there's no 'draft' functionality yet
09:47 nirvdrum: qrush_: draft is a fine term.  More descriptive than "unpublished"
09:48 jharuska: qrush_: as far as i know you still need to build the proxy? god damn students
09:49 qrush_: nirvdrum: I'd rather have a status option
09:49 qrush_: that's either
09:49 qrush_: ignore, draft, published
09:49 nirvdrum: qrush_: Agreed.

convert err to string

I made a small fix to jekyll in branch master of git://github.com/luciang/jekyll.git.
The problem arrised when I ran
$ jekyll
in a directory that had no files related to jekyll.

The exact error message:
/var/lib/gems/1.9.0/gems/mojombo-jekyll-0.5.0/lib/jekyll.rb:72:in `+': can't convert Errno::ENOENT into String (TypeError)

RSS importer

I made an importer that reads the contents of an RSS feed and creates HTML files in _posts. It can be used as a generic importer from any blog engine.

http://github.com/vilcans/jekyll/tree/rss_importer

I have only tested it on my own RSS feed and on a Blogger feed, and it worked. It may not create proper post IDs or have other problems with other feeds.

Pull and modify if you want.

classification fixes

related_posts now adds in posts from nested _posts directories, and added
slug to text considered for classification (kanwei/jekyll)

Generators

I think some generators for Jekyll would be really useful. Here's what I had in mind:

jekyll generate post [title] => 
  _posts/todays-date-title.textile

jekyll generate post [title] --markdown => 
  _posts/todays-date-title.markdown

jekyll generate site => 
  creates _posts, _layouts dir, default layout, index.html, _config.yml

It would be neat to have a generic generation system like Rails, but I think this would be a decent start to give those who use jekyll for the first time or those who need to whip up a new post.

Support for posts pagination

Hi, I've been working on a basic support for posts' pagination. When the pages are processed several directories are created with the number of the page and and index file with the posts for that page.

I've added some documentation, cucumber features and tests.

You can take a look at my fork:

http://github.com/calavera/jekyll/tree/master

[FIX] Highlighting breaks on UTF-8

Fixed here: http://github.com/henrik/jekyll/commit/fb3d93759bc1e3deefe0b8b6d9ef7e6becbcb37a

Also here: http://github.com/henrik/albino

Possibly my fix needs some additional work to handle linenos.

add an exclude option to exclude certain files to be copied

I have added a config option to exclude certain files in the root directory to be copied into _site, as I have a rakefile as well a README and others in it.

You'll find it in my master branch which is on top of yours @ [email protected]:duritong/jekyll.git

Get config values in pages

I have found it useful to be able to get settings values (i.e. the ones in _config.yml) from the page code. In my scribbish-jekyll project I want to be able configure the name of the site, URLs etc. by just editing the config files instead of the templates.

For example, if you have the following in _config.yml:

url: http://www.librador.com

...you can have the following in an HTML page:

<a href="{{site.url}}">Home!</a>

Here's an implementation:
vilcans/jekyll@7b44923

Order of hierarchical/categories should match source folder layout

Jekyll's inference of flat category and topic spaces from trees of parent folders (above and below _posts, respectively) is potentially useful. However, where categories are reflected in the generated URL structure (which they are by default, which is good), the generated directory structure should mirror the source structure, not be re-nested as some arbitrary ordering of categories.

In my case, under my Jekyll root, I have:

projects/
    aProject/
        _posts/
    anotherProject/
        _posts/

and in the generated _site this yields:

projects/aProject/year/month/day/some-post

AND

aProject/projects/year/month/day/some-post

with the default url for the post (which gets inserted in templates referencing that post) being in reverse order, pointing to the latter:

aProject/projects/year/month/day/some-post

This is unintuitive in two respects:

1. Generating the combinatorial set of possible paths to each post is unexpected.
2. Having the default path/permalink include a different (perhaps arbitrary) hierarchical ordering of categories is unexpected and undesirable.

It is common to want some degree of hierarchy in a generated site. It only makes sense for the source hierarchy to be mirrored for posts (where it is mirrored at all -- I understand and respect that topic directories are meant to be handled separately, and not reflected in the generated directory structure), just as it is for generated non-post pages and other content. Supporting this more predictably is arguably much more valuable than any clever tricks to interpret hierarchical filesystem layout as implying a flat tag space, and even where those tricks may be useful, I maintain that this is logically something which should distinguish topics (tags) from categories ("folders").

Consider using jeweler gem from github, or try requiring both.

On Ruby 1.9 I only have technicalpickles-jeweler installed and jekyll blows up working with it locally. Would you consider either removing the gem 'jeweler' statement on ruby 1.9, or adding/changing it to gem 'technicalpickles-jeweler'?

Update RedCloth dependency to v4.1.9 to allow Ruby 1.9 to work

RedCloth 4.1.0 goes directly to exploding, and does not pass go on Ruby 1.9.1 locally.

Allow non-pretty permalinks to be set while pretty permalink style on

I want to migrate my blog to use pretty permalinks. The problem is that enabling pretty permalinks changes/breaks previous post urls that aren't pretty (i.e. that end in .html). Theoretically I could preserve old post urls by passing them a yaml permalink option. However this doesn't work since the pretty permalink style overrides the yaml permalink. I submitted a one-line pull request a week ago but haven't heard back.

Generate multiple files from one

I'd like to make pages that shows all the posts with a specific category/topic/tag. One such page should be created for each category/topic/tag.

E.g. if I have category "foo" and category "bar" I want Jekyll to generate the files /category/foo.html and /category/bar.html, each with a list of posts of that category. I don't want to create them manually if I have lots of categories.

So what I'm thinking about is some kind of "build description" file that specifies what files should be built and how.

Here's how that file can look in pseudo-code:

for each category:
    generate "categories/#{category}.html" from "_category.html"
for each topic:
    generate "topics/#{topic}.html" from "_topic.html"

Do you understand what I'm trying to say? Has anyone else thought about something like this and think it would be a good idea?

This could also be used to do something completely different from Jekyll's default behaviour if we want to. E.g. Jekyll's default would be to generate posts from the files in the "_posts" directory and "normal" pages from all other files, but it would be possible to override that with something else if needed.

'Use site.time variable' scenario fails if today's time has a plus in it

The 'then I should see today's time' in jekyll_steps doesn't escape the time before generating a Regexp, so if it has a plus in it (such as right now in the UK) it incorrectly fails.

I've fixed this in the master branch of my own fork:

http://github.com/tomafro/jekyll/tree/master

Issue with gh-pages rendering.

I'm not 100% sure what's going on, but I'm assuming it's a difference in how variables are assigned. I'm running Jekyll 0.5.0 locally and it groups my posts by year and month correctly. On my page it is repeating the information for each post. The relevant code is below. Let me know if any more information is needed.

<dl id="archives">
{% for post in site.posts %}
  {% if post.date|date:"%B" != previous_post.date|date:"%B" %}
    {% if post.date|date:"%Y" != previous_post.date|date:"%Y" %}
      {% assign year_changed = true %}
    {% else %}
      {% assign year_changed = false %}
    {% endif %}

    <dt class="month{% if year_changed %} year{% endif %}">
      {{ post.date | date:"%B" }}

      {% if year_changed %}
        <span>{{ post.date | date:"%Y" }}</span>
      {% endif %}
    </dt>
  {% endif %}

  <dd><span>{{ post.date | date:"%d" }}</span> <a href="{{ post.url }}">{{ post.title }}</a></dd>

  {% assign previous_post = post %}
{% endfor %}
</dl>

CGI escaping post urls

Special characters in post urls should be CGI escaped. I have a simple patch in my fork which works for my needs, it could possibly be expanded. Please let me know if anything should be adjusted. Example from the tests:

    @post.process("2009-03-12-hash-#1.markdown")
    assert_equal "/2009/03/12/hash-%231.html", @post.url
    assert_equal "/2009/03/12/hash-#1", @post.id

Docs

I think we need to move the documentation for the project out of the README and into something serious, either an RDoc site and/or attack the Wiki at full force. I'm thinking the Wiki could be used for setup tutorials and whatnot, and from there the code could be documented as much as possible. Any thoughts?

Support for pretty permalinks in other places

On my original blog, I had permalinks like /posts/hello-world

It’d be cool to support this. I’ve added support for a pretty_posts permalink schema in my own fork. I’m not sure if this is the best route though.

CLI for importing

I'm in the process of creating the wiki page for migrating from other platforms, and I definitely think this could use some work. Something like the following would be good:

jekyll import wordpress --user=root --password=lol --db=whatever [--markdown|--textile]

Partials: Includes with layouts

Call it partials, subpages or whatever. I came to a point where I wanted to generate multiple similar sections in a page and found no way to achieve this with Jekyll. Instead of writing lots of "copy & paste" code, I'd like to use some kind of partial (like in Rails).

I created a new tag for this, called import. It's more or less the same as the include tag, but it uses Jekyll::Page for rendering, not just Liquid::Template.

koraktor/jekyll@import-tag

Please note that this isn't perfect yet - e.g. you can't use this in Markdown or Textile files as line wraps and indentation are interpreted.

asciidoc support ?

Jekyll currently support markdown and textile markup.

Is there any chance to have asciidoc markup available ? http://www.methods.co.nz/asciidoc/

Thank you very much.

Liquid error: undefined method `xmlschema' for Date

In my Atom feed template, I have

<updated>{{ site.time | date_to_xmlschema }}</updated>

But the rendered XML looks like

<updated>Liquid error: undefined method `xmlschema' for #<Date: 4907055/2,0,2299161></updated>

stylesheet tag render with mtime

This is in the same spirit of Rails' `stylesheet_link_tag'. Introduce a style sheet tag which generates the link tag and appends on a query-string with the css file's mtime. This helps alleviate issues with the browser caching of the style sheet when the developer would prefer it be reloaded.

I've created a branch http://github.com/kyleburton/jekyll/commit/dccfb353fa3468a4e02718af49743fc71cddd263 with an implementation including unit tests.

Searching tags

I have been thinking to use the simplicity of Jekyll as a sort of a wiki. Many a times we come across the same problem over and over again and it would be good if it is documented somewhere. For example: How do I add new users to CentOS in a certain group? So I will assign my post some tags, let's say: linux, administration...and so on.

The problem arises when I want to search for certain tags let us say "linux" from 300 or so posts I have got. So, I was thinking if we append the tags to the end of the file name like: "2008-10-18-foo-bar-tag-ruby-nuby.textile" and get javascript to filter the links on the page.

HTML parse error for valid img tag

I can render a regular HTML with this content:

<html>

<img src="http://yuml.me/diagram/class/[Project]-&gt;[Task]"/>

</html>

but if I put the img tag in a mardown file parsed with jekyll, I get the following error:
HTML parse error:
<img src="http://yuml.me/diagram/class/[Project]- />

I'm new to jekyll and not a markdown expert, so maybe I'm missing something. It sure would be cool to use yuml in with the markdown for easy diagrams.

Thanks.

Allow projects to have their own Liquid tags

I find that I often need to implement my own Liquid tags for various projects I've worked on in Jekyll. I implemented this in my Jekyll branch by allowing each project to have its own _tags directory. Here's the patch; happy to refactor if you like the idea but not the implementation:

http://github.com/n8agrin/jekyll/commit/f65e50703ce2671f532e7bbdecfebf11aeccf9ad

Next and previous posts are backwards

Just switch the next and previous methods in post.rb.

Unless this is a weird problem with post_data.feature, or a weird local problem?

Remove Topics, Add Tags

Does anyone actually use topics? I think they're just confusing and should be replaced with a decent implementation of tagging.

[FIX] Markdown after highlight block broken with RDiscount

Fix here: http://github.com/henrik/jekyll/commit/60683ea48b5616a5845c9d58f59555e7ac4779ba

Runnable example code for the issue in the commit message.

Support custom root URL path as config parameter

Jekyll appears fairly hard-wired to assume that the generated site will live at the root of the web host (post.url, the WEBrick preview server, etc. assume everything begins directly at "/"). It would be useful in many situations to have a Jekyll-generated site living in a specific subdirectory, without requiring lots of template wrangling, and while still supporting the WEBrick preview server. Ideally this would be a single config variable which would:

• Prefix all system-generated URLs
• Be available as a Liquid tag for templating
• Be simulated in the WEBrick preview server

Page rendering errors cause Jekyll to fail silently

In server- and auto modes, Jekyll silently fails to build a page that has markup errors. The only error type I've been able to pinpoint so far is a syntax error in the YAML header, like:

---
title: something. with: weird, punctuation
layout: default

---
Some content

Saving that file just causes the following to be spit into the log:

[2009-05-23 15:29:25] regeneration: 1 files changed

but no HTML file is generated. Fixing the header (by putting quotes around the title value) causes the page to generate properly.

CRLF linebreaks in YAML front matter halts execution

If the YAML front matter contains CRLF (0d0a) linebreaks page generation halts with the following exception:

ArgumentError: syntax error on line 3, col 12: ' /opt/local/lib/ruby/1.8/yaml.rb:133:inload'
/opt/local/lib/ruby/1.8/yaml.rb:133:in `load'

Changing the regex in Jekyll::Convertible#read_yaml to cater for CRLF fixes this issue.

A fix for this defect (with appropriate test case) can be found here:
http://github.com/juretta/jekyll/tree/fixlinebreak-in-frontmatter (#71516fabe).

A pretty permalink should end with a slash

AFAIK when apache gets a request like /path/to/post it looks for a file named "post" by default, not a directrory. That's why a mod rewrite rule is often added that redirects such requests to /path/to/post/ (basically just adds a trailing slash) and everything works well.

However the links in jekyll still don't have that trailing slash which confuses disqus. Comments are added to a page with the trailing slash and counters are requested for a page without the slash.

I think the pretty permalinks template should have the trailing slash to avoid the redirect and make disqus comments counters work correctly. I have it my fork http://github.com/eugenebolshakov/jekyll/tree/trailing-slashes-for-pretty-permalinks

It's obviously a tiny fix. I've also added the entire test/dest directory to .gitignore

some pages fail to generate with no error message

Some pages in my site will generate fine for a while. Then something will get messed up and I'll clear out the /_site directory and restart the jekyll server. After that, things go haywire -- some pages will get generated, but many won't. There are no error messages.

Refactor access to category/tag names

Adding a sorted array with all available category names as 'site.categorynames'. This allows to set up a listing of all categories.

Please pull from my repository (commit b659e9ce34cb74129650fc3e37ee5000328e9d8d).

Project Page

I've started a project page for Jekyll here: (Jekyll creating a page for Jekyll. Can't get better than that)

http://qrush.github.com/jekyll/
http://github.com/qrush/jekyll/tree/gh-pages

I'm looking for feedback on what else could go on here.

Extra line breaks in pygments syntax highlighting (0.5.0)

Since upgrading to 0.5.0 I am getting extra spaces between each line. First noticed this on my github Pages account, then confirmed that 0.5.0 was causing the spaces locally as well.

You can see what I mean here: http://www.supaspoida.com/2009/04/14/adding-context-to-resources-using-render_with_context.html

converter for marley

for marley

http://github.com/jberkel/jekyll/tree/marley_importer

Layout that can list posts with (parametric) topics/categories

This might just be an issue for me and not a lack of feature in jekyll. I want to make a layout that is used to list all posts with an arbitrary topic, and have each page that use that layout specify what topic that is.

How do I pass on references from a page to a layout, so that the page can tell the xyz layout to loop through site.categories.foo from xyz-layouted foo.textile and site.categories.bar from xyz-layouted bar.textile ?

Unicode Support

Jekyll doesn't like posts that are in unicode. FIX IT!

Passing options to Pygments

Right now only linenos can be passed to Pygments. I built a small patch for the highlight tag allowing general passing of options to Pygments. This can be used e.g. for startinline for PHP code.

http://github.com/koraktor/jekyll/commit/dd12900dd59b2a6526040fc7d1400f35a8a73fe8

Support for navigation between posts in chronological order

This patch allows you to use constructs like {{ page.previous.title }} and {{ page.next.title }} in your liquid markup. As per the instructions, here is the link http://github.com/pantulis/jekyll/tree/master

Unit tests and a cucumber feature are included.

site.topics should only return a list of topics

Currently for me it's returning not just a list of the topics, but also the entire content of every single post within that topic.

Ideally, one should be able to do site.topics much in the same way they can use site.categories. This would allow, for example, to create a nice page with a listing of all topics.

Here's what I'd ideally like to be able to do:

---
layout: default
title: Will Farrington - Tags

---
<div class='topics'>
  {% for topic in site.topics %}
  <h2>{{ topic }}</h2>
  <ul class="topic">
    {% for post in site.topics.{{ topic }} %}
    <li>{{ post.title }}</li>
    {% endfor %}
  </ul>
  {% endfor %}
</div>

post_defaults section in _config.yml, for default layouts

So you don't have to specify the layout in every post.

Implemented here (without tests, sorry): http://github.com/henrik/jekyll/commit/77bf31c42c25c2f87c215348a816b730104fe820