Add hello world tutorial (#119)

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/IntroducingSlipstream.tutorial

@@ -6,10 +6,13 @@
   }
 
   @Chapter(name: "Your first site") {
-    Learn all the basics of building your first static website with Slipstream.
+    Learn the basics of making a static website with Slipstream.
+
+    And there's cute pigs too 🐷
 
-    @Image(source: "logo-square", alt: "The Slipstream logo. The Swift bird logo is flying off the edge of the Tailwind CSS wind logo")
+    @Image(source: "IntroducingSlipstream-YourFirstSite", alt: "The Slipstream logo. The Swift bird logo is flying off the edge of the Tailwind CSS wind logo")
 
-    @TutorialReference(tutorial: "doc:IntroducingSlipstream-YourFirstSite")
+    @TutorialReference(tutorial: "doc:IntroducingSlipstream-YourFirstSite-Workspace")
+    @TutorialReference(tutorial: "doc:IntroducingSlipstream-YourFirstSite-HelloWorld")
   }
 }

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/HelloWorld/IntroducingSlipstream-YourFirstSite-HelloWorld-1-1.swift

@@ -0,0 +1,4 @@
+// The Swift Programming Language
+// https://docs.swift.org/swift-book
+
+print("Hello, world!")

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/HelloWorld/IntroducingSlipstream-YourFirstSite-HelloWorld-1-2.swift

@@ -0,0 +1,7 @@
+import Slipstream
+
+struct Home: View {
+  var body: some View {
+    Text("Hello, world!")
+  }
+}

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/HelloWorld/IntroducingSlipstream-YourFirstSite-HelloWorld-1-3.swift

@@ -0,0 +1,9 @@
+import Slipstream
+
+struct Home: View {
+  var body: some View {
+    Text("Hello, world!")
+  }
+}
+
+print(try renderHTML(Home()))

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/HelloWorld/IntroducingSlipstream-YourFirstSite-HelloWorld-2-1.swift

