Unbelievably difficult to get syntax highlighting working

MaybeThisIsRu commented 7 years ago

Some general background/development environment

Versions:

Ruby: 2.3.0 Middleman: 4.1.10 Middleman-blog: 4.0.1 Middleman-syntax: 3.0.0

Unresolved spec:

WARN: Unresolved specs during Gem::Specification.reset:
      hashie (~> 3.4)
WARN: Clearing out unresolved specs.
Please report a bug if this causes problems.

Snippet from Gemfile.lock

hashie (3.4.4)
middleman-core (4.1.10)
  hashie (~> 3.4)

The problem

As the documentation suggested, I created a _rogue.css.erb file which had the following line in it: <%= Rouge::Themes::ThankfulEyes.render(:scope => '.highlight') %>
Then, I proceeded to include it in my site.css.scss file with @import "_rogue.css", which apparently, results in nothing being added to the built site.css file. In fact, the file is not found on the build. I'm kind of stuck here -- the documentation says create a .css.erb file but exclude it from middleman's build -- but then how do we use it?

Code blocks worked pretty well, almost straight out of the box with the suggested config, even with Slim and in Markdown files. I have spent over 6+ hours trying to get syntax highlighting to work, though. My Gemfile includes:

gem 'middleman-syntax'
gem 'redcarpet', '~> 3.3', '>= 3.3.3'

My config.rb file includes

activate :syntax, :line_numbers => true, :inline_theme => "ThankfulEyes"
set :markdown_engine, :redcarpet
set :markdown, :fenced_code_blocks => true, :smartypants => true

This throws the following error:

undefined method `style_for' for "ThankfulEyes":String

Now, I was able to fix the blog article page by editing my config.rb file to this:

activate :syntax, :line_numbers => true, :inline_theme => Rouge::Themes::ThankfulEyes.new

From what I figured out using hit and trial from Rogue Issue #122. If I understand correctly, passing a string should work fine, but it doesn't?

Now, all the pages work fine (blog, article, tags and calendar).

If this is the intended code, why is the documentation outdated? If this is not the intended code, and passing a string should work, why does it not? What am I doing wrong with the _rogue.css.erb file that prevents it from working at all?

thedanotto commented 7 years ago

Thanks so much for your post, you helped me get this working.

When I added

set :markdown, :fenced_code_blocks => true, :smartypants => true to my config.rb file, I received the error you mentioned

undefined methodstyle_for' for "ThankfulEyes":String`

But your fix fixed it! Not sure why the documentation is so far off?

bhollis commented 7 years ago

The documentation is outdated because time passes and Rogue changes, so things that were correct one day are no longer correct later! A nice way to help out is to submit a PR with updated documentation or a patch to the code to make things work correctly.

MaybeThisIsRu commented 7 years ago

@thedanotto I'm glad it's working for you. I took a sabbatical from code and will be going through this issue again. If you have understood the issue, might it be okay that I seek your help in further understanding the deeper parts?

@bhollis I'll be more than happy to submit a PR. However, that only solves one of my three questions and I feel it would be futile to submit one without really understanding the issue.

To reiterate, if you could help me with these two:

If this is the intended code, why is the documentation outdated?

Right, if this works and is intended, I will submit a PR.

If this is not the intended code, and passing a string should work, why does it not?

This is what I was not clear about with, previously. If the original code requires that a string would work too -- then perhaps we need to figure out another solution.

What am I doing wrong with the _rogue.css.erb file that prevents it from working at all?

This, too, is something I am still unclear with.

bhollis commented 7 years ago

I'm afraid in general I don't have time or inclination to work on this plugin much anymore, since it works for my own use cases, so I have to rely on other folks solving their own problems with PRs.

If there's anything you find confusing about the documentation, or something that doesn't work as you expect, or something that makes this hard to use, then it'd probably help users of this plugin to fix it. I don't really have answers beyond that, since I've pretty much forgotten how it works (and it's mostly a wrapper around Rogue anyway, which changes faster than this does).

vinc commented 7 years ago

Hello,

After reading the documentation, and trying different things for a while, I don't understand how to get the CSS file to work.

After reading this issue I changed my config.rb to include activate :syntax, :inline_theme => Rouge::Themes::Base16::Solarized.new and now it works. Thanks @ruppalsingh!

Inlining the CSS with every code block isn't very pretty but it's better than nothing. Maybe we could start with updating the README to include this fix?

bhollis commented 7 years ago

If there's a problem with the documented approach, a good way to move forward would be a PR that includes a test case showing that it doesn't work. Inline themes as a workaround are not the intended way to use this.

Here's what I have on my website, which has syntax highlighting working nicely. I have a file source/stylesheets/github.css.erb, with the contents:

<%= Rouge::Themes::Github.render(:scope => '.highlight') %>

Then I include that file in my site like this:

<%= stylesheet_link_tag :github %>

Maybe you don't want a separate stylesheet for it though, so I also tested this:

Create a file named source/stylesheets/_github.css.erb.
In my main.css.sass, add @import 'github'.
Now my main stylesheet includes the necessary syntax highlighting styles.

I tried this with both middleman-syntax 2.1.0 and 3.0.0.

bhollis commented 7 years ago

I've updated the README to hopefully make things more clear.

vinc commented 7 years ago

@bhollis thanks for taking the time to test the issue and making the README more clear!

Following your first method, I have now a separate stylesheet working, I didn't try that last time.

But the import directly from the main SASS file doesn't work on my setup. I'm already including _normalize.css without a problem, so maybe it comes from the erb extension. I'll try to see if I can reproduce the issue with a minimal test case, otherwise it'll be hard to do something about it if it's working for you!

bhollis commented 7 years ago

Try doing it exactly like I wrote out. Same file name, same import statement, exactly.

On Jan 23, 2017, at 3:32 AM, Vincent Ollivier notifications@github.com wrote:

@bhollis thanks for taking the time to test the issue and making the README more clear!

Following your first method, I have now a separate stylesheet working, I didn't try that last time.

But the import directly from the main SASS file doesn't work on my setup. I'm already including _normalize.css without a problem, so maybe it comes from the erb extension. I'll try to see if I can reproduce the issue with a minimal test case, otherwise it'll be hard to do something about it if it's working for you!

― You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

mofirouz commented 7 years ago

I've had the same issue as well. I've done exactly as @bhollis has mentioned in his last post (exact file names etc). When I include it in my main stylesheet, the SCSS parser fails to find the find the file and drops everything with a stacktrace and breaks the entire website styling.

