{"id":16742507,"url":"https://github.com/johnsundell/splash","last_synced_at":"2025-05-15T02:05:21.818Z","repository":{"id":33620774,"uuid":"145689632","full_name":"JohnSundell/Splash","owner":"JohnSundell","description":"A fast, lightweight and flexible Swift syntax highlighter for blogs, tools and fun!","archived":false,"fork":false,"pushed_at":"2024-05-27T11:18:15.000Z","size":497,"stargazers_count":1815,"open_issues_count":8,"forks_count":130,"subscribers_count":31,"default_branch":"master","last_synced_at":"2025-04-03T13:00:12.789Z","etag":null,"topics":["command-line-tool","swift","swift-package","syntax-highlighting"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/JohnSundell.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-08-22T09:51:38.000Z","updated_at":"2025-04-01T07:29:59.000Z","dependencies_parsed_at":"2024-06-18T16:41:37.187Z","dependency_job_id":"779bb5c1-c9c7-4605-8a84-fc3f5640175e","html_url":"https://github.com/JohnSundell/Splash","commit_stats":{"total_commits":143,"total_committers":21,"mean_commits":6.809523809523809,"dds":0.3776223776223776,"last_synced_commit":"2e3f17c2d09689c8bf175c4a84ff7f2ad3353301"},"previous_names":[],"tags_count":23,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnSundell%2FSplash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnSundell%2FSplash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnSundell%2FSplash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/JohnSundell%2FSplash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/JohnSundell","download_url":"https://codeload.github.com/JohnSundell/Splash/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248368162,"owners_count":21092312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["command-line-tool","swift","swift-package","syntax-highlighting"],"created_at":"2024-10-13T01:23:57.654Z","updated_at":"2025-04-11T09:30:36.406Z","avatar_url":"https://github.com/JohnSundell.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"Images/Logo.png\" width=\"528\" max-width=\"90%\" alt=\"Splash\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Swift-5.2-orange.svg\" /\u003e\n    \u003ca href=\"https://swift.org/package-manager\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/spm-compatible-brightgreen.svg?style=flat\" alt=\"Swift Package Manager\" /\u003e\n    \u003c/a\u003e\n     \u003cimg src=\"https://img.shields.io/badge/platforms-mac+linux-brightgreen.svg?style=flat\" alt=\"Mac + Linux\" /\u003e\n    \u003ca href=\"https://twitter.com/johnsundell\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/twitter-@johnsundell-blue.svg?style=flat\" alt=\"Twitter: @johnsundell\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\nWelcome 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.\n\nIt's used to highlight all articles on [swiftbysundell.com](https://swiftbysundell.com).\n\n## Usage\n\nSplash 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.\n\n### 🌍 On the web\n\nIf you're using [Publish](https://github.com/JohnSundell/Publish), then there's an official plugin that makes it easy to integrate Splash into your website:\n\n👉 [SplashPublishPlugin](https://github.com/JohnSundell/SplashPublishPlugin)\n\nIf you're using Jekyll, there's also a custom ```{% splash %}``` tag available for the Liquid templating language.\n\n👉 [splashtag](https://github.com/mannberg/splashtag)\n\n### 🖥 On the command line\n\nThe 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.\n\n#### SplashHTMLGen\n\n`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.\n\nFor example, if you call it like this:\n\n```\n$ SplashHTMLGen \"func hello(world: String) -\u003e Int\"\n```\n\nYou'll get the following output back:\n\n```html\n\u003cspan class=\"keyword\"\u003efunc\u003c/span\u003e hello(world: \u003cspan class=\"type\"\u003eString\u003c/span\u003e) -\u003e \u003cspan class=\"type\"\u003eInt\u003c/span\u003e\n```\n\nTo 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](https://github.com/JohnSundell/Splash/blob/master/Examples/sundellsColors.css).\n\nWhen rendering your outputted html, make sure to wrap your output code in the `\u003cpre\u003e` and `\u003ccode\u003e` tags and properly link to your `.css` file. Like this:\n\n```html\n\u003c!DOCTYPE html\u003e\n\u003chead\u003e\n    \u003ctitle\u003eHello World\u003c/title\u003e\n    \u003clink rel=\"stylesheet\" href=\"sundellsColors.css\"\u003e\n\u003c/head\u003e\n\n\u003cpre\u003e\n    \u003ccode\u003e\n        \u003cspan class=\"keyword\"\u003efunc\u003c/span\u003e hello(world: \u003cspan class=\"type\"\u003eString\u003c/span\u003e) -\u003e \u003cspan class=\"type\"\u003eInt\u003c/span\u003e\n    \u003c/code\u003e\n\u003c/pre\u003e\n```\n\nFor more information about HTML generation with Splash and how to customize it, see `HTMLOutputFormat` [here](https://github.com/JohnSundell/Splash/blob/master/Sources/Splash/Output/HTMLOutputFormat.swift).\n\n#### SplashMarkdown\n\n`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.\n\nJust 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.\n\nHere’s an example call to decorate a Markdown file at the path `~/Documents/Article.md`:\n\n```\n$ SplashMarkdown ~/Documents/Article.md\n```\n\nThe decorated Markdown will be returned as standard output.\n\nHighlighting can be skipped for any code block by adding `no-highlight` next to the block’s opening row of backticks — like this: *“```no-highlight”*.\n\n#### SplashImageGen\n\n`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.\n\nFor example, if you call it like this:\n\n```\n$ SplashImageGen \"func hello(world: String) -\u003e Int\" \"MyImage.png\"\n```\n\nThe following image will be generated (and written to disk as `MyImage.png`):\n\n\u003cimg src=\"Images/Code.png\" max-width=\"90%\" alt=\"Code sample\" /\u003e\n\n*`SplashImageGen` is currently only available on macOS.*\n\n#### SplashTokenizer\n\nThe 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).\n\nSo if you call it like this:\n\n```\n$ SplashTokenizer \"func hello(world: String) -\u003e Int\"\n```\n\nYou'll get the following standard output back:\n\n```\nKeyword token: func\nPlain text: hello(world:\nType token: String\nPlain text: )\nPlain text: -\u003e\nType token: Int\n```\n\n### 📦 As a package\n\nTo include Splash in your own script or Swift package, [add it as a dependency](#installation) and use the `SyntaxHighlighter` class combined with your output format of choice to highlight a string of code:\n\n```swift\nimport Splash\n\nlet highlighter = SyntaxHighlighter(format: HTMLOutputFormat())\nlet html = highlighter.highlight(\"func hello() -\u003e String\")\n```\n\nSplash ships with two built-in output formats - HTML and `NSAttributedString`, but you can also easily add your own by implementing the `OutputFormat` protocol.\n\n## Installation\n\nSplash 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.\n\nSplash supports both macOS and Linux.\n\n*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).*\n\n### 📦 As a package\n\nTo 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](https://github.com/apple/swift-package-manager/tree/master/Documentation).\n\n```\n.package(url: \"https://github.com/JohnSundell/Splash\", from: \"0.1.0\")\n```\n\n### 🛠 Command line tools\n\nIf you want to use Splash through one of its built-in command line tools, start by cloning the repo to your local machine:\n\n```\n$ git clone https://github.com/johnsundell/splash.git\n$ cd splash\n```\n\nTo run a tool without installing it, you can use the Swift Package Manager's `run` command, like this:\n\n```\n$ swift run SplashHTMLGen \"func hello(world: String) -\u003e Int\"\n```\n\nTo install all four command line tools globally on your system, use Make:\n\n```\n$ make install\n```\n\nThat will install the following four tools in your `/usr/local/bin` folder:\n\n```\nSplashHTMLGen\nSplashMarkdown\nSplashImageGen\nSplashTokenizer\n```\n\nIf you only wish to install one of these, compile it and then move it to `/usr/local/bin`, like this:\n\n```\n$ swift build -c release -Xswiftc -static-stdlib\n$ install .build/release/SplashHTMLGen /usr/local/bin/SplashHTMLGen\n```\n\n## Contributions and support\n\nSplash 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.\n\nThis 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.\n\nTo 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](https://github.com/JohnSundell/Splash/blob/master/CONTRIBUTING.md).\n\n## Hope you enjoy using Splash!\n\nI 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 [Twitter](https://twitter.com/johnsundell) 😊\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnsundell%2Fsplash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjohnsundell%2Fsplash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjohnsundell%2Fsplash/lists"}