Swiftpack.co - Package - JohnSundell/Publish

Publish

Swift Package Manager Mac + Linux Twitter: @johnsundell

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:

struct DeliciousRecipes: Website {
    enum SectionID: String, WebsiteSectionID {
        case recipes
        case links
        case about
    }

    struct ItemMetadata: WebsiteItemMetadata {
        var ingredients: [String]
        var preparationTime: TimeInterval
    }

    var url = URL(string: "https://cooking-with-john.com")!
    var name = "Delicious Recipes"
    var description = "Many very delicious recipes."
    var language: Language { .english }
    var imagePath: Path? { "images/logo.png" }
}

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 ItemMetadata 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:

try DeliciousRecipes().publish(withTheme: .foundation)

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 Content 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 SectionID 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 Section, Item, and Page 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 publish() call from before to inject our own custom publishing pipeline — which enables us to define new items, modify sections, and much more:

try DeliciousRecipes().publish(
    withTheme: .foundation,
    additionalSteps: [
        // Add an item programmatically
        .addItem(Item(
            path: "my-favorite-recipe",
            sectionID: .recipes,
            metadata: DeliciousRecipes.ItemMetadata(
                ingredients: ["Chocolate", "Coffee", "Flour"],
                preparationTime: 10 * 60
            ),
            tags: ["favorite", "featured"],
            content: Content(
                title: "Check out my favorite recipe!"
            )
        )),
        // Add default titles to all sections
        .step(named: "Default section titles") { context in
            context.mutateAllSections { section in
                guard section.title.isEmpty else { return }
                
                switch section.id {
                case .recipes:
                    section.title = "My recipes"
                case .links:
                    section.title = "External links"
                case .about:
                    section.title = "About this site"
                }
            }
        }
    ]
)

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 PublishingStep type with static properties or methods, like this:

extension PublishingStep where Site == DeliciousRecipes {
    static func addDefaultSectionTitles() -> Self {
        .step(named: "Default section titles") { context in
            context.mutateAllSections { section in
                guard section.title.isEmpty else { return }

                switch section.id {
                case .recipes:
                    section.title = "My recipes"
                case .links:
                    section.title = "External links"
                case .about:
                    section.title = "About this site"
                }
            }
        }
    }
}

Each publishing step is passed an instance of PublishingContext, 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:

try DeliciousRecipes().publish(using: [
    .addMarkdownFiles(),
    .copyResources(),
    .addFavoriteItems(),
    .addDefaultSectionTitles(),
    .generateHTML(withTheme: .delicious),
    .generateRSSFeed(including: [.recipes]),
    .generateSiteMap()
])

Above we’re constructing a completely custom publishing pipeline by calling the publish(using:) 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 Theme type, which uses an HTMLFactory implementation to create all of a website’s HTML pages. Here’s an excerpt of what the implementation for the custom .delicious theme used above may look like:

extension Theme where Site == DeliciousRecipes {
    static var delicious: Self {
        Theme(htmlFactory: DeliciousHTMLFactory())
    }

    private struct DeliciousHTMLFactory: HTMLFactory {
        ...
        func makeItemHTML(for item: Item<DeliciousRecipes>,
                          context: PublishingContext<DeliciousRecipes>) throws -> HTML {
            HTML(
                .head(for: item, on: context.site),
                .body(
                    .ul(
                        .class("ingredients"),
                        .forEach(item.metadata.ingredients) {
                            .li(.text($0))
                        }
                    ),
                    .p(
                        "This will take around ",
                        "\(Int(item.metadata.preparationTime / 60)) ",
                        "minutes to prepare"
                    ),
                    .contentBody(item.body)
                )
            )
        }
        ...
    }
}

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 ItemMetadata 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 PublishingContext — 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:

extension Plugin {
    static var ensureAllItemsAreTagged: Self {
        Plugin(name: "Ensure that all items are tagged") { context in
            let allItems = context.sections.flatMap { $0.items }

            for item in allItems {
                guard !item.tags.isEmpty else {
                    throw PublishingError(
                        path: item.path,
                        infoMessage: "Item has no tags"
                    )
                }
            }
        }
    }
}

Plugins are then installed by adding the installPlugin step to any publishing pipeline:

try DeliciousRecipes().publish(using: [
    ...
    .installPlugin(.ensureAllItemsAreTagged)
])

If your plugin is hosted on GitHub you can use the publish-plugin 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.2 (or later) installed. If you’re using a Mac, also make sure that xcode-select is pointed at an Xcode installation that includes the required version of Swift, and that you’re running macOS Catalina (10.15) 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 project, add it as a dependency within your Package.swift manifest:

let package = Package(
    ...
    dependencies: [
        .package(url: "https://github.com/johnsundell/publish.git", from: "0.1.0")
    ],
    ...
)

Then import Publish wherever you’d like to use it:

import Publish

For more information on how to use the Swift Package Manager, check out this article, or its official documentation.

Publish also ships with a command line tool that makes it easy to set up new website projects, and to generate and deploy existing ones. To install that command line tool, simply run make within a local copy of the Publish repo:

$ git clone https://github.com/JohnSundell/Publish.git
$ cd Publish
$ make

Then run publish help for instructions on how to use it.

Running and deploying

Since all Publish websites are implemented as Swift packages, they can be generated simply by opening up a website’s package in Xcode (by opening its Package.swift file), and then running it using the Product > Run command (or ⌘+R).

Publish can also facilitate the deployment of websites to external servers through its DeploymentMethod API, and ships with built-in implementations for Git and GitHub-based deployments. To define a deployment method for a website, add the deploy step to your publishing pipeline:

try DeliciousRecipes().publish(using: [
    ...
    .deploy(using: .gitHub("johnsundell/delicious-recipes"))
])

Even when added to a pipeline, deployment steps are disabled by default, and are only executed when the --deploy command line flag was passed (which can be added through Xcode’s Product > Scheme > Edit Scheme... menu), or by running the command line tool using publish deploy.

Publish can also start a localhost web server for local testing and development, by using the publish run command. To regenerate site content with the server running, use Product > Run on your site's package in Xcode.

Quick start

To quickly get started with Publish, install the command line tool by first cloning this repository, and then run make within the cloned folder:

$ git clone https://github.com/JohnSundell/Publish.git
$ cd Publish
$ make

Note: If you encounter an error while running make, ensure that you have your Command Line Tools location set from Xcode's preferences. It's in Preferences > Locations > Locations > Command Line Tools. The dropdown will be blank if it hasn't been set yet.

Then, create a new folder for your new website project and simply run publish new within it to get started:

$ mkdir MyWebsite
$ cd MyWebsite
$ publish new

Finally, run open Package.swift to open up the project in Xcode to start building your new website.

Additional documentation

You can find a growing collection of additional documentation about Publish’s various features and capabilities within the Documentation folder.

Design and goals

Publish was first and foremost designed to be a powerful and heavily customizable tool for building static websites in Swift — starting with Swift by Sundell, a website which has over 300 individual pages and a pipeline consisting of over 25 publishing steps.

While the goal is definitely also to make Publish as accessible and easy to use as possible, it will most likely keep being a quite low-level tool that favors code-level control over file system configuration files, and customizability over strongly held conventions.

The main trade-off of that design is that Publish will likely have a steeper learning curve than most other static site generators, but hopefully it’ll also offer a much greater degree of power, flexibility and type safety as a result. Over time, and with the community’s help, we should be able to make that learning curve much less steep though — through much more thorough documentation and examples, and through shared tools and convenience APIs.

Publish was also designed with code reuse in mind, and hopefully a much larger selection of themes, tools, plugins and other extensions will be developed by the community over time.

Contributions and support

Publish is developed completely in the open, and your contributions are more than welcome.

Before you start using Publish in any of your projects, it’s highly recommended that you spend a few minutes familiarizing yourself with its documentation and internal implementation, so that you’ll be ready to tackle any issues or edge cases that you might encounter.

Since this is a very young project, it’s likely to have many limitations and missing features, which is something that can really only be discovered and addressed as more people start using it. While Publish is used in production to build all of Swift by Sundell, it’s recommended that you first try it out for your specific use case, to make sure it supports the features that you need.

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.

If you wish to make a change, open a Pull Request — even if it just contains a draft of the changes you’re planning, or a test that reproduces an issue — and we can discuss it further from there.

Hope you’ll enjoy using Publish!

Github

link
Stars: 2893

Releases