The problem (as far as I've yet to understand) is that the syntax stylesheet file is not found.

This is my setup:

Gemfile

gem 'middleman', '>= 4.0.0'
gem 'middleman-asciidoc'
gem 'middleman-livereload'
gem 'middleman-compass', '>= 4.0.0'
gem 'middleman-syntax'

Gemfile.lock

haml (4.0.7)
hashie (3.4.6)
middleman (4.2.0)
middleman-asciidoc (1.0.0.rc.2)
      asciidoctor (>= 1.5.0)
middleman-compass (4.0.1)
      compass (>= 1.0.0, < 2.0.0)
middleman-syntax (3.0.0)
      middleman-core (>= 3.2)
      rouge (~> 2.0)
rouge (2.0.7)
sass (3.4.23)

layout.haml

= stylesheet_link_tag(:github)

config.rb

activate :asciidoc
#activate :asciidoc, attributes: ['source-highlighter=rouge', 'coderay-css=style']
activate :syntax
#activate :syntax, :inline_theme => Rouge::Themes::ThankfulEyes.new

main.scss

/* Setup */
@import "settings";
@import "generic/mixins";
@import "default/normalize";
@import "default/base";
@import "hacks/clearfix";
@import "generic/helpers";
@import "github";

_github.css.erb

<%= Rouge::Themes::ThankfulEyes.render(:scope => '.highlight') %>

swifthand commented 7 years ago

I am having this issue, and first tried the suggested configuration that @mofirouz is also having trouble with. Using the same filenames and locations (_github.css.erb) recommended by @bhollis. The error I receive is:

File to import not found or unreadable: github.

The only difference I can see is that my primary stylesheet is using SCSS syntax instead of SASS syntax?

I have just methodically tried every possible combination of extensions I can imagine, both for the root stylesheet file being built, and for the SCSS partial being included (which consists only of the <%= Rouge::Themes::ThankfulEyes.render(:scope => '.highlight') %> line).

The extensions I have tried are:

.css.erb
.scss.erb
.css.scss.erb

I have also tried each combination with-and-without an underscore in the partial's filename. So all in all 18 combinations.

None of them seem to be able to pick up on the <%= Rouge::Themes::ThankfulEyes.render(:scope => '.highlight') %> code. Not even when I directly paste it into the primary stylesheet, or when I paste it into said stylesheet and rename it with any of the extensions listed above.

The error which shows up the most often is as follows:

Error: File to import not found or unreadable: github.

Which seems to be from the primary stylesheet file failing to find the partial at whatever paths it attempts to check.

The second most common error is:

Error: Invalid CSS after "....highlight') %>": expected "{", was ""

Which seems to be when it finds the partial, but chooses (?) not to parse the partial as ERB.

There are two noteworthy quirks among the 18 combinations I tried.

Quirk One

If I rename the primary stylesheet to have an extension of .css.scss.erb
And name the github partial as github.scss.erb
And reference it via erb <%= partial 'stylesheets/github.scss.erb" %'> rather than @import
Then I can get the ERB pass to succeed, but then all SCSS @import statements in the primary stylesheet fail with a "File to import not found or unreadable".

Quirk Two

If I name the partial _github.css.erb
And I import it via @import "github.css"; in the primary stylesheet.
Then the ERB and SCSS seem to parse/execute successfully, but the resulting stylesheet has the line @import url(github.css); at the top when loaded by the browser, and the browser console shows a 404 for GET http://localhost:4567/stylesheets/github.css.

bhollis commented 7 years ago

If somebody can provide a minimal repo that shows this problem happening, progress can be made on figuring out what the issue is.

vinc commented 7 years ago

I finally tried to setup a minimal test case:

$ middleman init example
$ cd example
$ echo "gem 'middleman-syntax'" >> Gemfile
$ echo "activate :syntax" >> config.rb
$ echo "<%= Rouge::Themes::Github.render(:scope => '.highlight') %>" > source/stylesheets/_github.css.erb
$ echo "@import 'github';" >> source/stylesheets/site.css.scss
$ middleman build

And then:

$ cat build/stylesheets/site.css
/*
Error: File to import not found or unreadable: github.
        on line 25 of /tmp/example/source/stylesheets/site.css.scss

20: 
21: .middleman-logo {
22:   margin-bottom: 1rem;
23:   width: 10rem;
24: }
25: @import 'github';

Backtrace:
/tmp/example/source/stylesheets/site.css.scss:25
/home/v/.rbenv/versions/2.4.0/lib/ruby/gems/2.4.0/gems/sass-3.4.23/lib/sass/tree/import_node.rb:67:in `rescue in import'
/home/v/.rbenv/versions/2.4.0/lib/ruby/gems/2.4.0/gems/sass-3.4.23/lib/sass/tree/import_node.rb:45:in `import'
/home/v/.rbenv/versions/2.4.0/lib/ruby/gems/2.4.0/gems/sass-3.4.23/lib/sass/tree/import_node.rb:28:in `imported_file'
/home/v/.rbenv/versions/2.4.0/lib/ruby/gems/2.4.0/gems/sass-3.4.23/lib/sass/tree/import_node.rb:37:in `css_import?'
...
/home/v/.rbenv/versions/2.4.0/lib/ruby/gems/2.4.0/gems/thor-0.19.4/lib/thor.rb:369:in `dispatch'
/home/v/.rbenv/versions/2.4.0/lib/ruby/gems/2.4.0/gems/thor-0.19.4/lib/thor/base.rb:444:in `start'
/home/v/.rbenv/versions/2.4.0/lib/ruby/gems/2.4.0/gems/middleman-cli-4.2.1/bin/middleman:70:in `<top (required)>'
/home/v/.rbenv/versions/2.4.0/bin/middleman:22:in `load'
/home/v/.rbenv/versions/2.4.0/bin/middleman:22:in `<main>'
*/
body:before {
  white-space: pre;
  font-family: monospace;
  content: "Error: File to import not found or unreadable: github.\A         on line 25 of /tmp/example/source/stylesheets/site.css.scss\A \A 20: \A 21: .middleman-logo {\A 22:   margin-bottom: 1rem;\A 23:   width: 10rem;\A 24: }\A 25: @import 'github';"; }

But my guess is that this has nothing to do with middleman-syntax, I got the same problem for any _example.css.erb or _example.css for that matter. But the import works with _example.scss (though not with _example.scss.erb).

andy-twosticks commented 7 years ago

I have just the same problem. According to this Stack Overflow answer, the problem is that Middleman 4 does not process files starting with an underscore .... which basically means that all partials are bust.

andy-twosticks commented 7 years ago

I now have something of a workaround.

in pry or IRB type:

require "rouge"
File.open("highlighting.scss", "w"){|f| puts Rouge::Themes::ThankfulEyes.render(scope: ".highlight") }

Move the file into your SASS path.
In your main SASS file, put @import "highlighting";

Some things to note about this:

This supports the idea that Middleman 4 ignores files starting with an underscore. Luckily SASS appears to be able to cope with importing files when they don't have underscores. This is not documented AFAICS.
The instructions for middleman-syntax assume that we can dynamically render the SASS and then import it. That appears to be incorrect.
The file we generate is CSS, not SASS, but we need to name it as .scss in order for @import to work.

The only issue here that appears to be a problem with this gem is the installation instructions, I think.

bostonaholic commented 6 years ago

Here is a minimal repo. https://github.com/bostonaholic/middleman-syntax-error

Basically, since middleman 4 doesn't touch sources that start with an underscore (thanks for pointing this out @andy-twosticks), _syntax.scss.erb won't be transpiled from erb -> scss to be picked up by the @import _syntax; in the site.css.scss file.

Probably not a middleman-syntax bug.

markets commented 5 months ago

Going to close this one for now, just pushed some documentation updates (https://github.com/middleman/middleman-syntax/commit/888e1a6590830ef7e6163301d3bd53afa39614c0) following @johnlane's comment. That setup works fine in a new MM v4 generated site

Please, don't hesitate to reopen if you're still experimenting problems following the current docs.

middleman / middleman-syntax

Unbelievably difficult to get syntax highlighting working #67

Quirk One

Quirk Two