Add sections as documentation pages

content/documentation/connect/_index.md

@@ -2,5 +2,47 @@
 title = "Integrations"
 weight = 3
 sort_by = "weight"
-redirect_to = "documentation/connect/apps/"
+template = "documentation.html"
 +++
+
+
+
+Garage implements the Amazon S3 protocol, which makes it compatible with many existing software programs.
+
+In particular, you will find here instructions to connect it with:
+
+  - [web applications](./apps.md)
+  - [website hosting](./websites.md)
+  - [software repositories](./repositories.md)
+  - [CLI tools](./cli.md)
+  - [your own code](./code.md)
+
+### Generic instructions
+
+To configure S3-compatible software to interact with Garage,
+you will need the following parameters:
+
+- An **API endpoint**: this corresponds to the HTTP or HTTPS address
+  used to contact the Garage server. When runing Garage locally this will usually
+  be `http://127.0.0.1:3900`. In a real-world setting, you would usually have a reverse-proxy
+  that adds TLS support and makes your Garage server available under a public hostname
+  such as `https://garage.example.com`.
+
+- An **API access key** and its associated **secret key**. These usually look something
+  like this: `GK3515373e4c851ebaad366558` (access key),
+  `7d37d093435a41f2aab8f13c19ba067d9776c90215f56614adad6ece597dbb34` (secret key).
+  These keys are created and managed using the `garage` CLI, as explained in the
+  [quick start](../quick_start/index.md) guide.
+
+Most S3 clients can be configured easily with these parameters,
+provided that you follow the following guidelines:
+
+- **Force path style:** Garage does not support DNS-style buckets, which are now by default
+  on Amazon S3. Instead, Garage uses the legacy path-style bucket addressing.
+  Remember to configure your client to acknowledge this fact.
+
+- **Configuring the S3 region:** Garage requires your client to talk to the correct "S3 region",
+  which is set in the configuration file. This is often set just to `garage`.
+  If this is not configured explicitly, clients usually try to talk to region `us-east-1`.
+  Garage should normally redirect your client to the correct region,
+  but in case your client does not support this you might have to configure it manually.

content/documentation/cookbook/_index.md

@@ -1,6 +1,32 @@
 +++
 title="Cookbook"
+template = "documentation.html"
 weight = 2
 sort_by = "weight"
-redirect_to = "documentation/cookbook/real-world/"
 +++
+
+
+A cookbook, when you cook, is a collection of recipes.
+Similarly, Garage's cookbook contains a collection of recipes that are known to works well!
+This chapter could also be referred as "Tutorials" or "Best practices".
+
+- **[Multi-node deployment](real_world.md):** This page will walk you through all of the necessary
+  steps to deploy Garage in a real-world setting.
+
+- **[Building from source](from_source.md):** This page explains how to build Garage from
+  source in case a binary is not provided for your architecture, or if you want to
+  hack with us!
+
+- **[Integration with Systemd](systemd.md):** This page explains how to run Garage
+  as a Systemd service (instead of as a Docker container).
+
+- **[Configuring a gateway node](gateways.md):** This page explains how to run a gateway node in a Garage cluster, i.e. a Garage node that doesn't store data but accelerates access to data present on the other nodes.
+
+- **[Hosting a website](exposing_websites.md):** This page explains how to use Garage
+  to host a static website.
+
+- **[Configuring a reverse-proxy](reverse_proxy.md):** This page explains how to configure a reverse-proxy to add TLS support to your S3 api endpoint.
+
+- **[Recovering from failures](recovering.md):** Garage's first selling point is resilience
+  to hardware failures. This section explains how to recover from such a failure in the
+  best possible way.

content/documentation/design/_index.md

@@ -2,5 +2,31 @@
 title = "Design"
 weight = 5
 sort_by = "weight"
-redirect_to = "documentation/design/goals/"
+template = "documentation.html"
 +++
