Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP

Loading…

Jekyll is eating a particular paragraph only if it's the first paragraph. #1236

Closed
adregan opened this Issue · 20 comments

8 participants

@adregan

I use Jekyll for a little project where I retype 2 pages of Ulysses everyday (http://dailyulyss.es, hosted https://github.com/adregan/ulysses). So far things couldn't be better. However, on Day Seventeen, I have encountered a strange bug that only seems to effect that single post. Jekyll (jekyll serve, jekyll build, github jekyll) does not render the first paragraph— at all, it doesn't exist in the site's code, but it does exist in the markdown file.

A little background. I use the same Rakefile to generate a new post everytime, and I generated Day 17 several times to ensure there wasn't any user error. For the live version, I've gotten around it by inserting a <br> tag in the first line, and this gave me an idea: I placed a random paragraph before the paragraph in question, and it rendered fine as the 2nd paragraph (all paragraphs accounted for).

It's a very strange problem, perhaps there is something in Joyce's writing that Jekyll doesn't like. This is the offending paragraph:

Ineluctable modality of the visible: at least that if no more, thought through my eyes. Signatures of all things I am here to read, seaspawn and seawrack, the nearing tide, that rusty boot. Snotgreen, bluesilver, rust: coloured signs. Limits of the diaphane. But he adds: in bodies. Then he was aware of them bodies before of them coloured. How? By knocking his sconce against them, sure. Go easy. Bald as he was and a millionaire, maestro di color che sanno. Limit of the diaphane in. Why in? Diaphane, adiaphane. If you can put your five fingers through it, it is the gate if not a door. Shut your eyes and see.

What on earth is it about this paragraph that Jekyll doesn't like?

@adregan

Alright. So it's nothing as nefarious as Jekyll adopting a distaste for Joyce, which would have been really interesting. The problem appears to be the colon in the first line. If I escape the colon \:, everything works as it should. However, this colon is squarely outside of the YAML header:


layout: post
title: Day Seventeen
date: 2013-06-21 19:14:45
published: true


Ineluctable modality of the visible: at least that if no more, thought through my eyes.

so why is it causing trouble?

@maul-esel

Just guessing, but does escaping / quoting the colons in the date solve the issue?

@parkr
Owner

@adregan You need to have a newline after your YAML:

---
layout: post
title: Day Seventeen
---

Ineluctable...

In your example above, it doesn't look like it's formatted this way.

@adregan

Yes escaping the colon does help, and I have also added the extra line. So:

I have just switched to RDiscount after reading Issue 127 and Issue 126. Apparently this is a problem with Maruku. It can't handle a colon on the first line. Problem solved. Go figure.

So that leads me to a new question: Are there any unforeseen issues with using RDiscount? Why does Maruku happen to be the default of the Jekyll project?

@adregan

Here is the issue over on the Maruku project. When they release 1.0 this feature will be off by default.

@parkr
Owner

No unforeseen issues using RDiscount of which I am aware. RedCarpet is probably the best (and fastest) parser, so if RDiscount gives you headaches, try RedCarpet. MaRuKu isn't the default for any particular reason. It was chosen way back when and we haven't modified the default since then.

@parkr parkr closed this
@davecranwell

One of my live Jekyll sites on Github Pages recently ceased compiling due to what maruku deemed as a missing line-break between two sibling ul elements in a markdown file. The html was 100% valid, flawless even :P but maruku complained about the uls not having a blank line between them. Ridiculous.

Prior to Github Pages upgrading their Jekyll version, eveything was fine.

If you're saying Maruku isn't actually that great, and that redcarpet is so much better (I've switched to redcarpet and not only is it faster, but far less precious about that missing line break) wouldn't it be worth replacing the dependency on maruku, with redcarpet in the gemspec?

@parkr
Owner

@davecranwell We're sunk into MaRuKu at this point. It's the default for thousands of users and if we switched all of a sudden, there would be a lot of broken sites.

Imagine that you have a site that you've been editing with prose.io on GitHub Pages. You don't test whether your site compiles on your local machine: it's just easier to make your edits on prose and push to GitHub and let GitHub do the heavy lifting. You're happily using the default, as you have no ul tags and you haven't hit any of the other downsides of MaRuKu. Now imagine that we update Jekyll and GitHub Pages to use RedCarpet. Next time you go to edit your site and push to GitHub, your site doesn't change like it normally did. You go make another edit to double-check that it's indeed not a problem with Prose. You see your updates on GitHub just like normal but your site still isn't building. You finally clone down your repo, install Jekyll and run it yourself. You're now getting some esoteric error about some markup you have that used a MaRuKu feature that RedCarpet doesn't support and doesn't have a replacement for. The error, of course, is super cryptic and you don't recognize that you're using a new markdown parser because you just used the default. Why did it stop working all of a sudden? You go to Google and StackOverflow for answers but you can't find anything. You finally write a ticket on mojombo/jekyll in hopes that someone else knows what's up and a day later you get a response that the default changed from MaRuKu to RedCarpet and that you need to modify your _config.yml file in order to get the old behaviour back. So now you're out a day's worth of work just because the dev team likes RedCarpet more than MaRuKu, and you're frustrated as hell about it.

Now multiply this times a couple thousand and you have yourself the scale of frustration that the change in default will cause. It seems like such a simple change, but the ramifications are enormous.

@davecranwell

Hmm, good point well made.

Perhaps instead add a section on good/better/best markdown interpreters to the docs?

There's already a section on RDiscount in the "Extras" section, but this comes rather late in the day in a section less will read during their initial learning period. Will send a pull request.

@parkr
Owner

Great, thanks man :)

@zachgersh

@parkr you think this is something we could consider for 2.0 ie switching the default markdown parser?

@parkr
Owner

@zachgersh I don't think we can ever switch it. Maybe @benbalter has a different take, but from what I understand about Jekyll's UX, it'd be best not to change it.

@benbalter
Owner

TL;DR: Build software for everyday users, not computer scientists.

This was touched on a bit in #1113. If Jekyll were an internal software library (like Maruku or Rails or Sinatra), it wouldn't be a problem. You could assume the 80% use case was sophisticated developers who understand and respect the nuances of semantic versioning, can debug breaking changes rather quickly, and most importantly, either vendor or version their software in a Gemfile. A breaking change is fine because I just won't update the Gem, and besides, my release cycle is quarterly, so I'll just deal with it before the next release.

But that's not Jekyll. Jekyll's my website. My release cycle is daily. Sometime hourly. I chose Jekyll over something heavyweight like WordPress or Drupal because I crave simplicity. I don't want to have to worry about what version of Maruku I'm running, or what my Markdown pre-processor is, or if somebody updated a plugin on wordpress.org that isn't compatable with my theme. I just want it to work. This is my website we're talking about, not an open source software project I maintain on the side.

This is true for both Jekyll I host on S3 and GitHub pages hosted users. A year ago, if I ran jekyll build and all of a sudden my site didn't build because a week ago I ran bundle update in a different folder (after all, I'm probably not using .rvmc... why would I need something so complex if Jekyll's the only Ruby app I use -- true story), I'd be pretty confused. And it's not like read_inline_code': undefined method[]' for nil:NilClass (NoMethodError)` (#1105) tells me anything. And the problem's worse for GitHub pages as @parkr outlined.

Maybe we all agree that Maruku is not the best thing since sliced bread. But it works. And people rely on it. And less than perfect is a lot better than a bunch of people on the internet breaking my site and causing me a lot of grief because something called "semantic versioning" gave them permission to.

Drupal introduced breaking changes with every version, and as a result, two things happen: 1) people rarely update, because it's like playing Russian Roulette with your site, and 2) it's relegated to a small cadre of highly technical users with formal computer science backgrounds. Compare that with WordPress, which absorbs all the complexity for the user, and as a result, something crazy like 1/4 of the Internet from large companies to grandparents can get behind it because they know there's a mutual respect there. They know they can trust it.

