New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Fenced backtick code highlighting using GFM #2709

Closed
rogeralsing opened this Issue Aug 7, 2014 · 18 comments

Comments

Projects
None yet
@rogeralsing
Copy link

rogeralsing commented Aug 7, 2014

So I've been fighting with Jekyll for a week now to get it to render my github wiki pages in a proper way on my github pages site.

The only markdown renderer that I have successfully got to render highlighted backtick code is redcarpet

The kramdown renderer has GFM support (?) there is an input: GFM option, this does not seem to have any effect on the output.

So what renderer am I supposed to use to get as close to the original github format as possible?

kramdown's GFM support seems broken, and redcarpet is somewhat picky and wants extra linebreaks before fenced backtick code, while github itself does not need that.

@kleinfreund

This comment has been minimized.

Copy link
Contributor

kleinfreund commented Aug 7, 2014

I use backtick code blocks with kramdown and it does work:

kramdown:
  input: GFM

What problem do have specifically with kramdown and code blocks?

@rogeralsing

This comment has been minimized.

Copy link

rogeralsing commented Aug 7, 2014

Apparently, github uses two different styles of markdown.
one for md files in repos and issues etc. and one for the wiki..
e.g. #foo is a header in the wiki and not a header in the rest of github.
So some of my problems was due to ill formed md.

However, I'm unable to get any sort of highlighting to work with kramdown.
is highlighter: pygments supposed to be enough? that works for redcarpet, but it has no effect on kramdown.

@pathawks

This comment has been minimized.

Copy link
Member

pathawks commented Aug 7, 2014

It should work.
Can you post a specific example of something that's not working, or (better yet) a link to your repo?

@rogeralsing

This comment has been minimized.

Copy link

rogeralsing commented Aug 7, 2014

Live using kramdown: http://akkadotnet.github.io/wiki/The%20Obligatory%20Hello%20World
site repo: https://github.com/akkadotnet/akkadotnet.github.com

The example above is rendered as:

<pre><code class="language-csharp">//Create an (immutable) message type that your actor will respond to
public class Greet
{
    public Greet(string who)
    {
        Who = who;
    }
    public string Who { get;private set; }
}
</code></pre>

That is, no tokenization of the code inside, redcarpet with pygments applies all the css classes one would expect.

Also, whats up with the #### headers , those should be headers in GFM, right?

@kleinfreund

This comment has been minimized.

Copy link
Contributor

kleinfreund commented Aug 7, 2014

They are headers in Markdown in general, but also in GFM.

# Heading (H1)

This should work. If it does not, you have a different issue.

@rogeralsing rogeralsing changed the title GFM support? Fenced backtick code highlighting using GFM Aug 7, 2014

@pathawks

This comment has been minimized.

Copy link
Member

pathawks commented Aug 7, 2014

From gettalong/kramdown#68...

@konklone

Notably though, this feature doesn't do any syntax-specific highlighting (e.g. Pygments) itself

@plexus

Syntax highlighting in Kramdown is done with coderay. If you set the enable_coderay option to true you should get HTML with actual syntax highlighting.

@rogeralsing

This comment has been minimized.

Copy link

rogeralsing commented Aug 7, 2014

I found this SO answer:
http://stackoverflow.com/questions/19332876/is-it-possible-to-use-coderay-in-github-pages

So the short anser is:

  • kramdown cant use pygments
  • coderay doesnt work on github pages?
@pathawks

This comment has been minimized.

Copy link
Member

pathawks commented Aug 7, 2014

I'll point out that {% highlight %} works great with kramdown and Github pages.

@parkr

This comment has been minimized.

Copy link
Member

parkr commented Aug 8, 2014

I'll point out that {% highlight %} works great with kramdown and Github pages.

👍

In general our syntax highlighting needs a huge overhaul. We have Pygments and Rouge injected into places within Jekyll that would make Robert Louis Stevenson blush. It's an absolute mess. Most of our markdown converters find all the <pre> tags and use gsub (can you believe it?!) to provide some sort of highlighting. Few of the markdown libraries we use offer support for plugins, so we're a little dead in the water. We've been asked to match what GitHub is doing and we've bent over backwards to accomplish that. Unfortunately, it's left us in this present quandary.

I think the path going forward is to ask markdown libraries to give us some means to work with their internal AST's (or whatever it is they build) to manipulate the code and pre tags to our liking. I have a strong urge to rip out all syntax highlighting in everything but the {% highlight %} tag and ship highlighting when it's ready from the Markdown library side (i.e. kramdown, RDiscount, RedCarpet).

