WIP

docs/canary/build-and-deploy/build.md

@@ -0,0 +1,38 @@
+---
+description: |
+  Building your Fresh app for production.
+---
+
+Fresh comes with built-in capabilities to compress assets to improve page load
+speed.
+
+## Building
+
+You can build your Fresh app by invoking the `deno task build` script. This will
+run the `dev.ts` file, which will then call Fresh's `Builder` class and generate
+optimized bundles for the browser. Put any additional tasks that should be done
+to prepare your app for deployment here. You can check if the build task was
+invoke by checking for `Deno.args.includes("build")`.
+
+Here is an example what the `dev.ts` file looks like for the Fresh documentation
+website:
+
+```ts dev.ts
+import { Builder } from "fresh/dev";
+import { app } from "./main.ts";
+import { tailwind } from "@fresh/plugin-tailwind";
+
+const builder = new Builder({ target: "safari12" });
+tailwind(builder, app, {});
+
+if (Deno.args.includes("build")) {
+  await builder.build(app);
+} else {
+  await builder.listen(app);
+}
+```
+
+## Preview your app
+
+You can preview your production app locally by running the `deno task start` or
+running `deno run -A main.ts` directly.

docs/canary/build-and-deploy/deno-deploy.md

@@ -0,0 +1,21 @@
+---
+description: |
+  Deploy Fresh to Deno Deploy which is an optimized edge platform.
+---
+
+[Deno Deploy](https://deno.com/deploy) is a hassle-free deployment platform for
+serverless TypeScript/JavaScript applications created by us. Fresh works best
+with that.
+
+## Creating a new Deploy project
+
+Head over to your [Deno Deploy Dashboard](https://dash.deno.com/projects) and
+click on the "New Project" button. Select the GitHub repository of your project
+and the branch you want to deploy from. The default branch is typically `main`
+for production deployments. Follow the rest of the wizard and finish deployment
+by clicking the "Deploy Project" button at the bottom. Each time new code lands
+in the `main` branch, a new deployment will be made to update your website
+automatically.
+
+> [info]: Deno deploy will automatically integrate with GitHub to create preview
+> deployments for every PR.

docs/canary/build-and-deploy/docker.md

@@ -0,0 +1,54 @@
+---
+description: |
+  Deploy Fresh via Docker yourself.
+---
+
+You can deploy Fresh to any platform that can run Docker containers. Docker is a
+tool to containerize projects and portably run them on any supported platform.
+
+## Creating a Docker image
+
+When packaging your Fresh app for Docker, it is important that you set the
+`DENO_DEPLOYMENT_ID` environment variable in your container. This variable needs
+to be set to an opaque string ID that represents the version of your application
+that is currently being run. This could be a Git commit hash, or a hash of all
+files in your project. It is critical for the function of Fresh that this ID
+changes when _any_ file in your project changes - if it doesn't, incorrect
+caching **will** cause your project to not function correctly.
+
+Here is an example `Dockerfile` for a Fresh project:
+
+```dockerfile Dockerfile
+# Pick the latest deno version here
+FROM denoland/deno:1.44.4
+
+ARG GIT_REVISION
+ENV DENO_DEPLOYMENT_ID=${GIT_REVISION}
+
+WORKDIR /app
+
+COPY . .
+RUN deno cache main.ts
+
+EXPOSE 8000
+
+CMD ["run", "-A", "main.ts"]
+```
+
+To build your Docker image inside of a Git repository:
+
+```sh Terminal
+$ docker build --build-arg GIT_REVISION=$(git rev-parse HEAD) -t my-fresh-app .
+```
+
+Then run your Docker container:
+
+```sh Terminal
+$ docker run -t -i -p 80:8000 my-fresh-app
+```
+
+To deploy to a cloud provider, push it to a container registry and follow their
+documentation.
+
+- [Amazon Web Services](https://docs.aws.amazon.com/AmazonECS/latest/userguide/create-container-image.html#create-container-image-push-ecr)
+- [Google Cloud](https://cloud.google.com/container-registry/docs/pushing-and-pulling)

docs/canary/getting-started/create-a-project.md

@@ -18,8 +18,12 @@ cd fresh-project
 ```
 
 This will scaffold out the new project, then switch ito the newly created
-directory. The folder structure of the newly created Fresh project will look
-roughly like this:
+directory.
+
+## Project Structure
+
+The folder structure of the newly created Fresh project will look roughly like
+this:
 
 ```sh
 fresh-project/
@@ -50,13 +54,13 @@ The most important fields in the `deno.json` file are the `"imports"` and
 - `"tasks"`: Registers [tasks](https://deno.land/manual/tools/task_runner) for
   your project. Run `deno task` to view all available tasks.
 
-> [info]: Fresh requires the following permissions to function:
+> [info]: The commands defined in the `"tasks"` section in `deno.json` pass `-A`
+> to `deno run` which enables all permissions. Fresh requires the following
+> permissions to function:
 >
 > - **`--allow-net`**: Required to start the HTTP server.
 > - **`--allow-read`**: Required to read (static) files from disk.
 > - **`--allow-env`**: Required to read environment variables that can be used
 >   to configure your project.
 > - **`--allow-run`**: Required to shell out to `deno` and `esbuild` under the
 >   hood generate the browser assets.
->
-> The tasks defined in `deno.json` have `-A` which allows all permissions.

docs/canary/getting-started/introduction.md

@@ -0,0 +1,30 @@
+---
+description: |
+  Fresh is a full stack modern web framework for JavaScript and TypeScript
+  developers, designed to make it trivial to create high-quality, performant,
+  and personalized web applications.
+---
+
+Fresh is an approchable full stack web framework, designed to make it trivial to
+create high-quality, performant, and personalized web applications. You can use
+it to create your home page, a blog, a large web application like GitHub or
+Twitter, or anything else you can think of.
+
+Fresh is built around the
+[island architecture](https://jasonformat.com/islands-architecture/) where every
+page is rendered on the server and only the JavaScript for the interactive areas
+on your page - so called islands - is shipped to the browser. This allows Fresh
+to minimize the amount of JavaScript that is sent to the browser to make your
+websites load faster.
+
+Fresh uses [Preact](https://preactjs.com) under the hood, which is a super tiny
+react-like framework. Whenever possible, we use standard
+[Web APIs](https://developer.mozilla.org/en-US/docs/Web/API) instead of
+re-inventing the wheel.
+
+## Project goals
+
+The Fresh project was created and is maintained by the [Deno](https://deno.com/)
+company with the goal of beign one of the fastest web frameworks and showing how
+Deno can be used to built highly optimized websites. Many experiences gained
+here in Fresh directly help making Deno better.

docs/canary/getting-started/tutorial.md

@@ -135,7 +135,7 @@ creating a route for viewing a single post. To do so, create a
 
 ```tsx routes/blog/[id].tsx
 import { HttpError, page } from "fresh";
-import { define } from "../utils/state.ts";
+import { define } from "../../utils/state.ts";
 import { type BlogPost, posts } from "../../blog-posts.ts";
 
 // This is a handler that runs before rendering the page. It
@@ -172,9 +172,52 @@ export default define.page<typeof handler>(function Post(props) {
 });
 ```
 
-### Adding a search page
+## Adding a search page for our blog
 
-asd
+To build our search page, we'll create a standard
+[`<form>`](https://developer.mozilla.org/en-US/docs/Learn/Forms/Your_first_form)
+that upon submission adds the search query in the URL. On the server we'll pull
+out that value of the incoming request, and search if any of our blog posts
+contains the query string.
+
+Since handlers run before rendering the components they are the perfect place to
+trigger the search. Once we've filtered down the result list, we can pass it to
+our component via the `page()` function.
+
+```tsx routes/blog/search.tsx
+import { page } from "fresh";
+import { define } from "../../utils/state.ts";
+import { posts } from "../../blog-posts.ts"
+
+export const handler = define.handler({
+  GET(ctx) {
+    const query = ctx.url.searchParams.get("q") || "";
+    const results = posts.filter((post) => post.title.includes(query));
+    return page({ results, query });
+  },
+});
+
+export default define.page<typeof handler>(props => {
+  const { results, query } = props.data;
+  return (
+    <div>
+      <form>
+        <input type="text" name="q" value={query} />
+        <button type="submit">Search</button>
+      </form>
+      <ul>
+        {results.map((post) => {
+          return (
+            <li key={post}>
+              <a href={`/blog/${post.slug}`}>{post.title}</a>
+            </li>
+          )
+        })}
+      </ul>
+    </div>
+  );
+}
+```
 
 ## Your first island
 
@@ -236,3 +279,8 @@ export default function AboutPage() {
 If you now visit http://localhost:8000/about you'll see our newly created
 counter on the page. Click the "increment" and "decrement" button and see the
 number update in the UI.
+
+## Deploying
+
+Congratulations, you've built your first Fresh app! You can now continue to
+[deploy it](#) to publish it on the internet.

docs/toc.ts

@@ -21,25 +21,19 @@ const toc: RawTableOfContents = {
       "the-canary-version": {
         title: "The canary version",
       },
-      introduction: {
-        title: "Introduction",
-        link: "latest",
-      },
       "getting-started": {
         title: "Getting Started",
         link: "latest",
         pages: [
+          ["introduction", "Introduction", "link:canary"],
           ["create-a-project", "Create a project", "link:canary"],
           ["tutorial", "Tutorial", "link:canary"],
-          ["form-submissions", "Form submissions", "link:latest"],
-          ["deploy-to-production", "Deploy to production", "link:latest"],
         ],
       },
       concepts: {
         title: "Concepts",
         link: "latest",
         pages: [
-          ["architecture", "Architecture", "link:latest"],
           ["server-components", "Server Components", "link:latest"],
           ["routing", "Routing", "link:latest"],
           ["routes", "Routes", "link:latest"],
@@ -59,6 +53,14 @@ const toc: RawTableOfContents = {
           ["server-configuration", "Server configuration", "link:latest"],
         ],
       },
+      "build-and-deploy": {
+        title: "Build and Deploy",
+        pages: [
+          ["build", "Building your app", "link:canary"],
+          ["deno-deploy", "Deno Deploy", "link:canary"],
+          ["docker", "Docker Image", "link:canary"],
+        ],
+      },
       integrations: {
         title: "Integrations",
         link: "latest",