docs: add documentation center (#75)

.dockerignore

@@ -1,4 +1,5 @@
 .git/
 node_modules/
 deployment/
+docs/
 Dockerfile

.github/workflows/cd.yml

@@ -54,3 +54,39 @@ jobs:
           password: ${{ secrets.DOCKER_PASSWORD }}
           repository: ${{ github.repository }}
           enable-url-completion: true
+
+  publish-docs:
+    environment: Production
+    name: "Deploy documentation"
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build documentations
+        run: npm run build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./build
+          # The following lines assign commit authorship to the official
+          # GH-Actions bot for deploys to `gh-pages` branch:
+          # https://github.com/actions/checkout/issues/13#issuecomment-724415212
+          # The GH actions bot is used by default if you didn't specify the two fields.
+          # You can swap them out with your own user credentials.
+          user_name: github-actions[bot]
+          user_email: 41898282+github-actions[bot]@users.noreply.github.com

.github/workflows/ci.yml

@@ -6,6 +6,28 @@ on:
   pull_request:
 
 jobs:
+  build-docs:
+    name: "Build documentation"
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Check out the repo
+        uses: actions/checkout@v4
+
+      - name: Use Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: '18.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build documentations
+        run: npm run build
+
   commitlint:
     name: "Commitlint Validation"
     runs-on: ubuntu-latest

docs/.gitignore

@@ -0,0 +1,20 @@
+# Dependencies
+/node_modules
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

docs/README.md

@@ -0,0 +1,25 @@
+# Website
+
+This documentation center is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
+
+### Installation
+
+```
+$ npm ci
+```
+
+### Local Development
+
+```
+$ npm start
+```
+
+This command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server.
+
+### Build
+
+```
+$ npm build
+```
+
+This command generates static content into the `build` directory and can be served using any static contents hosting service.

docs/babel.config.js

@@ -0,0 +1,3 @@
+module.exports = {
+    presets: [require.resolve('@docusaurus/core/lib/babel/preset')],
+};

docs/docs/configuration/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Configuration",
+  "position": 2,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/configuration/cron.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 3
+title: Configure with Cron
+tags: [
+  'configuration',
+  'cron',
+]
+---
+
+# ⏰ Cron configuration
+
+## Define environment variables
+3 types of environment variables are required to run the sync:
+- **Core variables**: required in situations, get them [here](/docs/resources/environment-variables#core-variables)
+- **Sync variables**: required for the sync **you** want, get them [here](/docs/resources/environment-variables#synchronization-)
+- **Cron variables**: required for the cron, get them [here](/docs/resources/environment-variables#configuration-with-cron-)

docs/docs/configuration/docker.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 2
+title: Configure with Docker
+tags: [
+  'configuration',
+  'docker',
+]
+---
+
+# 🐳 Docker configuration
+
+## Define environment variables
+3 types of environment variables are required to run the sync:
+- **Core variables**: required in situations, get them [here](/docs/resources/environment-variables#core-variables)
+- **Sync variables**: required for the sync **you** want, get them [here](/docs/resources/environment-variables#synchronization-)
+- **Docker variables**: required for the docker container, get them [here](/docs/resources/environment-variables#configuration-with-docker-)

docs/docs/configuration/index.mdx

@@ -0,0 +1,24 @@
+---
+sidebar_position: 1
+title: "Get Started"
+---
+
+import Platforms from "@site/src/components/platforms";
+
+
+# Get Started
+
+As of today, Touitomamout is a self-hosted only tool. It means you have to host it yourself to use it. But don't worry, it's not that hard!
+
+## Solutions
+There are multiple ways to run Touitomamout, all of these ways are detailed below. Features are the same for each of them.
+
+<Platforms/>
+
+:::info Environment variables
+
+In all cases you'll have to define a set of environment variables to properly shape the Touitomamout instance to your needs.
+
+You can find the [list of all environment variables here](/docs/resources/environment-variables).
+
+:::

docs/docs/configuration/manual-sync.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 5
+title: Configure with Manual sync
+tags: [
+  'configuration',
+  'manual sync',
+]
+---
+
+# 👏️️ Manual sync configuration
+
+## Define environment variables
+3 types of environment variables are required to run the sync:
+- **Core variables**: required in situations, get them [here](/docs/resources/environment-variables#core-variables)
+- **Sync variables**: required for the sync **you** want, get them [here](/docs/resources/environment-variables#synchronization-)
+- **Manual sync variables**: required for the manual sync, get them [here](/docs/resources/environment-variables#configuration-with-manual-sync-)

docs/docs/configuration/pm2.md

@@ -0,0 +1,16 @@
+---
+sidebar_position: 4
+title: Configure with PM2
+tags: [
+  'configuration',
+  'pm2',
+]
+---
+
+# ⏲️ PM2 configuration
+
+## Define environment variables
+3 types of environment variables are required to run the sync:
+- **Core variables**: required in situations, get them [here](/docs/resources/environment-variables#core-variables)
+- **Sync variables**: required for the sync **you** want, get them [here](/docs/resources/environment-variables#synchronization-)
+- **PM2 variables**: required for the PM2 instance, get them [here](/docs/resources/environment-variables#configuration-with-pm2-)

docs/docs/discover.md

@@ -0,0 +1,63 @@
+---
+title: Introduction
+sidebar_position: 1
+---
+
+# Discover Touitomamout 👀
+
+Let's discover Touitomamout in less than ⏲️ **5** minutes!
+
+First, what is Touitomamout? It is a self-hosted cross-poster from **Twitter** to **Mastodon** and / or **Bluesky**. It's a tool that allows you to sync tweets to Mastodon & Bluesky. But it also allows you to synchronize the profile picture, the name, the banner & profile description if you'd like to.
+
+![touitomamout](/img/touitomamout-small.svg)
+
+## Features
+
+Here are an overview of the Touitomamout features.
+
+| Sync eligible   | Text | Images | Videos | Gifs | Profile      |
+|-----------------|------|--------|--------|------|--------------|
+| **Mastodon 🦣** | ✅    | ✅      | ✅      | ✅    | ✅ (optional) |
+| **Bluesky ☁️**  | ✅    | ✅      | ⛔      | ⛔    | ✅ (optional) |
+
+:::note
+
+Gifs & Videos are not supported on Bluesky yet. But it will be soon 🤞! Until then, tweets containing gifs or videos will
+be synced without the medias. If no text and no compatible media are found, the post will be skipped during sync.
+:::
+
+## How synchronization is working?
+
+### Content synchronization
+Touitomamout syncs tweets from the selected account every X minutes (you have to choose this while creating your instance).
+If you have to understand a single thing about sync, it would be the following:
+
+:::tip Sync in a nutshell
+
+Touitomamout only syncs **the content from the synced account** and only when it's **platform-agnostic**.
+
+:::
+
+Meaning for a given synced account @ilovetouitomamout:
+- Sync will work for a thread of 5 tweets made by @ilovetouitomamout,
+- But sync will skip a reply from @ilovetouitomamout to a different Twitter user that itself.
+
+Here is a detailed view of what is synced or not.
+
+| Sync eligible                |  Text  |  Image |  Video | Text & Image | Text & Video |  Reply |  Quote |  Retweet | 
+|------------------------------|:------:|:------:|:------:|:------------:|:------------:|:------:|:------:|:--------:|
+| Tweet from synced account    |   ✅   |   ✅   |   ✅   |      ✅      |      ✅      |   ✅   |   ✅   |    ⛔    |
+| Tweet from different account |   ⛔   |   ⛔   |   ⛔   |      ⛔      |      ⛔      |   ⛔   |   ⛔   |    ⛔    |
+
+### Profile synchronization
+This process is totally optional and **can be disabled** from the `.env` configuration file. You're able to chose to synce the following items:
+1. 📸 Profile picture
+2. 📜 Biography
+3. 🌄 Banner
+4. 🔤 Profile name
+
+## What does Touitomamout rely on to work?
+
+The project relies on [Twitter Scraper](https://github.com/the-convocation/twitter-scraper) to access the data from Twitter. Since it's not an official way of connecting to Twitter, please take into account the data retrieval can sometimes be slow down or broken.
+Some filtering & configuration rules are taken into account to output the list of posts to sync.
+Finally, posts are provided to Mastodon & Bluesky by relying on the [atproto](https://github.com/bluesky-social/atproto) and [masto.js](https://github.com/neet/masto.js) libraries.

docs/docs/resources/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "Resources",
+  "position": 3,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index"
+  }
+}

docs/docs/resources/environment-variables.md

@@ -0,0 +1,68 @@
+---
+title: Environment variables
+---
+
+# Environment variables
+
+In order to configure the application, you have to provide environment variables. You'll find here the list of all the
+environment variables by type of usage. `(📌 means the variable is required for the context where it is defined)`
+
+## Core variables
+
+| Variable            | Default | Category          | Description                                    |
+|---------------------|:-------:|-------------------|------------------------------------------------|
+| `TWITTER_HANDLE` 📌 |    ∅    | **Twitter**::data | The twitter username you want to sync.         |
+| `TWITTER_USERNAME`  |    ∅    | **Twitter**::auth | The twitter username used to log into twitter. |
+| `TWITTER_PASSWORD`  |    ∅    | **Twitter**::auth | The twitter password used to log into twitter. |
+
+:::caution Twitter auth
+
+Even if `TWITTER_USERNAME` & `TWITTER_PASSWORD` are optional, these variables are **_highly_** recommended. Using a secondary account you don't care about is recommended.
+
+**Learn more about [Authentication against Twitter API](./twitter-authentication).**
+:::
+
+## To sync to Mastodon 🦣
+
+| Variable                   | Default | Category           | Description                                                   |
+|----------------------------|:-------:|--------------------|---------------------------------------------------------------|
+| 📌 `MASTODON_INSTANCE`     |    ∅    | **Mastodon**::auth | The mastodon instance the account is registered on.           |
+| 📌 `MASTODON_ACCESS_TOKEN` |    ∅    | **Mastodon**::auth | The mastodon access token to authenticated the sync requests. |
+
+## To sync to Bluesky ☁️
+
+| Variable                | Default | Category          | Description                                                                                                        |
+|-------------------------|:-------:|-------------------|--------------------------------------------------------------------------------------------------------------------|
+| 📌 `BLUESKY_INSTANCE`   |    ∅    | **Bluesky**::auth | The bluesky instance the account is registered on.<br/>_(eg: `bsky.social`)_                                       |
+| 📌 `BLUESKY_IDENTIFIER` |    ∅    | **Bluesky**::auth | The bluesky user identifier.<br/>_(eg: `handle.bsky.social`)_                                                      |
+| 📌 `BLUESKY_PASSWORD`   |    ∅    | **Bluesky**::auth | The bluesky password.<br/>_(Can be a user password or an [app password](https://bsky.app/settings/app-passwords))_ |
+
+## Synchronization 🐝
+
+Configure here how the sync will be done.
+
+| Variable                   | Default | Category           | Description                                 |
+|----------------------------|:-------:|--------------------|---------------------------------------------|
+| 📌 `SYNC_MASTODON`         |  false  | **Sync**::platform | Whether run the sync to Mastodon.           |
+| 📌 `SYNC_BLUESKY`          |  false  | **Sync**::platform | Whether run the sync to Bluesky.            |
+| `SYNC_PROFILE_NAME`        |  false  | **Sync**::profile  | Whether sync the profile name.              |
+| `SYNC_PROFILE_DESCRIPTION` |  false  | **Sync**::profile  | Whether sync the profile description.       |
+| `SYNC_PROFILE_PICTURE`     |  false  | **Sync**::profile  | Whether sync the profile picture.           |
+| `SYNC_PROFILE_HEADER`      |  false  | **Sync**::profile  | Whether sync the profile header (= banner). |
+
+## Configuration with Docker 🐳
+
+## Configuration with Cron ⏰
+
+## Configuration with PM2 ⏲️
+
+|     Variable     |  Default   | Category         | Description                                                                                           |
+|:----------------:|:----------:|------------------|-------------------------------------------------------------------------------------------------------|
+|  📌 `EXECUTION`  |     ∅      | **PM2**::runtime | The execution type you want to rely on (if you use the `deploy.sh` script). Value **has to be 'pm2'** |
+|  `INSTANCE_ID`   | 'instance' | **PM2**::runtime | The pm2 instance name suffix. Will generate `touitomamout-[INSTANCE_ID]`.                             |
+
+## Configuration with Manual execution 👏️
+
+|     Variable     | Default | Category            | Description                                                                                              |
+|:----------------:|:-------:|---------------------|----------------------------------------------------------------------------------------------------------|
+|  📌 `EXECUTION`  |    ∅    | **Manual**::runtime | The execution type you want to rely on (if you use the `deploy.sh` script). Value **has to be 'manual'** |

docs/docs/resources/storage/_category_.json

@@ -0,0 +1,7 @@
+{
+  "label": "Storage",
+  "collapsed": false,
+  "link": {
+    "type": "generated-index"
+  }
+}