@@ -0,0 +1,13 @@
+import Slipstream
+
+struct Home: View {
+  var body: some View {
+    Text("Hello, world!")
+  }
+}
+
+let sitemap: Sitemap = [
+  "index.html": Home()
+]
+
+print(try renderHTML(Home()))

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/HelloWorld/IntroducingSlipstream-YourFirstSite-HelloWorld-2-2.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+import Slipstream
+
+struct Home: View {
+  var body: some View {
+    Text("Hello, world!")
+  }
+}
+
+let sitemap: Sitemap = [
+  "index.html": Home()
+]
+
+guard let projectURL = URL(filePath: #filePath)?
+  .deletingLastPathComponent()
+  .deletingLastPathComponent() else {
+  print("Unable to create URL for \(#filePath)")
+  exit(1)
+}
+
+let outputURL = projectURL.appending(path: "site")
+
+print(try renderHTML(Home()))

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/HelloWorld/IntroducingSlipstream-YourFirstSite-HelloWorld-2-3.swift

@@ -0,0 +1,24 @@
+import Foundation
+
+import Slipstream
+
+struct Home: View {
+  var body: some View {
+    Text("Hello, world!")
+  }
+}
+
+let sitemap: Sitemap = [
+  "index.html": Home()
+]
+
+guard let projectURL = URL(filePath: #filePath)?
+  .deletingLastPathComponent()
+  .deletingLastPathComponent() else {
+  print("Unable to create URL for \(#filePath)")
+  exit(1)
+}
+
+let outputURL = projectURL.appending(path: "site")
+
+try renderSitemap(sitemap, to: outputURL)

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/HelloWorld/IntroducingSlipstream-YourFirstSite-HelloWorld.tutorial

@@ -0,0 +1,101 @@
+@Tutorial(time: 10) {
+  @XcodeRequirement(title: "Xcode 15 or later", destination: "https://itunes.apple.com/us/app/xcode/id497799835?mt=12")
+
+  @Intro(title: "Hello, world!") {
+    Learn the essential Slipstream concepts and workflow to build your first site.
+
+    This tutorial assumes you already have Xcode and Tailwind CSS installed and that you have a
+    Swift package with Slipstream added as a dependency.
+
+    @Image(source: "tutorial-banner", alt: "Coco the pig")
+  }
+
+  @Section(title: "Your first view") {
+    @ContentAndMedia {
+      Let's learn the basics of Slipstream. If you're familiar with SwiftUI then this section will
+      also feel familiar.
+
+      @Image(source: "logo-square", alt: "The Slipstream logo. The Swift bird logo is flying off the edge of the Tailwind CSS wind logo")    
+    }
+
+    @Steps {
+      @Step {
+        Like SwiftUI, every project in Slipstream starts with a ``View``.
+
+        Open up main.swift.
+
+        @Code(name: "main.swift", file: "IntroducingSlipstream-YourFirstSite-HelloWorld-1-1.swift")
+      }
+
+      @Step {
+        Remove the boilerplate and add a new ``View`` type called `Home`.
+
+        This view will be the root definition for our home page.
+
+        @Code(name: "main.swift", file: "IntroducingSlipstream-YourFirstSite-HelloWorld-1-2.swift")
+      }
+
+      @Step {
+        Now let's try rendering the view to see what the output looks like. We'll use
+        ``renderHTML(_:)`` to render our view to a string that we can print to the console.
+
+        Notice that the output includes our text wrapped inside of a `<p>` element. Every View type
+        in Slipstream will produce some kind of an HTML element. When possible, Slipstream tries to
+        match the generated code to similar behavior for the view's SwiftUI equivalent.
+        <doc:SlipstreamforSwiftUIDevelopers> provides a complete outline of the overlap between
+        SwiftUI and Slipstream.
+
+        @Code(name: "main.swift", file: "IntroducingSlipstream-YourFirstSite-HelloWorld-1-3.swift") {
+          @Image(source: "IntroducingSlipstream-YourFirstSite-HelloWorld-1-3-preview", alt: "The output from rendering our view: <p>Hello, world!</p>")
+        }
+      }
+    }
+  }
+
+  @Section(title: "Rendering to disk") {
+    @ContentAndMedia {
+      Now that we've made our first Slipstream view, let's get it saved to disk so that we can
+      preview the output to a browser.
+
+      @Image(source: "logo-square", alt: "The Slipstream logo. The Swift bird logo is flying off the edge of the Tailwind CSS wind logo")
+    }
+
+    @Steps {
+      @Step {
+        Slipstream provides a barebones site renderer that requires we define a ``Sitemap``, essentially
+        a map of filepaths to ``View`` instances.
+
+        To use it we first define our sitemap.
+
+        @Code(name: "main.swift", file: "IntroducingSlipstream-YourFirstSite-HelloWorld-2-1.swift", previousFile: "IntroducingSlipstream-YourFirstSite-HelloWorld-1-3.swift")
+      }
+
+      @Step {
+        Next we need to define where we want to output our site to. In most cases just writing to
+        your project directory is going to be sufficient, but you could extend functionality with
+        more options if needed.
+
+        @Code(name: "main.swift", file: "IntroducingSlipstream-YourFirstSite-HelloWorld-2-2.swift")
+      }
+
+      @Step {
+        We can now use ``renderSitemap(_:to:encoding:)`` to output our generated site to our project
+        folder.
+
+        @Code(name: "main.swift", file: "IntroducingSlipstream-YourFirstSite-HelloWorld-2-3.swift") {
+          @Image(source: "IntroducingSlipstream-YourFirstSite-HelloWorld-2-3-preview", alt: "The output from rendering our sitemap")
+        }
+      }
+
+      @Step {
+        Congratulations! You've just generated your first Slipstream html page! 🎉 It ain't pretty
+        (yet!), but it's yours 😉
+
+        You can try previewing `index.html` by right clicking it in Xcode and clicking "Open
+        with External Editor".
+
+        @Image(source: "IntroducingSlipstream-YourFirstSite-HelloWorld-2-4", alt: "The output from rendering our sitemap")
+      }
+    }
+  }
+}

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/IntroducingSlipstream-YourFirstSite-1-3.sh → Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/Workspace/IntroducingSlipstream-YourFirstSite-Workspace-1-3.sh

@@ -1 +1,2 @@
+
 npm install -D tailwindcss

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/IntroducingSlipstream-YourFirstSite-2-2.swift → Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/Workspace/IntroducingSlipstream-YourFirstSite-Workspace-1-6.swift

@@ -5,6 +5,10 @@ import PackageDescription
 
 let package = Package(
   name: "MySite",
+  platforms: [
+    .macOS("14"),
+    .iOS("17"),
+  ],
   dependencies: [
     .package(url: "https://github.com/jverkoey/slipstream.git", branch: "main"),
   ],

Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/IntroducingSlipstream-YourFirstSite.tutorial → Sources/Slipstream/Documentation.docc/Tutorials/IntroducingSlipstream/YourFirstSite/Workspace/IntroducingSlipstream-YourFirstSite-Workspace.tutorial

@@ -1,72 +1,75 @@
-@Tutorial(time: 20) {
+@Tutorial(time: 5) {
+  @XcodeRequirement(title: "Xcode 15 or later", destination: "https://itunes.apple.com/us/app/xcode/id497799835?mt=12")
+
   @Intro(title: "Setting up your workspace") {
     This tutorial guides you through building a website for coco the pig. You’ll start by
     setting up your workspace by installing Tailwind CSS and creating the Swift package you'll
     use to generate your website. By the end of this tutorial you will have deployed your first
     static Slipstream site to the internet for free using GitHub Pages.
-
-    @Image(source: "tutorial-banner", alt: "The Slipstream logo. The Swift bird logo is flying off the edge of the Tailwind CSS wind logo")
+
+    If you already have Xcode installed then you'll have your workspace set up in no time.
+
+    @Image(source: "tutorial-banner", alt: "Coco the pig")
   }
-  
+
   @Section(title: "Prerequisites") {
     @ContentAndMedia {
       Slipstream requires a Mac with Xcode and Tailwind CSS installed. In this section we'll also
       create a new Swift Package for our website and configure it to work with Slipstream and
       Tailwind CSS.
 
-      @Image(source: "YourFirstSite-section1", alt: "Xcode installed on a MacBook Pro")    
+      @Image(source: "IntroducingSlipstream-YourFirstSite-Workspace-1", alt: "Xcode installed on a MacBook Pro")    
     }
 
     @Steps {
       @Step {
         Install Xcode from the [App Store](https://apps.apple.com/us/app/xcode/id497799835?mt=12) or
         from [developer.apple.com](https://developer.apple.com/xcode/). Xcode 15 or higher is required.
 
-        @Image(source: "IntroducingSlipstream-YourFirstSite-1-1", alt: "Xcode in the App Store")   
+        @Image(source: "IntroducingSlipstream-YourFirstSite-Workspace-1-1", alt: "Xcode in the App Store")   
       }
 
       @Step {
         Open Xcode and create a Package. Select the macOS Executable template and click Next. Name
         your site and enable the "Create git repository" option so that we can push the site to
         GitHub later on. 
 
-        @Image(source: "IntroducingSlipstream-YourFirstSite-1-2", alt: "The new Package menu in Xcode")   
+        @Image(source: "IntroducingSlipstream-YourFirstSite-Workspace-1-2", alt: "The new Package menu in Xcode")   
       }
 
       @Step {
         Open Terminal and install Tailwind CSS. Alternatively, follow the installation instructions
         at [tailwindcss.com/docs/installation](https://tailwindcss.com/docs/installation).
 
-        @Code(name: "Terminal", file: "IntroducingSlipstream-YourFirstSite-1-3.sh")
+        @Code(name: "Terminal", file: "IntroducingSlipstream-YourFirstSite-Workspace-1-3.sh")
       }
 
       @Step {
         In the same terminal, change your working directory to your newly created site and
         initialize Tailwind CSS. This will create a generic tailwind.config.js file for your site.
 
-        @Code(name: "Terminal", file: "IntroducingSlipstream-YourFirstSite-1-4.sh", reset: true)
+        @Code(name: "Terminal", file: "IntroducingSlipstream-YourFirstSite-Workspace-1-4.sh", reset: true)
+      }
+
+      @Step {
+        Now let's add Slipstream as a dependency to our package.
+
+        Open `Package.swift` from the Xcode project you just created.
+
+        @Code(name: "Package.swift", file: "IntroducingSlipstream-YourFirstSite-Workspace-1-5.swift")
       }
 
       @Step {
-        Back in Xcode, verify that your tailwind.config has now appeared.
+        Add Slipstream as a dependency.
 
-        You now have all the prerequisites to make your first Slipstream site!
+        Slipstream only supports iOS 17+ and macOS 14+, so we also need to define a minimum OS for our package.
 
-        @Image(source: "IntroducingSlipstream-YourFirstSite-1-5", alt: "The fully configured package in Xcode")   
+        @Code(name: "Package.swift", file: "IntroducingSlipstream-YourFirstSite-Workspace-1-6.swift")   
       }
 
-<!---->
-<!--      @Step {-->
-<!--        Open Package.swift.-->
-<!--        -->
-<!--        @Code(name: "Package.swift", file: "IntroducingSlipstream-YourFirstSite-step-3.swift")-->
-<!--      }-->
-<!---->
-<!--      @Step {-->
-<!--        Add Slipstream as a dependency.-->
-<!---->
-<!--        @Code(name: "Package.swift", file: "IntroducingSlipstream-YourFirstSite-step-4.swift")-->
-<!--      }-->
+      @Step {
+        We now have all of the prerequisites set up to make a Slipstream website!
+      }
     }
   }
 }