Drop support for pygments as syntax-highlighter

[ashmaroli]

Resolves #6823

• stop testing output from the use of Pygments as syntax highlighter
• maintain API for handling Pygments so that a plugin can easily hook into, if needed in future.
  e.g. The plugin would just have to override HighlightBlock::render_pygments to provide the functionality.

[pathawks]

This is a pretty clever idea 💡👍🏼

[crispgm]

👍And do u forget the Gemfile?

[ashmaroli]

..u forget the Gemfile?

@crispgm Ah yes, I did..!! Thanks 👍

[DirtyF]

Our docs should reflect that change https://jekyllrb.com/docs/templates/#code-snippet-highlighting
There's also a mention in a tutorial: https://jekyllrb.com/tutorials/orderofinterpretation/#markdown-in-include-file-not-processed

[ashmaroli]

Our docs should reflect that change

I left that out intentionally since our docs are not versioned.. I believe that a 4.0 change should not be included in the current docs.

[DirtyF]

@ashmaroli right, it was more of a reminder. Maybe we could keep a list of changes to make to the docs before the release instead?

[ashmaroli]

Maybe we could keep a list of changes to make to the docs before the release instead?

Yes. Exactly what I was thinking..
My plan currently is as follows:

• Create branch docs-40
• Update docs as required either by us (or the contributor theirself)
• merge into release-4.0 when its time

[pathawks]

Maybe it would be best if we didn't work on 4.0 on master. That way, we could continue to update docs right along changes to code.

Or, we could create a new branch for the live site. GitHub Pages would build from that branch, and master would get all the 4.0 docs changes. Then when 4.0 is released, we point GitHub Pages back to master and delete the other branch.

[ashmaroli]

I feel like I've encountered a stalemate..

Maybe it would be best if we didn't work on 4.0 on master

Now that we've started working on 4.0 I no longer feel the benefits of working on a 4.0-dev especially since JekyllBot commits PR merges to master. Its probably only going to be an additional overhead on the maintainers..

Or, we could create a new branch for the live site

This is an additional overhead for us to maintain a temporary site source on the gh-pages branch with no significant gain..

[pathawks]

Or, we could create a new branch for the live site
This is an additional overhead for us to maintain a temporary site source on the gh-pages branch with no significant gain..

I worry that having a bunch of open docs PRs that must be kept up-to-date with code changes and that must be kept relatively free of merge conflicts and that cannot be merged until the day 4.0 launches would be far more overhead.

[ashmaroli]

that must be kept up-to-date with code changes and that must be kept relatively free of merge conflicts and that cannot be merged until the day 4.0 launches would be far more overhead.

True.. true.. true..

[pathawks]

This should probably fail the build, right?

Otherwise, folks who use (ie) GitHub Pages will just stop having syntax highlighting in their code with no clue as to why, and that is if they notice.

[ashmaroli]

yeah.. that's true..
I'd prefer users to keep abreast with changes in a major version and check for any warnings in their terminal output instead of getting a Page Build Error email from GitHub Pages..
but that's just me..

People just don't have the time to do a local run first.. 🙂
I'll update it to raise instead

[ashmaroli]

@pathawks Or... should we silently fallback to highlighting with Rouge? 💡

[DirtyF]

@ashmaroli if there is no compatibility issue between the two highlighters, this could be the nicest solution for all users.

[ashmaroli]

From the README at jneen/rouge:

Its HTML output is compatible with stylesheets designed for pygments.

If there's still a need for using pygments explicitly, the community can build a plugin which will be able to easily hook into the render method here.

[DirtyF]

Rouge::Formatters::HTMLPygments.new(formatter, css_class='codehilite') wraps the given formatter with div wrappers generally expected by stylesheets designed for Pygments

[ashmaroli]

@oe @pathawks Any updates on this..?

[pathawks]

Where are the changes to documentation? How did we decide to handle that?
Do we need a separate PR for that, and maybe a 4.0-docs milestone or something similar?

[ghost]

We could hide 4.0-specific doc changes behind a flag that we enable once the release has been done? I'm also not too into the idea of keeping a whole separate branch or lots of open PRs.

[ashmaroli]

hide 4.0-specific doc changes behind a flag that we enable once the release has been done

@oe Such a flag doesn't currently exist.
One solution is use Liquid to output 4.0 relevant changes only when site.version >= 4.0

{% if site.version >= 4.0.0 %}
  Documentation for Jekyll 4.0
{% else %}
  Existing documentation
{% endif %}

/cc @DirtyF what say?

[ashmaroli]

This PR seems to gathered a lot of noise. I'm going to close this in favor of a new one.