Difficult to use pygments classes

[amr]

Hi,

Jekyll by default uses pygments, and ships with a _syntax-highlighting.scss file. With this configuration...

asciidoctor:
  attributes:
    - hardbreaks!
    - source-highlighter=pygments

... syntax highlighting doesn't work. The reason is that asciidoctor uses a custom tok- class prefix. So all pygments stylesheets do not work by default and must be modified to include the tok- prefix.

Is it possible to tell asciidoctor to not use that prefix?

[mojavelinux]

Interesting, I wasn't aware that Jekyll shipped with a Pygments stylesheet.

As you noticed, Asciidoctor hardcodes the tok- prefix to avoid clashes in class names. I agree this should probably be configurable. Fortunately, there are two workarounds.

(a) First, you can instruct Asciidoctor to inline the styles for Pygments using the setting pygments-css=style (the default is pygments-css=class). The downside with this approach is that you are stuck to colors from the default theme in this case.

(b) Second, you can use Asciidoctor to write the Pygments stylesheet instead of using the one provided by Jekyll. You can do this by calling the following API:

Asciidoctor::Stylesheets.instance.write_pygments_stylesheet '_site/css', 'pastie'

Then, include that stylesheet (e.g., css/pygments-pastie.css) in your main template.

Note the using Asciidoctor's version is important because it provides the necessary styles to override AsciiDoc styling. It's tricky because everyone wants to be king when it comes to styles ;)

Perhaps this is something that could be handled by the Jekyll AsciiDoc plugin transparently. Thoughts?

[robjens]

I had to work around the fact that I wasn't really sure where and how to hack in Ruby/Sass support. I've enabled the Asciidoctor highlight-source and it generates the HTML elements properly, all I had to do was use some sed to inject the front-matter and rename the classes to the convention asciidoctor uses, then I moved it into css folder and adjust _layouts/default.html and changed:

    <link rel="stylesheet" href="{{page.root}}/css/{% if page.pygments-theme %}pygments/{{page.pygments-theme}}{% else %}coderay{% endif%}.css"/>

Now I can just use front-matter variable pygments-theme: mycustomtheme and if there is a file by that name (a custom one, can be easily be copied from the ~10 other scss files). The css/ folder is just easy, since I think it by default compiles sass in there, so no addition to _config. Also, I used https://github.com/dwayne/sass-pygments/ as a starting point for the minor hacks.

We could just add these to the (quickstart) project and be done with it. Since this specific repo doesn't carry any styles whatsoever, quickstart does and has the CSS for a bunch of other vendor libs too. This makes pygments more the exception, than anything else.

If you want, I've got the files and could do a pull request, minor effort.

[robjens]

@amr What do you mean by 'by default'. I tried jekyll new foo, I'm pretty sure i have the latest running. I did a ag pygments in that folder, not a trace.

[mojavelinux]

We could just add these to the (quickstart) project and be done with it.

Sounds reasonable to me. The CodeRay stylesheet was added just because that was Jared's preference, but I think the project should provide both for parity.

[robjens]

Sorry for the late response. I'll have another look at this and submit a pull request if it hasn't been done yet. Thanks for the feedback.

[mojavelinux]

(a) ... The downside with this approach is that you are stuck to colors from the default theme in this case.

Actually, I misspoke. Including the styles inline does still honor the theme.

[mojavelinux]

The integration with Pygments in Asciidoctor really calls for the Pygments stylesheet that Asciidoctor generates (which is backed by the Pygments API, making all the themes in Pygments available). Therefore, I've decide to auto-generate the CSS file into the stylesdir of the source directory if the attributes in the site configuration are configured as follows:

• source-highlighter has the value pygments
• pygments-css does not have the value style
• pygments-stylesheet does not have the value nil (meaning it is not unset)

By default, the stylesheet is written to stylesdir + pygments-stylesheet. If pygments-stylesheet is not set (and not unset), it defaults to asciidoc-pygments.css.

The file will be written if it does not exist or the contents have changed. The Pygments theme is selected by the value of the pygments-style. If this attribute is not set, it defaults to vs.

The file will then get copied to the output directory by Jekyll.

[mojavelinux]

You'll be able to disable this feature in one of two ways. First, you can switch to inline styles:

asciidoctor: 
  attributes:
    - pygments-css=style

Or you can disable the pygments-stylesheet attribute:

asciidoctor:
  attributes:
    - pygments-stylesheet!