+
+
+The design section helps you to see Garage from a "big picture"
+perspective.  It will allow you to understand if Garage is a good fit for
+you, how to better use it, how to contribute to it, what can Garage could
+and could not do, etc.
+
+- **[Goals and use cases](goals.md):** This page explains why Garage was concieved and what practical use cases it targets.
+
+- **[Related work](related_work.md):** This pages presents the theoretical background on which Garage is built, and describes other software storage solutions and why they didn't work for us.
+
+- **[Internals](internals.md):** This page enters into more details on how Garage manages data internally.
+
+## Talks
+
+We love to talk and hear about Garage, that's why we keep a log here:
+
+  - [(fr, 2021-11-13, video) Garage : Mille et une façons de stocker vos données](https://video.tedomum.net/w/moYKcv198dyMrT8hCS5jz9) and [slides (html)](https://rfid.deuxfleurs.fr/presentations/2021-11-13/garage/) - during [RFID#1](https://rfid.deuxfleurs.fr/programme/2021-11-13/) event
+
+  - [(en, 2021-04-28) Distributed object storage is centralised](https://git.deuxfleurs.fr/Deuxfleurs/garage/raw/commit/b1f60579a13d3c5eba7f74b1775c84639ea9b51a/doc/talks/2021-04-28_spirals-team/talk.pdf)
+
+  - [(fr, 2020-12-02) Garage : jouer dans la cour des grands quand on est un hébergeur associatif](https://git.deuxfleurs.fr/Deuxfleurs/garage/raw/commit/b1f60579a13d3c5eba7f74b1775c84639ea9b51a/doc/talks/2020-12-02_wide-team/talk.pdf)
+
+*Did you write or talk about Garage? [Open a pull request](https://git.deuxfleurs.fr/Deuxfleurs/garage/) to add a link here!*
+
+

content/documentation/development/_index.md

@@ -2,5 +2,19 @@
 title = "Development"
 weight = 6
 sort_by = "weight"
-redirect_to = "documentation/development/devenv/"
+template = "documentation.html"
 +++
+
+
+Now that you are a Garage expert, you want to enhance it, you are in the right place!
+We discuss here how to hack on Garage, how we manage its development, etc.
+
+## Rust API (docs.rs)
+If you encounter a specific bug in Garage or plan to patch it, you may jump directly to the source code's documentation!
+
+  - [garage\_api](https://docs.rs/garage_api/latest/garage_api/) - contains the S3 standard API endpoint
+  - [garage\_model](https://docs.rs/garage_model/latest/garage_model/) - contains Garage's model built on the table abstraction
+  - [garage\_rpc](https://docs.rs/garage_rpc/latest/garage_rpc/) - contains Garage's federation protocol
+  - [garage\_table](https://docs.rs/garage_table/latest/garage_table/) - contains core Garage's CRDT datatypes
+  - [garage\_util](https://docs.rs/garage_util/latest/garage_util/) - contains garage helpers
+  - [garage\_web](https://docs.rs/garage_web/latest/garage_web/) - contains the S3 website endpoint

content/documentation/quick_start.md

@@ -3,7 +3,6 @@ title = "Quick Start"
 weight = 5
 +++
 
-# Quick Start
 
 Let's start your Garage journey!
 In this chapter, we explain how to deploy Garage as a single-node server

content/documentation/reference-manual/_index.md

@@ -2,5 +2,10 @@
 title = "Reference Manual"
 weight = 4
 sort_by = "weight"
-redirect_to = "documentation/reference-manual/configuration/"
+template = "documentation.html"
 +++
+
+
+A reference manual contains some extensive descriptions about the features and the behaviour of the software.
+Reading of this chapter is recommended once you have a good knowledge/understanding of Garage.
+It will be useful if you want to tune it or to use it in some exotic conditions.

content/documentation/working-documents/_index.md

@@ -2,5 +2,13 @@
 title = "Working Documents"
 weight = 7
 sort_by = "weight"
-redirect_to = "documentation/working-documents/compatibility-target/"
+template = "documentation.html"
 +++
+
+
+Working documents are documents that reflect the fact that Garage is a software that evolves quickly.
+They are a way to communicate our ideas, our changes, and so on before or while we are implementing them in Garage.
+If you like to live on the edge, it could also serve as a documentation of our next features to be released.
+
+Ideally, once the feature/patch has been merged, the working document should serve as a source to 
+update the rest of the documentation and then be removed.

templates/documentation.html

@@ -1,11 +1,13 @@
 {% extends 'base.html' %}
 
 {% block title %}
-    {{ config.title }} | {{ page.title }}
+  {{ config.title }} | {% if page %}{{ page.title }}{% else %}{{ section.title }}{% endif %}
 {% endblock %}
 
 {% block content %}
-    {% set section = get_section(path="documentation/_index.md") %}
+    {% if not page %}
+      {% set page = section %}
+    {% endif %}
     <section id="documentation-section" class="section overflow-x-hidden">
         <div class="grid grid-cols-1 xl:grid-cols-5">
             {% include "partials/doc/global_toc.html" %}
@@ -45,6 +47,9 @@
 {% endblock %}
 
 {% block custom_js %}
+    {% if not page %}
+      {% set page = section %}
+    {% endif %}
     {% if page.toc %}
         {% include "partials/doc/toc_script.html" %}
     {% endif %}

templates/partials/doc/global_toc.html

@@ -1,3 +1,4 @@
+  {% set section = get_section(path="documentation/_index.md") %}
 <aside id="global_toc" class="relative col-span-1 h-full bg-gray-100 shadow-inner border-r border-t border-gray-200">
     {% if section.subsections %}
         <ul id="main-toc-menu" class="space-y-2 px-6 py-3 list-none">
@@ -6,8 +7,8 @@
                 {% for page in section.pages %}
                     <a 
                         href="{{ page.permalink | safe }}"
-                        class="docPage block pl-2 py-1 border-l rounded-r border-garage-orange hover:bg-garage-orange hover:bg-opacity-20
-                        {% if current_path == page.path %} activePage border-l-4 text-garage-orange font-semibold border-opacity-100 border-garage-orange {% endif %}">
+                        class="bg-white border border-garage-orange block p-1 rounded block font-semibold hover:bg-garage-orange hover:bg-opacity-20
+                        {% if current_path == page.path %} activePage text-garage-orange border-opacity-100 border-garage-orange {% endif %}">
                         {{ page.title }}
                     </a>
                 {% endfor %}
@@ -18,7 +19,9 @@
             <li class="relative">
                 <a 
                     href="{{ h1.permalink | safe }}"
-                    class="bg-white border border-garage-orange block p-1 rounded-r rounded-tl font-semibold text-gray-800">
+                    class="bg-white border border-garage-orange block p-1 rounded-r rounded-tl font-semibold 
+                           {% if current_path == h1.path %} activePage text-garage-orange font-semibold border-opacity-100 border-garage-orange {% else %}text-gray-800{% endif %}
+                    ">
                     {{ h1.title }}
                 </a>
                 {% if h1.pages %}