I'm :+1: for moving away from Maruku, but we'd have to do it with norms, not with breaking changes. Let's set the parser in _config.yml of jekyll new. Let's encourage things in the documentation. Lets fix Maruku upstream. Let's educate users. There's lots of ways to do this without breaking things in the process.

@benbalter
Owner

Also, can any of the other renderers support passing attributes (e.g., class name) to block level elements without dropping into HTML?

@parkr parkr referenced this issue from a commit
Commit has since been removed from the repository and is no longer available.
@zachgersh

@benbalter did I just get served? :smile: point well taken though and I agree. I also agree wholeheartedly with all the suggestions you make at the end.

@mattr-
Owner

clap

@ms-ati

May I suggest: When Maruku is enabled, and version is <= 1.0 (or whatever version finally has the colon thing off by default), why doesn't Jekyll simply feed Maruku the markdown content with a newline \n prepended?

As mentioned here:
bhollis/maruku#16 (comment)

Wouldn't this just neatly solve the issue, even when using Maruku? Pardon me for being slightly annoyed, but having your first paragraph mysteriously disappear is very frustrating.

@parkr
Owner

@ms-ati That's a good idea, we might be able to do that before MaRuKu is patched. It's such a pain... Sorry guys!

@parkr parkr reopened this
@parkr
Owner

Keeping with our philosophy of not breaking functionality that's already there, we cannot prepend the content with a newline, as MaRuKu actually allows you to specify some metadata on your first line. If we were to prepend the content with a newline, we would break this functionality for some folks who might be using it - that's not something I'm comfortable doing.

Check this out for more details: bhollis/maruku#16

@parkr parkr closed this
@ms-ati

This is a lol for me, @parkr.

  1. How many people have/will be bitten by a colon in first paragraph?
  2. How many people intentionally use this Maruku feature via Jekyll?

Seems like an easy opportunity to add a config option for the newline, and default it to on. If there actually are any people on group 2 above, it will be straightforward to inform them to turn on the new option.

However, the amount of people losing their first paragraphs will drop to zero.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Something went wrong with that request. Please try again.