Document and update menu order

#109

Author: MattiSG

README.md

@@ -1,5 +1,11 @@
 Open Terms Archive documentation.
 
+## Styleguide
+
+### Order of menu sections
+
+Pages and sections are ordered on the “end user” to “core team member” spectrum: the more up a page is in the menu, the more it is targeted at consumer end users, the more low it is the more it is targeted at committed contributors.
+
 ## Installation
 
 ### Dependencies

content/api.md

@@ -0,0 +1,4 @@
+---
+title: API
+weight: 7
+---

content/api/_index.md

@@ -0,0 +1,14 @@
+---
+title: Collection
+weight: 2
+---
+
+# Collection Web API [Beta]
+
+As Open Terms Archive is decentralised, each instance embarks its own API. The documentation relevant to the specific version of the engine on that instance is provided on that instance itself.
+
+The Collection API exposes JSON data over HTTP. Its [OpenAPI](https://swagger.io/specification/) specification can be found at `http://localhost:<port>/<basePath>/<API version>/docs`.
+
+That endpoint exposes both the OpenAPI specification if the requested `Content-Type` is JSON, and a Swagger UI for visual and interactive documentation otherwise.
+
+> For example, the [documentation](http://162.19.74.224/api/v1/docs) of the [Demo collection](https://github.com/OpenTermsArchive/demo-declarations) is publicly available for exploration.

content/api/collection.en.md

@@ -0,0 +1,24 @@
+---
+title: Federated
+weight: 3
+---
+
+# Federated Web API [Beta]
+
+Open Terms Archive is a decentralised system that tracks collections of services' terms across multiple servers. Each collection operates its own API, and the federated API unifies search and discovery across collections, fostering collaboration with external applications.
+
+The Federated Web API exposes JSON data over HTTP. Its [documentation](http://51.89.136.45/v1/docs/) is provided in a dedicated, interactive interface.
+
+That endpoint exposes both the [OpenAPI](https://swagger.io/specification/) specification if the requested `Content-Type` is JSON, and a Swagger UI for visual and interactive documentation otherwise.
+
+## Beta
+
+This API is offered as a preview, based on a first use case [defined](https://github.com/OpenTermsArchive/engine/issues/1016) with partner [ToS;DR](https://tosdr.org). Unexpected problems or missing functionality may arise. Please provide feedback through [issues](https://github.com/OpenTermsArchive/federated-api/issues) in the dedicated repository.
+
+## Source code
+
+The codebase for the Federated API is available on [`github.com/OpenTermsArchive/federated-api`](https://github.com/OpenTermsArchive/federated-api).
+
+## Deploying
+
+Deployment recipes are available in a [dedicated repository](https://github.com/OpenTermsArchive/deployment). Look at the [Federated API section](https://github.com/OpenTermsArchive/deployment#federated-api-application) on the README to know how to deploy the API.

content/api/federated.en.md

@@ -0,0 +1,54 @@
+---
+title: Node
+weight: 1
+---
+
+# Node.js API [Beta]
+
+As a Node module dependency, the engine exposes a JavaScript API that can be called in your own code. The following modules are available.
+
+## `fetch`
+
+The `fetch` module gets the MIME type and content of a document from its URL
+
+```js
+import fetch from '@opentermsarchive/engine/fetch';
+```
+
+Documentation on how to use `fetch` is provided [as JSDoc](/jsdoc/index.html).
+
+### Headless browser management
+
+If you pass the `executeClientScripts` option to `fetch`, a headless browser will be used to download and execute the page before serialising its DOM. For performance reasons, the starting and stopping of the browser is your responsibility to avoid instantiating a browser on each fetch. Here is an example on how to use this feature:
+
+```js
+import fetch, { launchHeadlessBrowser, stopHeadlessBrowser } from '@opentermsarchive/engine/fetch';
+
+await launchHeadlessBrowser();
+await fetch({ executeClientScripts: true, ... });
+await fetch({ executeClientScripts: true, ... });
+await fetch({ executeClientScripts: true, ... });
+await stopHeadlessBrowser();
+```
+
+The `fetch` module options are defined as a [`node-config` submodule](https://github.com/node-config/node-config/wiki/Sub-Module-Configuration). The default `fetcher` configuration can be overridden by adding a `fetcher` object to the local configuration file.
+
+## `extract`
+
+The `extract` module transforms HTML or PDF content into a Markdown string according to a declaration.
+
+```js
+import extract from '@opentermsarchive/engine/extract';
+```
+
+The `extract` function documentation is available [as JSDoc](/jsdoc/index.html).
+
+## `SourceDocument`
+
+The `SourceDocument` class encapsulates information about a terms' source document tracked by Open Terms Archive.
+
+```js
+import SourceDocument from '@opentermsarchive/engine/sourceDocument';
+```
+
+The `SourceDocument` format is defined [in source code](https://github.com/OpenTermsArchive/engine/tree/main/src/archivist/services/sourceDocument.js).

content/api/node.en.md

@@ -1,4 +1,4 @@
 ---
 title: Collections
-weight: 3
+weight: 5
 ---

content/collections/_index.md

@@ -1,6 +1,6 @@
 ---
 title: "Contributing terms"
-weight: 3
+weight: 4
 ---
 
 # Contributing terms

content/contributing-terms.en.md

@@ -1,6 +1,6 @@
 ---
 title: "Design principles"
-weight: 5
+weight: 10
 ---
 
 # Design principles

content/design-principles.en.md

@@ -16,7 +16,7 @@ A collection that **joins** the **federation** enjoys the following benefits:
 1. Visibility on the Open Terms Archive website lists of collections and datasets.
 2. Access to the Open Terms Archive GitHub organisation, administered by the Open Terms Archive core team.
 3. Collection logo provided by the Open Terms Archive core team.
-4. Referencing in the official [collections list](https://opentermsarchive.org/collections.json), enabling off-the-shelf discovery in the [Federated API]({{< relref "api" >}}).
+4. Referencing in the official [collections list](https://opentermsarchive.org/collections.json), enabling off-the-shelf discovery in the [Federated API]({{< relref "api/federated" >}}).
 5. Public announcement through all Open Terms Archive communication channels upon joining.
 
 ## Criteria