docs: move getting started to own page

egil · May 4, 2024 · 6e67bb4 · 6e67bb4
1 parent 3ae5ddd
commit 6e67bb4
Show file tree

Hide file tree

Showing 3 changed files with 112 additions and 104 deletions.
diff --git a/README.md b/README.md
@@ -19,109 +19,8 @@ The following Blazor Web Apps (Htmxor) are used to test Htmxor and demo the capa
 - [Htmxor - TestApp](https://github.com/egil/Htmxor/tree/main/test/Htmxor.TestApp)
 - [Minimal Htmxor App template](https://github.com/egil/Htmxor/tree/main/samples/MinimalHtmxorApp)
 
-## Getting started
-
-Download the [Minimal Htmxor App template](https://github.com/egil/Htmxor/tree/main/samples/MinimalHtmxorApp) for a complete (but) minimal Blazor + htmx app, with various small examples included.
-
-Starting fresh, here is what you need to do.
-
-1. Include the [Htmxor package from NuGet](https://www.nuget.org/packages/Htmxor).
-
-2. Modify `Program.cs` to look like this:
-
-```diff
-  var builder = WebApplication.CreateBuilder(args);
-
-  // Add services to the container.
-  builder.Services
-      .AddRazorComponents()
-+     .AddHtmx();
-
-  var app = builder.Build();
-
-  // Configure the HTTP request pipeline.
-  if (!app.Environment.IsDevelopment())
-  {
-      app.UseExceptionHandler("/Error", createScopeForErrors: true);
-      // The default HSTS value is 30 days. You may want to change this for production scenarios, see https://aka.ms/aspnetcore-hsts.
-      app.UseHsts();
-  }
-
-  app.UseHttpsRedirection();
-
-  app.UseStaticFiles();
-  app.UseAntiforgery();
-+ app.UseHtmxAntiforgery();
-  app.MapRazorComponents<App>()
-+    .AddHtmxorComponentEndpoints(app);
-
-  app.Run();
-```
-
-Note, there is an overload for `AddHtmx(options => { ... })` that allows you to configure all [htmx's configuration options](https://htmx.org/reference/#config) for your app.
-
-3. Modify `App.razor` to look like this:
-
-```diff
-  <!DOCTYPE html>
-  <html lang="en">
-
-  <head>
-      <meta charset="utf-8" />
-      <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-      <base href="/" />
-      <link rel="stylesheet" href="bootstrap/bootstrap.min.css" />
-      <link rel="stylesheet" href="app.css" />
-      <link rel="stylesheet" href="MinimalHtmxorApp.styles.css" />
-      <link rel="icon" type="image/png" href="favicon.png" />
-+     <HtmxHeadOutlet />
-      <HeadOutlet />
-  </head>
-
-+ <!-- Adding hx-boost="true" is optional. Learn more here: https://htmx.org/attributes/hx-boost/ -->
-+ <body hx-boost="true">
-      <Routes />
-
--     <script src="_framework/blazor.web.js"></script>
-  </body>
-
-  </html>
-```
-
-4. Optionally, create a htmx-request specific layout, e.g., `/Components/Layout/HtmxorLayout.razor`:
-
-```razor
-@* 
-This is a default layout component that is used with htmx requests.
-It only includes the <HeadOutlet /> which makes it possible to update the 
-page title during htmx requests by using the <PageTitle></PageTitle> component.
-*@
-@inherits LayoutComponentBase
-<HeadOutlet />
-@Body
-```
-
-5. Optionally, update `_Imports.razor`:
-
-```diff
-  @using System.Net.Http
-  @using System.Net.Http.Json
-  @using Microsoft.AspNetCore.Components.Forms
-  @using Microsoft.AspNetCore.Components.Routing
-  @using Microsoft.AspNetCore.Components.Web
-  @using static Microsoft.AspNetCore.Components.Web.RenderMode
-  @using Microsoft.AspNetCore.Components.Web.Virtualization
-  @using Microsoft.JSInterop
-+ @using Htmxor.Components
-+ @using Htmxor.Http
-+ @using Htmxor
-
-+ @attribute [HxLayout(typeof(HtmxorLayout))]
-```
-
-Note that we set up the custom layout for all components by defining the `[HxLayout(typeof(HtmxorLayout))]` attribute in the `_Imports.razor` file.
-
 ## Documentation
 
-- **[Routing in Htmxor](/docs/routing.md)**: Covers how routing works in Htmor, compared to Blazor Static Web apps. 
+- **[Getting Started](/docs/getting-started.md)** - how to create a new Htmxor/Blazor project.
+- **[Routing in Htmxor](/docs/routing.md)** - there are two types of routing in Htmxor, standard and direct.
 
diff --git a/docs/getting-started.md b/docs/getting-started.md
@@ -0,0 +1,109 @@
+# Getting Started
+
+To create a minimal Blazor + htmx app with various examples, download the [Minimal Htmxor App template](https://github.com/egil/Htmxor/tree/main/samples/MinimalHtmxorApp).
+
+To start fresh, follow these steps:
+
+1. **Add the Htmxor Package**
+
+   Install the [Htmxor package from NuGet](https://www.nuget.org/packages/Htmxor).
+
+
+2. **Update `Program.cs`**
+
+   Modify `Program.cs` to include Htmxor services and middleware:
+
+	```diff
+	  var builder = WebApplication.CreateBuilder(args);
+	  
+	  // Add services to the container.
+	  builder.Services
+	  	.AddRazorComponents()
+	+   .AddHtmx();
+	  
+	  var app = builder.Build();
+	  
+	  // Configure the HTTP request pipeline.
+	  if (!app.Environment.IsDevelopment())
+	  {
+	  	app.UseExceptionHandler("/Error", createScopeForErrors: true);
+	  	app.UseHsts();
+	  }
+	  
+	  app.UseHttpsRedirection();
+	  
+	  app.UseStaticFiles();
+	  app.UseAntiforgery();
+	+ app.UseHtmxAntiforgery();
+	  app.MapRazorComponents<App>()
+	+    .AddHtmxorComponentEndpoints(app);
+	  
+	  app.Run();
+	```
+	Note: You can use `AddHtmx(options => { ... })` to change [htmx's config](https://htmx.org/reference/#config) for your app.
+
+3. **Update App.razor**  
+
+   Modify `App.razor` to include Htmxor components:
+
+	```diff
+	  <!DOCTYPE html>
+	  <html lang="en">
+	  
+	  <head>
+	  	<meta charset="utf-8" />
+	  	<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+	  	<base href="/" />
+	  	<link rel="stylesheet" href="bootstrap/bootstrap.min.css" />
+	  	<link rel="stylesheet" href="app.css" />
+	  	<link rel="stylesheet" href="MinimalHtmxorApp.styles.css" />
+	  	<link rel="icon" type="image/png" href="favicon.png" />
+	+   <HtmxHeadOutlet />
+	  	<HeadOutlet />
+	  </head>
+	  
+	  <!-- 
+	    Adding hx-boost="true" is optional. 
+	    Learn more here: https://htmx.org/  attributes/hx-boost/ 
+	  -->
+	+ <body hx-boost="true">
+	  	<Routes />
+
+	-   <script src="_framework/blazor.web.js"></script>
+	  </body>
+	  
+	  </html>
+	```
+
+4. **Create an Optional Direct Request Layout**
+
+   Optionally, create a layout that will be used during [direct routing](routing.md#direct-routing), e.g., `/Components/Layout/HtmxorLayout.razor`:
+
+	```razor
+	@inherits HtmxLayoutComponentBase
+	@Body
+	```
+
+	The `HtmxLayoutComponentBase` includes the `<HeadOutlet>` component. This makes it possible to use the `<PageTitle>` component during htmx requests to update the page title. 
+
+5. **Update _Imports.razor (Optional)**
+
+   Modify _Imports.razor to include Htmxor namespaces and set a default layout:
+
+	```diff
+	  @using System.Net.Http
+	  @using System.Net.Http.Json
+	  @using Microsoft.AspNetCore.Components.Forms
+	  @using Microsoft.AspNetCore.Components.Routing
+	  @using Microsoft.AspNetCore.Components.Web
+	  @using static Microsoft.AspNetCore.Components.Web.RenderMode
+	  @using Microsoft.AspNetCore.Components.Web.Virtualization
+	  @using Microsoft.JSInterop
+	+ @using Htmxor.Components
+	+ @using Htmxor.Http
+	+ @using Htmxor
+
+	+ @attribute [HtmxLayout(typeof(HtmxorLayout))]
+	```
+
+	Note that we set up the custom layout for all components by defining the `[HtmxLayout(typeof(HtmxorLayout))]` attribute in the `_Imports.razor` file.
diff --git a/docs/routing.md b/docs/routing.md
@@ -33,7 +33,7 @@ HTTP GET /my-page
 App -> Routes --> MainLayout --> MyPage
 ```
 
-## Direct Routing:
+## Direct Routing
 
 Direct routing bypasses the root component (`App.razor`) and the standard layout (`MainLayout`). Instead, it routes directly to the component that matches the request.