JohnSundell / Publish

Welcome to **Publish**, a static site generator built specifically for Swift developers. It enables entire websites to be built using Swift, and supports themes, plugins and tons of other powerful customization options. Publish is used to build all of swiftbysundell.com. Websites as Swift packages When using Publish, each website is defined as a Swift package, which acts as the configuration as to how the website should be generated and deployed — all using native, type-safe Swift code. For example, here’s what the configuration for a food recipe website might look like: Each website built using Publish can freely decide what kind of sections and metadata that it wants to support. Above, we’ve added three sections — *Recipes*, *Links*, and *About* — which can then contain any number of items. We’ve also added support for our own, site-specific item metadata through the type, which we’ll be able to use in a fully type-safe manner all throughout our publishing process. Start out simple, and customize when needed While Publish offers a really powerful API that enables almost every aspect of the website generation process to be customized and tweaked, it also ships with a suite of convenience APIs that aims to make it as quick and easy as possible to get started. To start generating the *Delicious Recipes* website we defined above, all we need is a single line of code, that tells Publish which theme to use to generate our website’s HTML: *Not only does the above call render our website’s HTML, it also generates an RSS feed, a site map, and more.* Above we’re using Publish’s built-in Foundation theme, which is a very basic theme mostly provided as a starting point, and as an example of how Publish themes may be built. We can of course at any time replace that theme with our own, custom one, which can include any sort of HTML and resources that we’d like. By default, Publish will generate a website’s content based on Markdown files placed within that project’s folder, but any number of content items and custom pages can also be added programmatically. **Publish supports three types of content:** **Sections**, which are created based on the members of each website’s enum. Each section both has its own HTML page, and can also act as a container for a list of **Items**, which represent the nested HTML pages within that section. Finally, **Pages** provide a way to build custom free-form pages that can be placed into any kind of folder hierarchy. Each , , and can define its own set of Content — which can range from text (like titles and descriptions), to HTML, audio, video and various kinds of metadata. Here’s how we could extend our basic call from before to inject our own custom publishing pipeline — which enables us to define new items, modify sections, and much more: Of course, defining all of a program’s code in one single place is rarely a good idea, so it’s recommended to split up a website’s various generation operations into clearly separated steps — which can be defined by extending the type with static properties or methods, like this: *Each publishing step is passed an instance of , which it can use to mutate the current context in which the website is being published — including its files, folders, and content.* Using the above pattern, we can implement any number of custom publishing steps that’ll fit right in alongside all of the default steps that Publish ships with. This enables us to construct really powerful pipelines in which each step performs a single part of the generation process: *Above we’re constructing a completely custom publishing pipeline by calling the API.* To learn more about Publish’s built-in publishing steps, check out this file. Building an HTML theme Publish uses Plot as its HTML theming engine, which enables entire HTML pages to be defined using Swift. When using Publish, it’s recommended that you build your own website-specific theme — that can make full use of your own custom metadata, and be completely tailored to fit your website’s design. Themes are defined using the type, which uses an implementation to create all of a website’s HTML pages. Here’s an excerpt of what the implementation for the custom theme used above may look like: Above we’re able to access both built-in item properties, and the custom metadata properties that we defined earlier as part of our website’s struct, all in a way that retains full type safety. *More thorough documentation on how to build Publish themes, and some of the recommended best practices for doing so, will be added shortly.* Building plugins Publish also supports plugins, which can be used to share setup code between various projects, or to extend Publish’s built-in functionality in various ways. Just like publishing steps, plugins perform their work by modifying the current — for example by adding files or folders, by mutating the website’s existing content, or by adding Markdown parsing modifiers. Here’s an example of a plugin that ensures that all of a website’s items have tags: Plugins are then installed by adding the step to any publishing pipeline: *If your plugin is hosted on GitHub you can use the topic so it can be found with the rest of community plugins.* For a real-world example of a Publish plugin, check out the official Splash plugin, which makes it really easy to integrate the Splash syntax highlighter with Publish. System requirements To be able to successfully use Publish, make sure that your system has Swift version 5.4 (or later) installed. If you’re using a Mac, also make sure that is pointed at an Xcode installation that includes the required version of Swift, and that you’re running macOS Big Sur (11.0) or later. Please note that Publish **does not** officially support any form of beta software, including beta versions of Xcode and macOS, or unreleased versions of Swift. Installation Publish is distributed using the Swift Package Manager. To install it into a pr…