doc: x.vweb static website capabilities (#20808)

vlang · Feb 13, 2024 · feb649f · feb649f
1 parent 1a7badc
commit feb649f
Show file tree

Hide file tree

Showing 5 changed files with 63 additions and 2 deletions.
diff --git a/examples/vweb/static_website/README.md b/examples/vweb/static_website/README.md
@@ -0,0 +1,9 @@
+# Host the vlang website
+
+Here is an example on how to use the vweb server's static capabilities,
+to host a static website from the `dist/` folder. Just run the server,
+it will be available at http://localhost:8080/ :
+
+```bash
+v run server.v
+```
diff --git a/examples/vweb/static_website/dist/another.html b/examples/vweb/static_website/dist/another.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Website other page</title>
+    </head>
+    <body>
+        <h1>Hello, another world!</h1>
+        <p>Welcome to this another page of a demo website.</p>
+        <p><a href="/">Click here</a> to go to main page.</p>
+    </body>
+</html>
diff --git a/examples/vweb/static_website/dist/index.html b/examples/vweb/static_website/dist/index.html
@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>Website main page</title>
+    </head>
+    <body>
+        <h1>Hello, world!</h1>
+        <p>Welcome to this demo website.</p>
+        <p><a href="another.html">Click here</a> to go to another page.</p>
+    </body>
+</html>
diff --git a/examples/vweb/static_website/server.v b/examples/vweb/static_website/server.v
@@ -0,0 +1,21 @@
+module main
+
+import x.vweb
+import os
+
+pub struct Context {
+	vweb.Context
+}
+
+pub struct App {
+	vweb.StaticHandler
+}
+
+fn main() {
+	// make sure that the working folder is the one, containing the executable,
+	// so that 'dist' is a valid relative path from it later:
+	os.chdir(os.dir(os.executable()))!
+	mut app := &App{}
+	app.handle_static('dist', true)!
+	vweb.run[App, Context](mut app, 8080)
+}
diff --git a/vlib/x/vweb/README.md b/vlib/x/vweb/README.md
@@ -284,7 +284,7 @@ pub fn (mut ctx Context) not_found() vweb.Result {
 }
 ```
 
-## Static files
+## Static files and website
 
 Vweb also provides a way of handling static files. We can mount a folder at the root
 of our web app, or at a custom route. To start using static files we have to embed
@@ -347,7 +347,12 @@ is available at `/`.
 // change the second argument to `true` to mount a folder at the app root
 app.handle_static('static', true)!
 ```
-We can now access `main.css` directly at http://localhost:8080/css/main.css
+We can now access `main.css` directly at http://localhost:8080/css/main.css.
+
+If a request is made to the root of a static folder, vweb will look for an
+`index.html` or `ìndex.htm` file and serve it if available.
+Thus, it's also a good way to host a complete website.
+A example is available [here](/examples/vweb/static_website).
 
 It is also possible to mount the `static` folder at a custom path.