Swiftpack.co - Package - JohnSundell/Splash


Swift Package Manager Mac + Linux Twitter: @johnsundell

Welcome to Splash - a fast, lightweight and flexible Swift syntax highlighter. It can be used to generate code sample HTML for a blog post, to turn a string of Swift code into a fully syntax highlighted image, or to build custom developer tools.

It's used to highlight all articles on swiftbysundell.com.


Splash can be used either as a library in your own Swift Package Manager-powered tool or script, or by using one of the four built-in command line tools that act as frontends for the Splash library.

๐ŸŒ On the web

Thanks to my good friend Gui Rambo, you can try out Splash directly in your browser! His web tool lets you use Splash to generate either HTML or an image, by simply pasting Swift code into a text box.

๐Ÿ‘‰ splash.rambo.codes

If you're using Publish, then there's an official plugin that makes it easy to integrate Splash into your website:

๐Ÿ‘‰ SplashPublishPlugin

If you're using Jekyll, there's also a custom {% splash %} tag available for the Liquid templating language.

๐Ÿ‘‰ splashtag

๐Ÿ–ฅ On the command line

The easiest way to get started building things with Splash is to use one of the four built-in command line tools that each enable you to use Splash in different ways.


SplashHTMLGen uses Splash's HTML output format to generate an HTML string from Swift code. You simply pass it the code you want to highlight as an argument and HTML is returned as standard output.

For example, if you call it like this:

$ SplashHTMLGen "func hello(world: String) -> Int"

You'll get the following output back:

<span class="keyword">func</span> hello(world: <span class="type">String</span>) -> <span class="type">Int</span>

To be as flexible as possible, Splash doesn't hardcode any colors or other CSS attributes in the HTML it generates. Instead it simply assigns a CSS class to each token. For an example of a CSS file that can be used to style Splash-generated HTML, see Examples/sundellsColors.css.

When rendering your outputted html, make sure to wrap your output code in the <pre> and <code> tags and properly link to your .css file. Like this:

<!DOCTYPE html>
    <title>Hello World</title>
    <link rel="stylesheet" href="sundellsColors.css">

        <span class="keyword">func</span> hello(world: <span class="type">String</span>) -> <span class="type">Int</span>

For more information about HTML generation with Splash and how to customize it, see HTMLOutputFormat here.


SplashMarkdown builds on top of SplashHTMLGen to enable easy Splash decoration of any Markdown file. Pass it a path to a Markdown file, and it will iterate through all code blocks within that file and convert them into Splash-highlighted HTML.

Just like the HTML generated by SplashHTMLGen itself, a CSS file should also be added to any page serving the processed Markdown, since Splash only adds CSS classes to tokens โ€” rather than hardcoding styles inline. See the above SplashHTMLGen documentation for more information.

Hereโ€™s an example call to decorate a Markdown file at the path ~/Documents/Article.md:

$ SplashMarkdown ~/Documents/Article.md

The decorated Markdown will be returned as standard output.

