Merge pull request 'Add Matrix integration' (#101) from matrix-integration into master

Reviewed-on: https://codeberg.org/Codeberg/Documentation/pulls/101

.eleventy.js

@@ -9,6 +9,15 @@ module.exports = function(eleventyConfig) {
   eleventyConfig.addPassthroughCopy("fonts")
 
   eleventyConfig.addShortcode("fas_icon", function(name) { return `<span class="fas fa-${name}"></span>` })
+  
+  // List of icons: https://codeberg.org/Codeberg/gitea/src/branch/codeberg/public/img/svg
+  eleventyConfig.addShortcode("gitea_icon", function(name) { 
+    const fetch = require('node-fetch');
+    fetch(`https://codeberg.org/img/svg/${name}.svg`)
+    .then(res => res.text())
+    .then(body => {return svg = body;});
+    return svg 
+  })
 
   return {
     dir: {

content/integrations/index.md

@@ -9,5 +9,3 @@ eleventyNavigation:
 These documentation pages contain information on how you can use third-party software with Codeberg.
 
 See also [awesome-gitea](https://gitea.com/gitea/awesome-gitea/src/branch/master/README.md) which lists projects that work with Gitea, the software which Codeberg is based on.
-
-Please note that this is a Work in Progress.

content/integrations/matrix.md

@@ -0,0 +1,44 @@
+---
+eleventyNavigation:
+  key: MatrixIntegration
+  title: Integrating with Matrix
+  parent: Integrations
+---
+
+This article will guide you through integrating Codeberg with Matrix, allowing repo updates to be automatically broadcast to your project's Matrix room.
+
+## Create a new Matrix account
+To set up the Matrix integration, it is recommended that you [create a new account](https://app.element.io/#/register) dedicated to broadcasting your repo updates. This will act as a bot account. You can create an account on your preferred Matrix server.
+
+## Getting an access token
+You will need an access token to give Codeberg access to send updates from your dedicated Matrix account. Here's how to do it on the Element web client.
+
+1. Make sure you are logged in to [Element](https://app.element.io/) with the Matrix account you created earlier in a private/incognito browser window.
+2. Click on your account name in the top-left corner, then click on `All Settings` in the dropdown.
+3. Optionally, you can set a display name and a profile picture for the account here.
+4. Navigate to the `Help & About` tab on the left.
+5. Scroll to the bottom and click on latter part of `Access Token: <click to reveal>` in the advanced section.
+6. Copy the access token that appears to a safe place.
+7. **Do not log out of Element.** This will invalidate your access token. Instead, you can simply close your private/incognito browser.
+
+> Alternatively, you can get an access token directly from the Matrix API. Read more at [Matrix's documentation](https://www.matrix.org/docs/guides/client-server-api#login).
+
+## Connecting your repo to your Matrix using webhooks
+Now we will connect the Matrix bot to your Codeberg repository. You will need admin permissions for the repo.
+
+<picture>
+  <source srcset="/assets/images/integrations/matrix/webhooks.webp" type="image/webp">
+  <img src="/assets/images/integrations/matrix/webhooks.png" alt="webhooks">
+</picture>
+
+1. In a web browser, go to your repo and click on the {% gitea_icon "octicon-tools" %} `Settings` button on the top right.
+2. Navigate to the `Webhooks` settings tab.
+3. Click on the `Add Webhook` button and select `Matrix`.
+4. Here are explanations for some key fields: 
+
+  - Homeserver URL: for example `https://matrix.org`
+  - Room ID: for example `!VTjWrzxSWgLJnHgDUd:matrix.org`. You can find this on Element in the `Advanced` tab for the room settings.
+  - Access token: paste the access token you got earlier.
+  - Message type: `m.text` is the most basic type of message which represents text. `m.notice` is intended for bots and [behaves differently](https://matrix.org/docs/spec/client_server/latest#m-notice.).
+
+Add your webhook, then click on the webhook URL. At the bottom now, there will be a `Test Delivery` button. Click this, and you will receive a message on your Matrix room! 

package-lock.json

@@ -7,7 +7,8 @@
       "devDependencies": {
         "@11ty/eleventy": "^0.12.1",
         "@11ty/eleventy-navigation": "^0.1.6",
-        "@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1"
+        "@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1",
+        "node-fetch": "^2.6.1"
       }
     },
     "node_modules/@11ty/dependency-tree": {
@@ -2246,6 +2247,15 @@
       "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==",
       "dev": true
     },
+    "node_modules/node-fetch": {
+      "version": "2.6.1",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.1.tgz",
+      "integrity": "sha512-V4aYg89jEoVRxRb2fJdAg8FHvI7cEyYdVAh94HH0UIK8oJxUfkjlDQN9RbMx+bEjP7+ggMiFRprSti032Oipxw==",
+      "dev": true,
+      "engines": {
+        "node": "4.x || >=6.0.0"
+      }
+    },
     "node_modules/nopt": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/nopt/-/nopt-4.0.3.tgz",
@@ -5644,6 +5654,12 @@
       "integrity": "sha512-Yd3UES5mWCSqR+qNT93S3UoYUkqAZ9lLg8a7g9rimsWmYGK8cVToA4/sF3RrshdyV3sAGMXVUmpMYOw+dLpOuw==",
       "dev": true
     },
+    "node-fetch": {
+      "version": "2.6.1",
+      "resolved": "https://registry.npmjs.org/node-fetch/-/node-fetch-2.6.1.tgz",
+      "integrity": "sha512-V4aYg89jEoVRxRb2fJdAg8FHvI7cEyYdVAh94HH0UIK8oJxUfkjlDQN9RbMx+bEjP7+ggMiFRprSti032Oipxw==",
+      "dev": true
+    },
     "nopt": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/nopt/-/nopt-4.0.3.tgz",

package.json

@@ -10,6 +10,7 @@
   "devDependencies": {
     "@11ty/eleventy": "^0.12.1",
     "@11ty/eleventy-navigation": "^0.1.6",
-    "@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1"
+    "@11ty/eleventy-plugin-syntaxhighlight": "^3.0.1",
+    "node-fetch": "^2.6.1"
   }
 }