Publish 0.7.0 - 2020-06-15 17:47:45

  • The publish command line tool can now generate projects for building plugins, using publish new plugin.
  • A predicate can now be applied to filter which items that should be included when generating a podcast feed.

Publish 0.6.0 - 2020-05-26 11:24:31

  • Publish now requires Swift version 5.2.
  • If a Markdown file doesn’t contain a title (H1), that file’s name is now used as a fallback for the corresponding item’s title (by @bensyverson).
  • Items can now be filtered out of a given RSS feed by passing an itemPredicate when using the generateRSSFeed publishing step.
  • An item’s body can now be prefixed and suffixed when it appears within an RSS feed.
  • Items can now be removed from a section (by @peteschaffner).
  • When writing a custom deployment method, you can now pass an outputFolderPath when creating a deployment folder for it, to have the website’s output copied into a nested folder (by @baguio and @john-mueller).

Publish 0.5.0 - 2020-01-29 11:48:47

  • The publish run command now gives clearer instructions on how to stop it, by @honghaoz.
  • The publish run command is now compatible with both Python 2 and 3, by @hisaac.
  • The publish new command will now generate a project that better reflects its folder name, especially when numbers and underscores are used, by @natanrolnik.
  • Any hidden files within a project's Output folder are now cleaned up before each publishing process begins, by @Hejki.
  • Publish now ships with the latest versions of Ink, Plot and Sweep.

This release also contains documentation improvements by @Ze0nC, @alex-ross and @navanchauhan.

Publish 0.4.0 - 2020-01-16 10:53:10

  • The Foundation theme now correctly renders content for stand-alone pages.
  • The Foundation theme's CSS has been improved when using multiple sections.
  • When using a custom rawValue within a website's SectionID enum, that is now taken into account during the generation process (by @Goosse).
  • When iterating over a website's sections, the iteration order is now predictable and follows the order that the website's sections were defined in within the SectionID enum.
  • You can now specify an RSS titleSuffix for items.
  • Publish is now using version 0.3.0 of Ink.

This release also includes documentation improvements by @alexito4.

Publish 0.3.0 - 2020-01-09 12:34:51

  • When generating a new project using the publish new command line tool, any camelCasing within the current folder’s name will now be preserved in the project’s default name (by @wacumov).
  • A custom port number can now be specified when running the publish run command line tool (by @jlorfeo).
  • The publish run tool will now also correctly shut down its localhost server when it exits, and its error messaging has been improved.
  • External resources can now be referred to using Path instances, such as when specifying CSS files using the built-in head Plot component.
  • The Git deployment method will now output much richer error messages in case an error occured (by @ytyubox and @sindresorhus).
  • An item’s path can now be overriden using the path Markdown metadata property (by @dmonagle).
  • Publish now ships with Files 4.1.1 and Plot 0.5.0.
  • The Foundation theme's default CSS has been improved.

This release also includes documentation improvements by @NSBrianWard, @daniloc, @antonio081014 and @labradon.

Publish 0.2.0 - 2020-01-03 23:05:15

  • When using the command line tool publish run, the local web server's address is now prefixed with http://, which enables you to click it to open your site in your web browser (by @slashmo). Also, if any error was encountered when starting that server, it's now reported to the user (by @camdeardorff).
  • Nested items are now generated at the correct path. So if you place a content item in Content/yourSection/path/to/item it will be generated at Output/yourSection/path/to/item (by @tonisuter).
  • You can now exclude an entire section from a website's sitemap.xml by including its path in excludedPaths (by @artrmz).
  • Plugins can now easily be added when using the default publishing pipeline, using the plugins: argument (by @slashmo).
  • RSS/podcast feeds are now only re-generated when their content was changed.
  • RSSFeedConfiguration and PodcastFeedConfiguration are now value types.
  • A podcast/RSS feed's publishing date can now be customized.
  • Attempting to publish a website with an empty pipeline now throws an error.
  • Publishing steps can now easily create and use cache files, using PublishingContext.cacheFile(named:).
  • Publish now uses version 0.4.0 of Plot.

Also thanks to @fbernutz, @danielmgauthier and @brettkoonce for fixing spelling errors in the documentation.

Publish 0.1.0 - 2019-12-30 20:13:19

Initial release of Publish.