Finish porting Data Modules docs

Author: raucao

docs/data-modules/defining-a-module.md

@@ -3,35 +3,37 @@
 A data module is just a JavaScript object containing a module name and a
 builder function.
 
-The builder function receives two
-`base clients </js-api/base-client>`{.interpreted-text role="doc"} when
-loaded: one for private data stored in `/my-module-name/` and one for
-public data stored in `/public/my-module-name/`. It must return an
-object, defining the properties and functions to be used in the app as
-`exports`:
+The builder function receives two [BaseClient][2] instances when loaded: one
+for private data stored in `/my-module-name/` and one for public data stored in
+`/public/my-module-name/`. A module must return an object, with the properties
+and functions to be used in an app as `exports`:
 
 ``` javascript
-var Bookmarks = { name: 'bookmarks', builder: function(privateClient, publicClient) {
+const Bookmarks = { name: 'bookmarks', builder: function(privateClient, publicClient) {
   return {
     exports: {
-     addBookmark: function() {}
+      addBookmark: function() {}
     }
   }
 }};
 ```
 
-You can then load it into your
-`RemoteStorage </js-api/remotestorage>`{.interpreted-text role="doc"}
-instance either on initialization, or later using the `addModule()`
-function:
+You can then load the module into your [RemoteStorage][1] instance, either on
+initialization or later using the `addModule()` function:
 
-    const remoteStorage = new RemoteStorage({ modules: [ Bookmarks ] });
+```js
+const remoteStorage = new RemoteStorage({ modules: [ Bookmarks ] });
 
-    // or later:
+// or later:
+remoteStorage.addModule(Bookmarks);
+```
 
-    remoteStorage.addModule(Bookmarks);
+The module will then be accessible on the instance by its name, allowing
+you to call the functions and properties that it exports:
 
-It will then be available on the instance as its module name, allowing
-you to call the functions and properties that the module exports:
+```js
+remoteStorage.bookmarks.addBookmark()
+```
 
-    remoteStorage.bookmarks.addBookmark();
+[1]: ../api/remotestorage/classes/RemoteStorage.html
+[2]: ../api/baseclient/classes/BaseClient.html

docs/data-modules/defining-data-types.md

@@ -1,14 +1,16 @@
 # Defining data types
 
