I use syntax highlighting in my editor environment. Most modern editors enable syntax highlighting and come with a couple of themes by default; most online code-sharing platforms (like GitHub, GitLab, or Gitea) provide this feature out of the box.
By way of an example, syntax highlighting turns this:
… into something like this:
Grav, my current CMS, already has two plugins to do this on the client side:
- Prism Highlighter, which uses Prism.js; and
- Highlight, which uses (surprise!) highlight.js.
Features I’d like
- syntax highlighting
- pick a theme from the admin panel
- shortcode support
- code blocks & inline code samples
Boom. Super high-level todo list done. Time for a little more refinement.
Choosing a library
I suppose I could try to write a syntax highlighter from scratch, but that would be a foolish waste of time. (Unless the goal were to learn how to do exactly that — parsing, keywords, etc. That is not the goal.) Plenty of server-side syntax highlighting libraries exist already. I’ll use one of those.
I could use pygments, rouge, or chroma, using
exec to integrate the
output of those programs in with PHP’s templating. The PHPygments library
takes this approach. Since the intent is to release this on the Grav plugin
repositbory, I’d prefer to not require a user to have to necessarily hop into a
terminal session, check a Python version, etc. Doing so might even total
preclude people from using the plugin in shared hosting environments.
For pure PHP libraries, I found two options:
GeSHi looks pretty robust, and highly customizable. It’s not immediately clear how actively developed it is, with several items on its issue tracker still open and last updated nearly 10 years ago. highlight.php, on the other hand, has a small but pretty healthy community at GitHub, and last had an update this summer. It’s available under the quite permissive BSD 3-Clause License, so no problems there.
Picking a theme from the admin panel
This will cover on Grav’s Blueprints. I’ll start with hardcoding a couple of
themes, then take the opportunity to learn about using the
to dynamically populate the theme options provided by the highlight.php library.
Shortcodes are shorthand — a kind of parameterized text expander that runs when templates are compiled and evaluated. I think WordPress popularized them, based on BBCode markup syntax. Plenty of other CMSs support them now, both in PHP-land (WordPress, Craft, and Perch among others) and in static site generators (Hugo, Eleventy, and Nikola among others).
The Grav core dev team already maintains the shortcode core plugin, so the heavy lifting of Grav integration is done. I’ll extend that work. (Literally, using a subclass.)
Wrapping up the planning phase
Okay, given that:
- what I want doesn’t already exist,
- a suitably licensed PHP-only syntax highlighter does exist,
- Grav’s architecture favours plugins, and
- implementing custom shortcodes built on some excellent work is relatively trivial,
… I feel confident to proceed with the plugin project. As for planning the how to break up these posts, I’m thinking:
- this post
- planning out how the shortcode syntax will work
- setting up the development environment
- writing the plugin: shortcode/syntax highlighting bits
- writing the plugin: blueprint/admin panel bits
- writing the documentation, etc.
- finishing up: going through the plugin release process