Highlighting can be skipped for any code block by adding no-highlight next to the blockโ€™s opening row of backticks โ€” like this: โ€œ```no-highlightโ€.


SplashImageGen uses Splash to generate an NSAttributedString from Swift code, then draws that attributed string into a graphics context to turn it into an image, which is then written to disk.

For example, if you call it like this:

$ SplashImageGen "func hello(world: String) -> Int" "MyImage.png"

The following image will be generated (and written to disk as MyImage.png):

Code sample

SplashImageGen is currently only available on macOS.


The final built-in command line tool, SplashTokenizer, is mostly useful as a debugging tool when working on Splash - but can also be interesting to use in order to see how Splash breaks down code into tokens. Given a string of Swift code, it simply outputs all of its components (excluding whitespaces).

So if you call it like this:

$ SplashTokenizer "func hello(world: String) -> Int"

You'll get the following standard output back:

Keyword token: func
Plain text: hello(world:
Type token: String
Plain text: )
Plain text: ->
Type token: Int

๐Ÿ“ฆ As a package

To include Splash in your own script or Swift package, add it as a dependency and use the SyntaxHighlighter class combined with your output format of choice to highlight a string of code:

import Splash

let highlighter = SyntaxHighlighter(format: HTMLOutputFormat())
let html = highlighter.highlight("func hello() -> String")

Splash ships with two built-in output formats - HTML and NSAttributedString, but you can also easily add your own by implementing the OutputFormat protocol.


Splash is distributed as a Swift package, making it easy to install for use in scripts, developer tools, server-side applications, or to use its built-in command line tools.

Splash supports both macOS and Linux.

Before you begin, make sure that you have a Swift 5.2-compatible toolchain installed (for example Xcode 11.5 or later if you're on a Mac).

๐Ÿ“ฆ As a package

To install Splash for use in a Swift Package Manager-powered tool or server-side application, add Splash as a dependency to your Package.swift file. For more information, please see the Swift Package Manager documentation.

.package(url: "https://github.com/JohnSundell/Splash", from: "0.1.0")

๐Ÿ›  Command line tools

If you want to use Splash through one of its built-in command line tools, start by cloning the repo to your local machine:

$ git clone https://github.com/johnsundell/splash.git
$ cd Splash

To run a tool without installing it, you can use the Swift Package Manager's run command, like this:

$ swift run SplashHTMLGen "func hello(world: String) -> Int"

To install all four command line tools globally on your system, use Make:

$ make install

That will install the following four tools in your /usr/local/bin folder:


If you only wish to install one of these, compile it and then move it to /usr/local/bin, like this:

$ swift build -c release -Xswiftc -static-stdlib
$ install .build/Release/SplashHTMLGen /usr/local/bin/SplashHTMLGen

Contributions and support

Splash is developed completely in the open, and your contributions are more than welcome. It's still a very new project, so I'm sure there are bugs to be found and improvements to be made - and hopefully we can work on those together as a community.

This project does not come with GitHub Issues-based support, and users are instead encouraged to become active participants in its continued development โ€” by fixing any bugs that they encounter, or by improving the documentation wherever it's found to be lacking.

To read more about suggested workflows when contributing to Splash, how to report bugs and feature requests, as well as technical details and an architectural overview - check out the Contributing Guide.

Hope you enjoy using Splash!

I had a lot of fun building Splash, and I'm looking forward to continue working on it in the open together with you! I hope you'll like it and that you'll find it useful. Let me know what you think on on Twitter ๐Ÿ˜Š


Stars: 1322



Splash 0.13.0 - 2020-05-25 20:43:31

  • Splash now requires Swift 5.2.
  • The try keyword is now correctly highlighted when used within a function call.
  • Comments that appear next to curly brackets are now correctly highlighted.
  • Generic parameter types that appear in an initializer declaration are no longer highlighted.
  • Generic superclasses are now correctly highlighted within subclass declarations.

Splash 0.12.0 - 2020-04-16 17:59:47

  • Enum cases called some are now correctly highlighted.
  • You can now pass a custom Grammar when using MarkdownDecorator (by @marcocapano).
  • Function calls that are the first statement within a closure that accepts arguments are now correctly highlighted.
  • When switching on an expression that includes accessing a property, that property is no longer incorrectly highlighted as a function call.

Splash 0.11.1 - 2020-02-07 14:12:15

This releases makes Splash compatible with the Swift 5.2 compiler that's bundled with the current Xcode 11.4 beta, thanks to @duemunk.

Splash 0.11.0 - 2020-01-29 10:41:36

  • Keyword-like function parameters placed on a separate line are no longer highlighted.
  • Keyword-like variables used when unwrapping optionals are no longer highlighted.
  • Splash now recognizes the unowned keyword.
  • Multiline comments are now correctly highlighted when placed next to punctuation, and when such a comment has no content (like /**/), by @duemunk.
  • String literals that end with a newline character are now correctly highlighted.

This release also contains a test improvement by @artrmz.

Splash 0.10.0 - 2019-12-30 23:41:34

  • Splash now fully escapes all required HTML entities when outputting HTML and when highlighting Markdown code blocks.
  • The prefix keyword is now correctly highlighted.

Splash 0.9.0 - 2019-11-04 10:35:56

New features:

  • You can now inject a custom CSS class prefix when using MarkdownDecorator to highlight all code blocks within a Markdown file.


  • Single-expression raw string interpolation is now highlighted correctly.
  • Strings appearing within another string's interpolation are now correctly highlighted.
  • Types appearing within a generic subscript's declaration are now highlighted correctly.
  • nil is now properly highlighted when passed to a parameter-less function.
  • Support has been added for the #warning and #error compiler directives.

Splash 0.8.0 - 2019-08-08 08:41:22

New APIs

  • Grammar now has a method called isDelimiter(mergableWith:), which is optional to adopt, and allows each grammar to tweak whether two delimiters should be merged into a single token when evaluated.


  • The convenience keyword is now supported.
  • MarkdownDecorator no longer hard-codes line breaks within the HTML code blocks that it generates (which is also true for the splashmarkdown command line tool, since it uses that same decoration code).
  • APIs called using dot syntax are now only highlighted as dotAccess when there are no associated values or parameters passed. So .someCase will be highlighted as dotAccess, while .someCall() won't. This is to make static APIs called using dot access highlighted in a more accurate way.
  • Highlighting for strings containing interpolation has now been made a lot more robust, especially for strings that contain punctuation and other delimiter-like characters.
  • Fixed a bug that could cause a type following a comment ending with a punctuation character to not be highlighted correctly.
  • Comments that start with a delimiter are now highlighted correctly.

Splash 0.7.1 - 2019-07-17 09:05:06

Syntax highlighting has been corrected in the following scenarios:

  • When shorthand closure arguments ($0, $1, etc.) are interpolated into a string literal.
  • For types and functions which names has a leading underscore.

Splash 0.7.0 - 2019-06-18 11:38:09

  • Splash can now be compiled as a Swift Package for iOS+tvOS using Xcode 11.
  • Added support for Swift 5.1's new some keyword.
  • #available checks are now correctly highlighted.

Splash 0.6.0 - 2019-05-13 09:27:27

This version of Splash migrates the installation script to the Swift 5 toolchain, and fixes highlighting in the following scenarios:

  • When using closure argument shorthands, such as $0, $1, etc.
  • When using the inout keyword with a closure argument.
  • When returning a generic type from a function.

Splash 0.5.0 - 2019-03-31 20:53:54

  • Splash is now implemented using Swift 5.
  • Highlighting has been corrected for keywords used as parameter labels for generic functions.
  • Highlighting has been corrected for key paths passed as arguments to functions.

Splash 0.4.1 - 2019-03-24 10:47:28

Fixed highlighting for nested @escaping closures.

Splash 0.4.0 - 2019-03-16 16:46:45

  • Support for the rethrows keyword (thanks @marcocapano!)
  • Fixed documentation for TokenType.keyword (thanks @warren-gavin!)
  • Generic parameters (such as Array<T>) within generic functions are now highlighted correctly.
  • The root level of a key path literal (\.property) is now highlighted correctly.

This release also includes a new command line tool - SplashMarkdown, which enables automatic HTML conversion and Splash decoration of all code blocks within a Markdown file.

Splash 0.3.0 - 2019-03-12 00:12:23

  • Added support for Swift 5 raw strings (both single-line and multi-line).
  • HTML output is now much more compact, and merges <span>s for tokens of the same type.
  • Multi-line comments with two asterisks (documentation-style) are now supported (thanks @MaciejGad, @marcocapano and @warren-gavin).
  • The dynamic and nonmutating keywords are now supported (thanks @marcocapano).

Splash 0.2.0 - 2019-03-09 22:13:53

Splash now uses Swift 4.2. Keep using older versions for Swift 4.1 support.


  • Added support for the inout, continue, fallthrough, indirect, deinit, is, while and repeat keywords (thanks @marcocapano!)
  • Added support for custom token types.
  • SwiftGrammar can now more easily be extended.
  • .init() is no longer treated as an enum.
  • Keywords used as function names are no longer treated as keywords.
  • Highlighting is now correct for types conforming to multiple protocols.
  • Associated types are now correctly highlighted.
  • Setters with an explicit access level are now highlighted as keywords.
  • The XCTAssert family of functions are now highlighted as functions, rather than types.
  • switch statements using nil pattern matching are now correctly highlighted.
  • Functions using argument pre-processors are now correctly highlighted.
  • Bool values passed to arguments without an external parameter label are now correctly highlighted.


  • Added support for specifying a background color (thanks @MaciejGad!)

Splash 0.1.4 - 2018-08-28 21:33:40

defer is now correctly treated as a keyword (thanks @hotogwc!)

Splash 0.1.3 - 2018-08-27 17:21:09

Syntax highlighting has been fixed for the following scenarios:

  • Enums used as subscripting keys: dictionary[.case]
  • Subscript declarations: subscript(key: Key) -> Value?
  • Keywords used as parameter labels: key(for object: Object) -> String
  • Using self to refer to a type: String.self

Splash 0.1.2 - 2018-08-27 13:30:46

  • Adds additional built-in themes based on Xcodeโ€™s default themes
  • Correctly handles static methods called on a generic type
  • Escapes < and > in HTMLOutputFormat

Splash 0.1.1 - 2018-08-25 11:02:02

This release fixes syntax highlighting of properties being accessed after a function call.

Splash 0.1.0 - 2018-08-25 08:47:15

Initial release of Splash.