Notes from the Jekyll Mini Summit

[benbalter]

GitHub invited the Jekyll core team to informally chat all things Jekyll + GItHub Pages over drinks this weekend. Although no concrete decisions were made in meatspace, it was a great, great conversation (we'll follow up by opening lots of new issues here for further discussion where appropriate), but we wanted to surface the notes to expose process.

If anything strikes you, feel free to weigh in below, or ask for clarification where the shorthand is unclear.

---

Attendees: @mojombo, @parkr, @mattr-, @benbalter, @afeld, @gjtorikian, and @mislav

Vision

• “Jekyll is a simple, blog aware, static site generator.”
• Blog aware, not blog centric
• File-system based CMS
• Originally called “autoblog”
• Despite start, big use case today is technical documentation
• Not Rails style conventions over configurations
• Don’t try to outsmart the users
• Jekyll should do what I tell it to do, no more, no less
• The three-little bears of CMSs
• Git should not be a requirement to using Jekyll
• Marketing for open source projects, people, organizations
• Make it easier to install (Installer Packages with Ruby/RubyGems & gem dependencies installed)

Collections

• If people are using blog posts for a non-blog post thing, Jekyll has already failed
• By default, Jekyll registers [posts, pages]
• Can describe additional collections in _config.yml
• Can describe render in _config.yml, which by default contains pages, posts
• Collections rendered, render to /collection/#{object} - maybe give it a path?
• Jekyll looks to “/_#{collection}”
• FIles read in as site.#{collection}
• Collection object basic functionality, extended by posts and pages methods
• Anything in _collections folder is processed as a thing, much like _posts
• Posts, pages extends Collection (Ruby Object) (or something)
• Posts read tags, categories in to site.tags and site.categories, have dates in file names
• Pages don’t live in _collections folder

Layouts

• Explicit YAML
• YAML defaults
• Look to _layouts/#{collection}.* (only if specified in _config.yml under defaults?)
• Then look to _layouts/default.html
• Layouts of other types, e.g. Markdown/Textile?

Versioning jekyll sites alongside code

• Jekyll gh-publish or similar command to pull from /docs/ to gh-pages branch
• docs/site in a subdirectory alongside code

Faster builds

• IO vs CPU bottlenecks? Need better performance metrics
• Right now on watch, we reread all files in and basically run build when a file is changed
• Keep the site in memory, when a file is changed, just re-read that file and rebuild
• Ideally, we’d have a dependency tree and could know what would need to be re-rendered
• If the lag is IO, parallel processing may help as order doesn’t matter

Hooks / Plugin API

• What hooks do we want?

New default markdown processor

• Kramdown is nice because it’s pure Ruby, awesome docs
• Redcarpet is nice because it has an active developer community, written in C
• Would want to know if Redcarpet could commit to Windows support, user-centric docs

Potential Roadmap

• 2.0.0 - Tilt, Collections, Maruku EOL, new default markdown processor
• “3.0.0” - Refactor, Plugin API

Quality

• Breaking changes for plugins at major versions 👍
• Breaking changes for build pass/fail 👎
• Create list of top N pages sites, build as part of CI, run git diff

Input <-> output relationships

• Right now, one to one input to output relationship
• Collections will make that many to one, input to output
• Should be many to many… allow multiple representations of the same content via plugins / renderers
• use cases: .json/xml representations, ePub, etc.
• We have a great input experience and authoring workflow
• No reason it needs to be limited to HTML… maybe soon we can output ePub representations of technical documentation

Minimizing time to first site / community participation

• Installation is Painful - installer?
  • Bitnami package for Jekyll?
  • Disk image w/ everything installed, via Vagrant/Docker/something
• Feedback pipeline
• Avenues of contribution for all stakeholders http://ben.balter.com/open-sourcing-government/#/continuum-of-stakeholders

[nicksuch]

+1 for Collections, will start using that as soon as it arrives!

[mislav]

Our discussions about Collections was promising but I forgot what the technical conclusion of that discussion was, i.e. how are Collections going to be implemented and how is the feature exposed to the user. @parkr: I would appreciate if you CC me on some future discussion or PR about this.

[benbalter]

@mislav #1941 has some further explanation, and will likely be the 🏠 for future discussions. 😄

[jglovier]

Sounds like you people covered a lot of ground, and there's exciting things ahead!

• Installation is Painful - installer?

Curious about this point - what exactly do you feel makes Jekyll installation painful? Even as someone who always feels like a guest on the command line, I think freshly installing Jekyll is pretty straight forward and painless. Am I mistaking the context here or something?

[pathawks]

what exactly do you feel makes Jekyll installation painful?

@jglovier If you're already a Ruby programmer, gem install jekyll works fantastically.
If you're not, installing Jekyll requires first getting several dependancies setup, lots of Googling, and 2.09 GB of XCode.

[gjtorikian]

If you're not, installing Jekyll requires first getting several dependancies setup, lots of Googling, and 2.09 GB of XCode.

@jglovier Exactly that ☝️. We talked briefly about doing bundled .deb, .pkg. or .exes though none of us have any clue on how to do that. Heck, the state of Jekyll on Windows at this moment is already a pain.

[jglovier]

If you're not, installing Jekyll requires first getting several dependancies setup, lots of Googling, and 2.09 GB of XCode.

Ooohhhh yeah - gotcha. That totally makes sense now.

[mattr-]

I could do bundled RPMs at least. I haven't offered before because I haven't set up the environment yet.

On Tue, Jan 14, 2014 at 9:47 PM, Joel Glovier notifications@github.com
wrote:

Ooohhhh yeah - gotcha. That totally makes sense now.

Reply to this email directly or view it on GitHub:
#1929 (comment)

[doktorbro]

Please ask advice about packaging and Windows support from a Wordpress core member like @nacin. From what I know these tasks are not maintainable.

[mislav]

If you're already a Ruby programmer, gem install jekyll works fantastically.

…Until you switch to a different Ruby version on your system, or accidentally upgrade Liquid or your Markdown version to an incompatible version, and then wonder why either jekyll build fails or site builds fine locally but breaks on GH Pages.

Even for experienced users, there are so many ways how you can shoot yourself in the foot with Jekyll setup. I'm 👍 💯 for an installer that would put everything in an isolated location a la vagrant.

[metaskills]

Why not just use a Gemfile with version deps? Going the vagrant route seems heavy handed for a solution that most Ruby projects use already.

[mislav]

Sure, that's what I do for my Pages projects. There is also github-pages

However since jekyll is a program that you run on your compter and expect to work in a predictable way, it makes more sense that its runtime is isolated from the rest of your development environment. My rule of thumb is that I keep the tools that I use separate from the development environment I use for my libraries and apps. E.g. I might want to use jekyll, t, vagrant, heroku, cane or a similar tool while in my app's directory, but the fact that these programs are written in Ruby is just an implementation detail. They don't need to be run using the same version of Ruby that my app is using, their gems don't need to be among the shared gems of my current Ruby installation, and I certainly won't add them to the Gemfile.

[metaskills]

I just feel that judicious use of Bundler (future rubygems really) is the way to go. For instance, I always leverage binstubs on all my new projects, Jekyll included. I really can not make a good technical case against vagrant other than I have not felt the pain point to use it. Note that I am not a shallow user either. So the question is what does vagrant solve that a Gemfile and basic directions do not and is said issue substantive enough to warrant it? Or even some other methodology, ala the Heroku Toolbelt.

[parkr]

@metaskills You bring up some good points, but think about your perspective: you're an experienced Ruby developer who knows how to use and manage gems, and you can decipher the errors with relative ease. I'd say that your argument is flawless until you consider a user less experienced with Ruby programming tools (maybe you come from a Java or Python background). The learning curve for understanding Bundler isn't that high, but I'd love to be able to get Jekyll in the hands of a group of users that aren't as experienced or savvy in their use and understanding of Ruby and its tools.

[mislav]

I have been programming Ruby since 2004 and just in the past 2 years through many incidents I have lost countless hours in total on my Pages-powered blog debugging why GitHub reports failures building my site or why does it render stuff differently than I expected. The answer would always be that I broke my local Jekyll environment somehow, either by moving to an incompatible Ruby version or by accidentally upgrading dependent gems.

If you followed Gary Bernhard on Twitter last year, he tweeted a lot about pains he was experiencing while trying to use Jekyll consistently over a long period of time. His experiences resonated with mine, and we're both experienced Ruby developers that know very well how Bundler and RubyGems work.

[mhulse]

consider a user less experienced with Ruby programming tools (maybe you come from a Java or Python background). The learning curve for understanding Bundler isn't that high, but I'd love to be able to get Jekyll in the hands of a group of users that aren't as experienced or savvy in their use and understanding of Ruby and its tools.

When I was new to Jekyll ('bout a month back now), I kinda wish I found docs right up front that stated (basically):

$ gem install bundler

... and in my GemFile:

source 'https://rubygems.org'

gem 'jekyll'

Next:

# Note: Always run `bundle exec` when serving your site:
$ bundle exec jekyll serve --watch

With clear explanations as to why one should use bundler, maybe links to how the GemFile works, with an explanation on the bundle exec ... command.

From my perspective, it might have been nice to see installation instructions that combine Jekyll homepage 4-liner with the GitHub Pages Jekyll docs:

Build location	Reasoning	Instructions
Locally	You'd build local because ...	Here's how (bundler with jekyll gem, yadda ...)
GitHub	You'd let GitHub build your pages because ...	Here's how ... (bundler with github-pages gem, yadda ...)

Other topics that come to mind (as a Jekyll/Ruby noob):

1. Before installation:
   • Homebrew (for those on a Mac)
   • rvm
2. After installation:
   • Using a Rakefile to publish my site.

One-liner install instructions are awesome, but it seems like long-term Jekyll users would end up using the aforementioned tools/techniques anyway. Might as well get them off on the right "best practices" foot, no?

[jglovier]

@metaskills @mislav @mhulse forthcoming outcome not withstanding, I'm just really happy to see everyone leaning into it here. There are absolutely some nominal things that can be done (like updating documentation), and more monumental things that can be done (like installers, etc), all of which will help Jekyll and GH Pages adoption and user satisfaction. To that end, a ❤️-felt +💯.

@mhulse would you care to submit a PR to the Jekyll doc site with some of that info that might belong there? The GitHub Pages section could be a particularly appropriate section to add any of that info that is missing. ✨

I'll see what I can do about adding any of this info that is missing to the GH Pages documentation as well.

[benbalter]

When I was new to Jekyll ('bout a month back now), I kinda wish I found docs right up front that stated (basically):

https://help.github.com/articles/using-jekyll-with-pages#installing-jekyll gets us partially there.

[mhulse]

@mhulse would you care to submit a PR to the Jekyll doc site with some of that info that might belong there? The GitHub Pages section could be a particularly appropriate section to add any of that info that is missing. ✨

Edited:

That's a great idea. I'll look things over this weekend to see if there's anything I can contribute. 👍

https://help.github.com/articles/using-jekyll-with-pages#installing-jekyll gets us partially there.

Actually, that's a good point. The more I think about things, I think the GH docs + Jekyll site really do cover all the bases.

[metaskills]

(maybe you come from a Java or Python background)

@parkr Ouch dude I thought this was a civil discussion :) In all seriousness, I am a self taught programmer (used to be designer and manager) that learned Ruby as my first language.

I like to think I am exceptional in what I do, but my skills are rooted in Ruby and my software career is only about 7 years old. Cheers. I have never touched those languages before either.

EDIT: I also just realized you were not necessarily talking about me when you said "you".

[benbalter]

Perhaps it'd make sense to break installation documentation / packaging / lowering the barrier to entry to its own thread?

[mattr-]

Great idea. Created this new issue for it.

[parkr]

Ouch dude I thought this was a civil discussion

@metaskills The "maybe you come from a Java or Python background" sentence wasn't about you, it was about other users coming to Jekyll from a different language background. Cornell CS & IS teaches Java, Python and OCaml almost exclusively, so Java and Python came to mind when writing that. Sorry it didn't come off that way! Let's keep chatting about it in #1975. 😃