-Data types can be defined using the `declareType()` method. It expects a
-name (which you can later use with `storeObject()`), as well as a [JSON
-Schema](http://json-schema.org) object defining the actual structure and
-formatting of your data.
+Data types can be defined using the
+[declareType()](../api/baseclient/classes/BaseClient.html#declaretype) method.
+It expects a name (which you can later use with
+[storeObject()](../api/baseclient/classes/BaseClient.html#storeobject), as well
+as a [JSON Schema](http://json-schema.org) object defining the actual structure
+and formatting of your data.
 
 Consider this simplified example of an archive bookmark:
 
-``` javascript
-var Bookmarks = { name: 'bookmarks', builder: function(privateClient, publicClient) {
+```js
+const Bookmarks = { name: 'bookmarks', builder: function(privateClient, publicClient) {
 
   privateClient.declareType('archive-bookmark', {
     "type": "object",
@@ -40,48 +42,42 @@ can add a function for storing them. This will actually validate the
 incoming data against the type\'s schema, and reject the promise with
 detailed validation errors in case the data format doesn\'t match:
 
-    var Bookmarks = { name: 'bookmarks', builder: function(privateClient, publicClient) {
-      // ...
+```js
+const Bookmarks = { name: 'bookmarks', builder: function(privateClient, publicClient) {
+// ...
 
-      return {
-        exports: {
+return {
+  exports: {
+    add: function (bookmark) {
+      bookmark.id = md5Hash(bookmark.url); // hash URL for nice ID
+      var path = "archive/" + bookmark.id; // use hashed URL as filename as well
 
-          add: function (bookmark) {
-            bookmark.id = md5Hash(bookmark.url); // hash URL for nice ID
-            var path = "archive/" + bookmark.id; // use hashed URL as filename as well
+      return privateClient.storeObject("archive-bookmark", path, bookmark).
+        then(function() {
+          return bookmark; // return bookmark with added ID property
+        });
+    }
+  }
+};
 
-            return privateClient.storeObject("archive-bookmark", path, bookmark).
-              then(function() {
-                return bookmark; // return bookmark with added ID property
-              });
-          }
+// and in your app:
 
-        }
-      }
-    }};
-
-    // and in your app:
-
-    remoteStorage.bookmarks.add({
-      title: 'Unhosted Web Apps',
-      url: 'https://unhosted.org',
-      tags: ['unhosted', 'remotestorage', 'offline-first']
-    })
-    .then(() => {
-      console.log('stored bookmark successfully');
-    })
-    .catch((err) => {
-      console.error('validation error:', err);
-    });
-
-::: hint
-::: title
-Hint
-:::
+remoteStorage.bookmarks.add({
+  title: 'Unhosted Web Apps',
+  url: 'https://unhosted.org',
+  tags: ['unhosted', 'remotestorage', 'offline-first']
+})
+.then(() => {
+  console.log('stored bookmark successfully');
+})
+.catch((err) => {
+  console.error('validation error:', err);
+});
+```
 
-JSON Schema is very powerful and flexible. If you want to learn more
+::: tip
+JSON Schema is rather powerful and flexible. If you want to learn more
 about it, check out the free e-book [Understanding JSON
 Schema](https://spacetelescope.github.io/understanding-json-schema/) for
-example. The complete official specs can be found at
-<http://json-schema.org/documentation.html>
+example. The complete documentation can be found on [json-schema.org](https://json-schema.org)
 :::

docs/data-modules/index.md

@@ -8,24 +8,22 @@ Traditional Web apps make this possible with custom, proprietary APIs,
 which are dependent on the app provider. Third party developers usually
 need to register an application with the original provider to access
 that data via the API, and this access can be revoked at any time.
-remoteStorage and [unhosted web apps](https://unhosted.org) in general
-give end users ultimate control over which apps have access to their
-data.
 
-In order to make it easy and safe for your app data to be compatible
-with other apps, we created the concept of data modules for rs.js, which
-can be shared and developed collaboratively in the open.
+remoteStorage apps (and [unhosted web apps](https://unhosted.org) in general)
+give end users ultimate control over which apps have access to their data. This
+makes users more independent from single app providers, and ensures that any
+app developer can create new apps for users' existing data.
+
+In order to make it easy and safe for your app data to be compatible with other
+apps, we created the concept of data modules for remoteStorage.js. They are
+little add-on libraries, which can be shared between apps and developers, and
+that ideally are developed collaboratively in the open.
 
 Data modules can contain as much or as little functionality as desired,
-from defining data formats and types to data validation, formatting,
+from defining data formats and types, to data validation, formatting,
 processing, transformation, encryption, indexing, and other use cases.
 
 Data modules make your app and its data interoperable with other apps.
-Sharing your modules is generally encouraged, but it is also possible to
+Sharing your modules is generally encouraged, but it's also possible to
 encapsulate custom functionality in a custom module made just for your
 app.
-
-::: {.toctree caption="Contents" maxdepth="2"}
-data-modules/defining-a-module data-modules/defining-data-types
-data-modules/publishing-and-finding-modules
-:::

docs/data-modules/publishing-and-finding-modules.md

@@ -8,51 +8,23 @@ The recommended way for publishing data modules is as
 Our naming convention for rs.js modules is
 `remotestorage-module-mymodulename`. Thus, you can also find them by
 [searching npm for
-\"remotestorage-module\"](https://www.npmjs.com/search?q=remotestorage-module).
+"remotestorage-module"](https://www.npmjs.com/search?q=remotestorage-module).
 
-You can also add \"remotestorage-module\" and \"remotestorage\" to the
+You can also add "remotestorage-module" and "remotestorage" to the
 `keywords` property of your `package.json`.
 
 ## GitHub & Co.
 
 If you use GitHub ‒ or any other code hosting/collaboration platform for
-that matter ‒ for publishing your module\'s source code, please use the
+that matter ‒ for publishing your module's source code, please use the
 same naming convention as for the npm module for the repo name. And
-it\'s a good idea to add the topic/tag/label \"remotestorage-module\"
+it's a good idea to add the topic/tag/label "remotestorage-module"
 there as well, of course.
 
 <https://github.com/topics/remotestorage-module>
 
-::: hint
-::: title
-Hint
-:::
-
-With npm, you can also install modules directly from a Git repo or
+::: tip
+With npm, you can also install modules directly from a Git repository or
 GitHub, pointing to just the repo or a branch name, tag, or commit:
-<https://docs.npmjs.com/files/package.json#github-urls>
-:::
-
-## Examples
-
--   For a real-world example of a data module package, see e.g. the
-    shares module [on
-    GitHub](https://github.com/skddc/remotestorage-module-shares) and
-    [on npm](https://www.npmjs.com/package/remotestorage-module-shares).
-    Check out `webpack.config.js` and the source code in `index.js` to
-    see how it is built and exported.
-
-::: note
-::: title
-Note
-:::
-
-Unfortunately, we didn\'t have any package management for data modules
-before rs.js 1.0. To be fair, JavaScript package managers weren\'t
-actually a thing yet, when this functionality was added to the library.
-However, it means we\'re still in the process of porting and publishing
-modules and you won\'t find very many existing data modules on npm right
-now. You can check the [old modules
-repo](https://github.com/remotestorage/modules) for source code of
-legacy modules.
+https://docs.npmjs.com/cli/v10/configuring-npm/package-json#github-urls
 :::