DOCSEARCHbyAlgolia
Submit Docs

Ignite Static Site Builder

repository·main·Indexed 25 days ago

https://github.com/twostraws/ignite

A static site builder for Swift developers that uses a SwiftUI-like declarative syntax to create responsive websites. It includes a CLI for scaffolding, building, and previewing sites, and supports Markdown content rendering via the ArticlePage protocol and environment queries for adapting UI to device settings.

Tokens
1.5K
Snippets
4
Records
10
Agent score
79%

What's inside Ignite

  1. Overview of Ignite

    main
    Ignite is a static site generator designed specifically for Swift developers. It provides an expressive, SwiftUI-like syntax for building websites, allowing developers to create high-quality, responsive sites without requiring deep knowledge of HTML or CSS. Instead of a direct mapping of HTML to Swift, Ignite uses a declarative approach to help you build beautiful websites that work across all devices.

  2. Understand the Ignite folder structure

    main

    Ignite sites are Swift packages that follow a specific directory structure:

    • Assets: Custom site assets (images, etc.). You can use any subfolder structure.
    • Build: Automatically generated folder containing the final HTML files. Do not place important data here, as it is deleted on every build.
    • Content (Optional): Markdown files for posts. Files here are rendered to HTML and placed in the Build folder.
    • Includes (Optional): Custom HTML files you wish to include.
    • Sources: All Swift source code for your site.

  3. Use environment queries to adapt your UI

    main

    Ignite provides a set of specialized queries that allow you to detect and respond to the user's environment and device settings. These queries can be used to adjust layouts, colors, motion, and other UI properties based on real-time system state.

    Available queries include:

    • BreakpointQuery: Detects screen size breakpoints.
    • ColorSchemeQuery: Detects light or dark color schemes.
    • ContrastQuery: Detects high contrast settings.
    • DisplayModeQuery: Detects display modes.
    • MotionQuery: Detects user motion preferences (e.g., reduced motion).
    • OrientationQuery: Detects device orientation.
    • ThemeQuery: Detects active themes.
    • TransparencyQuery: Detects transparency/reduce transparency settings.

  4. Create a new Ignite site

    main

    Once the Ignite CLI is installed, you can scaffold a new website project using the new command.

    ignite new ExampleSite

    After creation, navigate to the project directory and open the Package.swift file in Xcode to begin development:

    cd ExampleSite
open Package.swift

  5. Create custom layouts for Markdown content

    main

    To render Markdown files located in the Content folder, you must implement a layout that conforms to the ArticlePage protocol. This protocol provides an article property containing the content of the Markdown file.

    1. Define the Layout

    Create a type conforming to ArticlePage and use the article property to build your HTML structure:

    import Foundation
import Ignite

struct CustomArticleLayout: ArticlePage {
    var body: some HTML {
        Text(article.title)
            .font(.title1)

        if let image = article.image {
            Image(image, description: article.imageDescription)
                .resizable()
                .cornerRadius(20)
                .frame(maxHeight: 300)
        }

        Text(article.text)
    }
}

    2. Register the Layout in your Site

    Add the custom layout to the articlePages property of your Site implementation:

    struct ExampleSite: Site {    
    var name = "Hello World"
    var url = URL(static: "https://www.example.com")

    var homePage = Home()
    var layout = MyLayout()

    var articlePages: [any ArticlePage] {
        CustomArticleLayout()
    }
}

  6. Build and preview your Ignite site

    main

    Ignite provides CLI commands to manage the build process and local development server.

    Build the site

    To convert your Swift code into HTML files, run the build command. This generates a Build folder containing the static site files.

    ignite build

    Preview the site

    To view your site locally, use the run --preview command. This starts a local web server and opens your default web browser. This is the recommended way to preview your site to ensure stylesheets and JavaScript load correctly.

    ignite run --preview

    Tip: If you are using Xcode, you can perform builds via the Xcode UI (Destination > My Mac) and then simply refresh your browser after running ignite run --preview to see changes.

    ignite build
ignite run --preview

  7. Install the Ignite CLI

    main

    To use the Ignite command-line tool for creating, building, and previewing sites, follow these steps to build and install it from the source repository:

    1. Clone the repository: git clone https://github.com/twostraws/Ignite.
    2. Enter the directory: cd Ignite.
    3. Build the tool: make.
    4. Install the tool to /usr/local/bin: make install (use sudo make install if you encounter permission issues).

    To install to a custom directory, use the PREFIX_DIR variable: make install PREFIX_DIR=/my/install/dir

    git clone https://github.com/twostraws/Ignite
cd Ignite
make
make install

  8. Reference: Ignite CLI commands

    main

    The Ignite command-line tool provides several subcommands for site management. Use ignite help for general help or ignite help <subcommand> for specific details.

    • new <Name>: Creates a new Ignite site project.
    • build: Converts Swift code into HTML files in the Build directory.
    • run --preview: Launches a local web server and opens the site in your browser.

  10. Run the Ignite development server

    main
    The server.py script provides a built-in HTTP server for previewing your Ignite site. It supports serving a specific directory and can be configured to serve a subsite (a specific subdirectory) with automatic redirection from the root path. If a 404.html file exists in the base directory, the server will serve it instead of the default error page.