HTMLSwiftKit is a Swift framework that simplifies the creation of static sites. The kit aims to convert your Swift-written code to HTML, thus making your site generation process easy with Swift and handling the HTML complexities under the hood. The goal of HTMLSwiftKit is to enable anyone with basic HTML knowledge to develop websites in Swift.
It includes all the essential HTML tags that are modified as per Swift language, which can be directly used. Now start generating your websites using Swift.
Creating a site is pretty simple with HTMLSwiftKit:
Every website have few pages associated with it, lets see how to make a HTMLPage using HTMLSwiftKit
Create a struct and implement the HTMLPage protocol, and you are good to start building your page.
struct FirstPage: HTMLPage {
/// Your HTMLContent
var htmlContent: [HTMLBlock] {
Heading(.h1, "Random Image")
Image(src: "https://picsum.photos/200/300", alt: "Test")
HorizontalRule()
}
}Tip
Start adding your HTML elements inside htmlContent block just like HTML without < > tag
Want to add CSS to your Webpage, HTMLSwiftKit covers that too.
Create a struct implement the CSSBlock protocol and provide the CSS type and start adding your styling modifiers.
struct BasicCSS: CSSBlock {
var cssType: CSSType = .custom
var content: [CSSModifier] {
Border(5, border: .dotted, color: "orange")
BackgroundColor(color: "yellow")
FontSize(22)
Color("Red")
Padding(200)
}
}Note
Don't forget to add your CSS block into your HTMLContent block to allow HTML to get context of it
var htmlContent: [HTMLBlock] {
Style({ BasicCSS() })
}Once the HTMLPages and CSS are ready, now its tme to configure your website
Create a struct implement the website protocol and provide the necessary data and you have configured your website.
struct MyWebSite: WebSite {
var baseUrl: URL = URL(string: "www.htmlswiftkit.com")!
var author: String = "Gokul"
var pages: [HTMLSwiftKit.HTMLPage] = [FirstPage(), SecondPage()]
var crawlerConfiguration: CrawlerConfiguration = CrawlerConfig()
}Once you are ready with your Website configuration now its time to generate the Site source code.
So HTMLSwiftKit provides two way to generate your source code:
To generate the site via SPM, create your own new SPM, add HTMLSwiftKit as a dependency and configure the above mentioned things. Once you have done all the stpes mentioned create an instance of the website and trigger the publishViaSPM() method
@main
struct StartWebsite {
static func main() {
let site = MyWebSite()
do {
try site.publishViaSPM()
} catch {
print(error.localizedDescription)
}
}
}On generating Site via SPM, the kit creates a Build folder into your existing package.
Check the starter project to understand more.
To generate the site via Device, create a new project and add HTMLSwiftKit as a dependency and configure the above mentioned things. Once you have done all the stpes mentioned create an instance of the website and trigger the publishViaDevice() method
@main
struct StartWebsite {
static func main() {
let site = MyWebSite()
do {
try site.publishViaDevice()
} catch {
print(error.localizedDescription)
}
}
}Here once the build file is generated, the console will print the Build location. Checkout the location to get the Build file.
Note
Console will print "HTMLSwiftKit: Build is available at pathURL "
Check the starter project to understand more.
By following the given procedure you can build your static site easily.
HTMLSwiftKit supports the functionality of Robots. So you can restrict certain crawlers from crawling your website. All you need to do is mention the crawlers you don't want to allow crawling and add paths if there is any.
class CrawlerConfig: CrawlerConfiguration {
var disallowRules: [CrawlerDisallowRule] = [CrawlerDisallowRule(robot: .google)]
}Tip
The kit includes a variety of crawlers, you can also add a specific crawler by directly providing the agent name.
Currently the kit supports the following of CSS modifiers:
| Modifiers | Modifiers |
|---|---|
| BackgroundColor | Border |
| BorderRadius | Color |
| FontFamily | FontSize |
| FontWeight | Margins |
| Padding | TextAlignment |
| TextDecoration | TextTransform |
| Width | Height |
All the details regarding the modifiers are added in their respective classes, do check them out to know more. Raise an issue with the details regarding the required modifier, and I will try to get it into the kit.
Currently the kit supports the following of HTML elements:
| Elements | Elements | Elements | Elements |
|---|---|---|---|
| Address | BlockQuote | Body | Break |
| Button | Cite | Code | Delete |
| Description | DescriptionList | DescriptionTerm | Details |
| Dialouge | Division | Footer | Head |
| Heading | HorizontalRule | Hyperlink | Image |
| Insert | ListItem | Mark | Meta |
| NoScript | OrderedList | Paragraph | PreFormatted |
| Script | Span | Style | UnorderedList |
All the details regarding the elements are added in their respective classes, do check them out to know more. Raise an issue with the details regarding the required element, and I will try to get it into the kit.
Now there are few elements which are very specific to this kit. These elements are made to bridge the gap that swift cant handle directly.
Currently we only have one such element:
| Element | Description |
|---|---|
| Text | Used while interpolating texts |
Primarily we have two kinds of CSS types:
- Source type CSS is used when created CSS is applied to any source tag.
- Want to create CSS for Button, Divider, Heading, etc., set CSS type to Source.
- Custom type CSS is used when created CSS is a custom class.
- Use this when any form of custom CSS needs to be used.
Providing a correct CSS type is important since this will cause impact in Source code generation.
HTMLSwiftKit has three block builders:
All the HTML blocks will be rendered by this block. When you are creating any HTML Content, the modifiers must be wrapped by this builder block.
All the CSS styling blocks are rendered by this block. When adding any type of CSS styling, make sure the modifiers are wrapped by this builder block.
While injecting CSS into the HTMLBlock, we will use a Style block. Now a style block can have various types of CSS. Thus to incorporate these multiple styles, we have this block builder.
Copyright (c) 2024 Gokul Nair
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Made with ❤️ in 🇮🇳 By Gokul Nair