We may be able to use HTML Pipeline to port GitHub's Markdown approach, but we'll need a bit of assistance from them to put it all together in a useful way.

@mattr-

This comment has been minimized.

Copy link
Member

mattr- commented Aug 9, 2014

Please correct me if I'm wrong (and I often am), if I understand you correctly, you're trying to share wiki pages from GitHub on a GitHub Pages site. Considering two different projects power the implementation behind the two different tools, I feel like you'll continually struggle with this.

Redcarpet is what will give you the closest approximation to GFM due to the fact that, for a time, it was the GFM renderer for GitHub itself. They've since switched to a more stripped down version of the same code base. If you're using some of the newer features of GFM (i.e. task lists), they won't work with any markdown renderer, as far as I know.

@mattr- mattr- closed this Aug 9, 2014

kansaichris referenced this issue in kansaichris/kansaichris.github.io Nov 17, 2014

Andersos pushed a commit to Andersos/andersos.net that referenced this issue Jan 3, 2015

@barryclark barryclark referenced this issue Jan 11, 2015

Closed

Adjustments #73

@rofr

This comment has been minimized.

Copy link

rofr commented Aug 23, 2015

Is there a workaround for this? I'd like to write markdown using fencing, preview in atom using markdown preview package and have it rendered with syntax highlighting correctly on github-pages.

@rajohns08

This comment has been minimized.

Copy link

rajohns08 commented Aug 23, 2015

+1 @rofr

@pathawks

This comment has been minimized.

Copy link
Member

pathawks commented Aug 23, 2015

This issue was closed a year ago, what are you expecting to have resolved?

@304NotModified

This comment has been minimized.

Copy link

304NotModified commented Sep 2, 2015

+1 @rofr

Not sure why this is ever closed. No fixes. No work arrounds.

@plexus

This comment has been minimized.

Copy link

plexus commented Sep 3, 2015

I assume this issue is closed because it's not a Jekyll issue. There is no authoritative spec for Markdown. Github has their own extensions, and even renders the same input differently depending on if it's comments, files, gists, etc.

Some implementations have partially copied some of the Github extensions. For Kramdown I implemented bactick-fenced code blocks, and rendering newlines as line breaks. If you want highlighting in the codeblocks you can either use Coderay on the server side, or use something javascript-based like highlight.js.

If you want more of these Github-specific extensions in a specific implementation then start a conversation for the relevant project. State what features you want to see, and if you plan to implement them yourself or not, and then ask if the project maintainers would accept such a pull request. If they do, then write the code, ask for feedback, incorporate that feedback, until the PR is merged.

If that's done and the changes are part of a new stable release, then you can consider coming back to Jekyll to suggest they update their dependencies. Until then +1-ing here will not make a difference.

@304NotModified

This comment has been minimized.

Copy link

304NotModified commented Sep 3, 2015

Well, it's no problem to close a ticket and telling Jekyll wont support code fences.

But closing an issue without making really clear why, well, that confuses people and those will give +1's because the issue isn't fixed.

There is a spec for GFM AFAIK. So setting the input on GFM, should support the GFM features IMO.

@envygeeks

This comment has been minimized.

Copy link
Contributor

envygeeks commented Sep 3, 2015

It is not our job to work around the problems of a markdown processor, I know you would like that to be so but that is on the maintainer of that library. If you enable GFM in Kramdown and it doesn't work the way you expect, that is a bug in Kramdown, not in Jekyll. If you enable fenced code blocks (which you can if you read: https://github.com/jekyll/jekyll/tree/master/lib/jekyll/converters/markdown) and it doesn't work that is a problem with Redcarpet. There are clearly documented ways to work around this and if those ways do not work then that is a bug in Jekyll unless... it's because Redcarpet or Kramdown or the markdown library removed the feature or it's broken there but necromancing a ticket instead of checking the documentation and blaming us isn't going to solve the problem.

Please try to read the documentation and see if that works, if it does not then please file a ticket and we'll gladly debug the issue and let you know if it's an upstream problem.

@parkr

This comment has been minimized.

Copy link
Member

parkr commented Sep 3, 2015

If GFM input for Kramdown doesn't support a feature, please ask the Kramdown authors to add this feature.

@jekyll jekyll locked and limited conversation to collaborators Sep 3, 2015

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.