Option to fallback to HighlightJS #120

wants to merge 15 commits into


None yet
6 participants

This adds a command-line option to specify the highlighter used.

By default, Pygments will be used but if it is not detected on the system or the user has specified "highlightjs", that will be used instead. The default CSS now contains styles for both types of marked-up code.

I've submitted a pull request to highlightJS to improve the detection and highlighting of coffee-script and include a Docco style.

This should maintain compatibility with existing usage and any custom CSS while making the python requirement optional.

Simon Madine and others added some commits Oct 2, 2012

Simon Madine Replaced Pygment with HighlightJS 57e7097
Simon Madine Moved from 'highlight' to official 'highlight.js' module
'highlight.js' is actively maintained and has coffeescript support.
@thingsinjars thingsinjars Update README ff75885
@thingsinjars thingsinjars Update README 2b4154a
@thingsinjars thingsinjars Update README 9fca00c
Simon Madine Detecting whether the user has Pygments installed and falling back to…
… highlightJS if not
Simon Madine Added command-line option to choose highlighter
If no highlighter is specified, it checks to see if Pygments is
available. If it is, it uses that, if not, it falls back to HighlightJS
@thingsinjars thingsinjars Added highlighter choice to command-line options cbeb88c

keithamus commented Oct 9, 2012

While I like the idea of removing the coupling to Pygments, I won't be able to include this patch for a few reasons:

  1. HighlightJS is very specific to NodeJS, which means all of the ports cannot use it.
  2. It adds another dependency to the project which goes against @jashkenas's idea of quick-and-dirty
  3. It is a breaking change, considering HighlightJS is now the default, meaning users now need to change their build scripts to use Pygments.

We really appreciate your work on this though, and would love to see more from you!

keithamus closed this Oct 9, 2012

Fair enough, no probs. For point 3, HighlightJS is only the default if Pygments is not available on the system already. Users who are already using it wouldn't need to change anything to continue.

Thanks for looking, though.

Massimiliano Marcon and others added some commits Oct 9, 2012

@keithamus Why is it better to depend on Pygments & Python for all the ports rather then on HighlightJS & Node? Besides if one switches completely to HighlightJS the code is shorter and cleaner and for docco it's only a npm dependency which is much smaller compared to a Python dependency.


keithamus commented Jan 1, 2013

@dignifiedquire et al: HighlightJS offers no binary which means it cannot be used as a drop in replacement for Pygments, meaning any port would have to involve some kind of JS to negotiate the use of HighlightJS. Pygments can be executed from the command line, making it flexible enough to be utilised from almost any programming language.

Any code which is added to Docco also needs to be feasible additions to the various Docco ports (such as Rocco, Shocco, Pycco and Locco). As described in my previous comment, point 1, HighlightJS is not an language agnostic feature. I agree with you though; for Docco, HighlightJS might be the simpler choice as it is "only an NPM dependency" - but "only an NPM dependency" doesn't translate well for the Python or Ruby port of Docco, for example.

The reason why HighlightJS will never be used as part of docco is because it breaks 2/3 of the Docco directives:

  1. To Be Quick and DIrty - ✓ ("only an NPM dependency")
  2. To introduce as few dependencies as possible - ✗
  3. To be cross compatible with all ports - ✗

jashkenas reopened this Jan 18, 2013


jashkenas commented Jan 18, 2013

Actually -- I don't see any problem with using Highlight instead of Pygments for Docco ... as long as there's high quality CoffeeScript grammar support and syntax highlighting in it. The ports can do whatever they thing best, but switching to a JS highlighter would remove the largest and most error-prone stumbling block to getting started with Docco.

@jashkenas My thoughts exactly. Having a cli python tool is a big hurdle for anyone getting started who hasn't full control over his environment. Imo it's just dirty not very quick especially to install.

I think it would be better to either stay on pygments or completly switch to highlight.js because supporting two deps for the same thing isn't anywhere near quick and dirty anymore


jashkenas commented Mar 13, 2013

Thanks a million for the implementation. Just merged a version of this. Now the Highlight.js syntax for CoffeeScript just needs a little more love...

jashkenas closed this Mar 13, 2013

chakrit referenced this pull request Mar 21, 2013


Error with Makefile. #173

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