About

Add syntax highlighting to code snippets in your Orchid site. Supports pre-rendered highlighting with Pygments, browser-based highlighting with PrismJS, and runnable Kotlin code snippets with Kotlin Playground.

Installation

dependencies {
    orchidRuntime("io.github.javaeden.orchid:OrchidSyntaxHighlighter:0.21.2")
}

<dependency>
    <groupId>io.github.javaeden.orchid</groupId>
    <artifactId>OrchidSyntaxHighlighter</artifactId>
    <version>0.21.2</version>
    <type>pom</type>
</dependency>

libraryDependencies += "io.github.javaeden.orchid" % "OrchidSyntaxHighlighter" % "0.21.2"

@file:DependsOn("io.github.javaeden.orchid:OrchidSyntaxHighlighter:0.21.2")

Demo

public class HelloWorld {
    public static void main(String[] args) {
        // Prints "Hello, World" to the terminal window.
        System.out.println("Hello, World");
    }
}

1 public class HelloWorld {
2     public static void main(String[] args) {
3         // Prints "Hello, World" to the terminal window.
4         System.out.println("Hello, World");
5     }
6 }

Usage

Pre-rendered Highlighting

The highlight Template Tag, which will highlight your code using Pygments. Pygments supports many languages out of the box for you with no additional configuration. Pre-rendered highlighting has the advantage of still working in an environment with JS disabled, such as the PDFs generated by the Wiki plugin.

{% highlight 'yaml' %}
title: 'Page Title'
components:
  - type: pageContent
{% endhighlight %}

This plugin includes a default stylesheet for Pygments, which must included in your theme for highlighting to work properly. Simply adding assets/css/pygments.scss in your extraCss is all that's needed, to use the default styling.

theme:
  extraCss: 
    - 'assets/css/pygments.scss' # this file is already available in the plugin's resources

Alternatively, you are free to use your own Pygments theme by creating and adding the necessary stylesheet.

theme:
  extraCss: 
    - 'assets/css/custom-pygments-theme.scss' # you'll need to create this file yourself

In-Browser Highlighting

Alternatively, you may opt for a browser-based solution using PrismJS. This may offer greater flexibility and works with the normal Markdown syntax, but requires Javascript to function. You will also need to manually add language definitions for each language you intend to highlight, which may not be feasible for sites which need many languages highlighted. This component is best added in an Archetype, such as allPages.

allPages:
  metaComponents:
    - type: 'prism'
      languages: 
        - 'java'
        - 'kotlin'
        - 'yaml'

Kotlin Playground

The Kotlin Playground allows you to convert Kotlin code snippets into playgrounds that are runnable right in your browser. The kotlinPlayground component adds the script from their CDN, which will select all elements on the page with your runnable Kotlin code and convert them into embedded runnable playgrounds. By default, all Markdown code snippets with a language of run-kotlin are converted.

allPages:
  metaComponents:
    - type: 'kotlinPlayground'
      selector: "pre code[class='language-run-kotlin']"

You can configure each individual playground using the attributes described in the Kotlin playground docs. These can be added from Markdown snippets with the following syntax:

```run-kotlin
fun main() {
   println("Running from Kotlin Playground!")
}
```
{theme='darcula' lines='true'}