From 9df75594461d29a4b286977f3ce2927a853f9c8a Mon Sep 17 00:00:00 2001
From: Quentin Dufour <quentin@deuxfleurs.fr>
Date: Thu, 4 Nov 2021 10:51:15 +0100
Subject: Documentation for hugo, jekyll and publii

---
 doc/book/src/SUMMARY.md                    |  1 +
 doc/book/src/connect/websites.md           | 76 ++++++++++++++++++++++++++++++
 doc/book/src/cookbook/exposing_websites.md |  1 +
 3 files changed, 78 insertions(+)
 create mode 100644 doc/book/src/cookbook/exposing_websites.md

(limited to 'doc/book')

diff --git a/doc/book/src/SUMMARY.md b/doc/book/src/SUMMARY.md
index 236ceeec..a0a111fd 100644
--- a/doc/book/src/SUMMARY.md
+++ b/doc/book/src/SUMMARY.md
@@ -8,6 +8,7 @@
   - [Building from source](./cookbook/from_source.md)
   - [Integration with systemd](./cookbook/systemd.md)
   - [Configuring a reverse proxy](./cookbook/reverse_proxy.md)
+  - [Exposing buckets as websites](./cookbook/exposing_websites.md)
   - [Production Deployment](./cookbook/real_world.md)
   - [Recovering from failures](./cookbook/recovering.md)
 
diff --git a/doc/book/src/connect/websites.md b/doc/book/src/connect/websites.md
index c7c3d554..13e4cd4a 100644
--- a/doc/book/src/connect/websites.md
+++ b/doc/book/src/connect/websites.md
@@ -1 +1,77 @@
 # Websites (Hugo, Jekyll, Publii...)
+
+Garage is also suitable to host static websites.
+While they can be deployed with traditional CLI tools, some static website generators have integrated options to ease your workflow.
+
+## Hugo
+
+Add to your `config.toml` the following section:
+
+```toml
+[[deployment.targets]]
+ URL = "s3://<bucket>?endpoint=<endpoint>&disableSSL=<bool>&s3ForcePathStyle=true&region=garage"
+```
+
+For example:
+
+```toml
+[[deployment.targets]]
+ URL = "s3://my-blog?endpoint=localhost:9000&disableSSL=true&s3ForcePathStyle=true&region=garage"
+```
+
+Then inform hugo of your credentials:
+
+```bash
+export AWS_ACCESS_KEY_ID=GKxxx
+export AWS_SECRET_ACCESS_KEY=xxx
+```
+
+And finally deploy your website:
+
+```bsh
+hugo deploy
+```
+
+*External links:*
+  - [gocloud.dev > aws > Supported URL parameters](https://pkg.go.dev/gocloud.dev/aws?utm_source=godoc#ConfigFromURLParams)
+  - [Hugo Documentation > hugo deploy](https://gohugo.io/hosting-and-deployment/hugo-deploy/)
+
+## Publii
+
+It would require a patch either on Garage or on Publii to make both systems work.
+
+Currently, the proposed workaround is to deploy your website manually:
+  - On the left menu, click on Server, choose Manual Deployment (the logo looks like a compressed file)
+  - Set your website URL, keep Output type as "Non-compressed catalog"
+  - Click on Save changes
+  - Click on Sync your website (bottom left of the app)
+  - On the new page, click again on Sync your website
+  - Click on Get website files
+  - You need to synchronize the output folder you see in your file explorer, we will use minio client.
+
+Be sure that you [configured minio client](cli.html#minio-client-recommended).
+
+Then copy this output folder
+
+```bash
+mc mirror --overwrite output garage/my-site
+```
+
+## Generic (eg. Jekyll)
+
+Some tools do not support sending to a S3 backend but output a compiled folder on your system.
+We can then use any CLI tool to upload this content to our S3 target.
+
+First, start by [configuring minio client](cli.html#minio-client-recommended).
+
+Then build your website:
+
+```bash
+jekyll build
+```
+
+And copy jekyll's output folder on S3:
+
+```bash
+mc mirror --overwrite _site garage/my-site
+```
diff --git a/doc/book/src/cookbook/exposing_websites.md b/doc/book/src/cookbook/exposing_websites.md
new file mode 100644
index 00000000..58e1f018
--- /dev/null
+++ b/doc/book/src/cookbook/exposing_websites.md
@@ -0,0 +1 @@
+# Exposing websites
-- 
cgit v1.2.3