suitenumerique · rebeling · Mar 29, 2025
diff --git a/README.md b/README.md
@@ -46,105 +46,22 @@ Docs is a collaborative text editor designed to address common challenges in kno
 
 ## Getting started 🔧
 
-### Test it
-
-Test Docs on your browser by logging in on this [environment](https://impress-preprod.beta.numerique.gouv.fr/)
-
-```
-email: [email protected]
-password: I'd<3ToTestDocs
-```
-
-### Run it locally
-
-> ⚠️ Running Docs locally using the methods described below is for testing purposes only.  It is based on building Docs using Minio as the S3 storage solution but you can choose any S3 compatible object storage of your choice.
-
-**Prerequisite**
-
-Make sure you have a recent version of Docker and [Docker Compose](https://docs.docker.com/compose/install) installed on your laptop:
-
-```shellscript
-$ docker -v
-
-Docker version 20.10.2, build 2291f61
-
-$ docker compose version
-
-Docker Compose version v2.32.4
-```
-
-> ⚠️ You may need to run the following commands with sudo but this can be avoided by adding your user to the `docker` group.
-
-**Project bootstrap**
-
-The easiest way to start working on the project is to use [GNU Make](https://www.gnu.org/software/make/):
-
-```shellscript
-$ make bootstrap FLUSH_ARGS='--no-input'
-```
-
-This command builds the `app` container, installs dependencies, performs database migrations and compile translations. It's a good idea to use this command each time you are pulling code from the project repository to avoid dependency-related or migration-related issues.
-
-Your Docker services should now be up and running 🎉
-
-You can access to the project by going to <http://localhost:3000>.
+For detailed guides on setup, development, and deployment, check out the documentation available on our [GitHub Pages site](https://suitenumerique.github.io/docs/).
 
-You will be prompted to log in, the default credentials are:
+Quick links:
 
-```
-username: impress
-password: impress
-```
+- 📚 [Documentation Overview](https://suitenumerique.github.io/docs/)
+- 🧑‍💻 [Development Guide](https://suitenumerique.github.io/docs/development)
+- 🚀 [Deployment Options](https://suitenumerique.github.io/docs/deployment)
 
-📝 Note that if you need to run them afterwards, you can use the eponym Make rule:
-
-```shellscript
-$ make run
-```
 
-⚠️ For the frontend developer, it is often better to run the frontend in development mode locally.
-
-To do so, install the frontend dependencies with the following command:
-
-```shellscript
-$ make frontend-development-install
-```
-
-And run the frontend locally in development mode with the following command:
-
-```shellscript
-$ make run-frontend-development
-```
-
-To start all the services, except the frontend container, you can use the following command:
-
-```shellscript
-$ make run-backend
-```
-
-**Adding content**
-You can create a basic demo site by running:
-
-```shellscript
-$ make demo
-```
+### Test it
 
-Finally, you can check all available Make rules using:
+Test Docs on your browser by logging in on this [environment](https://impress-preprod.beta.numerique.gouv.fr/)
 
-```shellscript
-$ make help
 ```
-
-**Django admin**
-
-You can access the Django admin site at
-
-<http://localhost:8071/admin>.
-
-You first need to create a superuser account:
-
-```shellscript
-$ make superuser
+email: [email protected]
+password: I'd<3ToTestDocs
 ```
 
 ## Feedback 🙋‍♂️🙋‍♀️

diff --git a/docs/api.md b/docs/api.md
@@ -0,0 +1,14 @@
+# 📡 API Reference
+
+## 🌐 API Overview
+
+Our API is fully documented using **Swagger UI**.
+
+👉 View the interactive docs here:
+[🔗 Swagger UI](http://localhost:8071/api/v1.0/swagger/)
+
+<!-- Latest url instead of `v1.0` would be cool -->
+
+## Authentication
+
+For cookieAuth (apiKey) use Y_PROVIDER_API_KEY.
diff --git a/docs/development.md b/docs/development.md
@@ -0,0 +1,97 @@
+# Development
+
+### Run it locally
+
+> ⚠️ Running Docs locally using the methods described below is for testing purposes only.  It is based on building Docs using Minio as the S3 storage solution but you can choose any S3 compatible object storage of your choice.
+
+**Prerequisite**
+
+Make sure you have a recent version of Docker and [Docker Compose](https://docs.docker.com/compose/install) installed on your laptop:
+
+```shellscript
+$ docker -v
+
+Docker version 20.10.2, build 2291f61
+
+$ docker compose version
+
+Docker Compose version v2.32.4
+```
+
+> ⚠️ You may need to run the following commands with sudo but this can be avoided by adding your user to the `docker` group.
+
+**Project bootstrap**
+
+The easiest way to start working on the project is to use [GNU Make](https://www.gnu.org/software/make/):
+
+```shellscript
+$ make bootstrap FLUSH_ARGS='--no-input'
+```
+
+This command builds the `app` container, installs dependencies, performs database migrations and compile translations. It's a good idea to use this command each time you are pulling code from the project repository to avoid dependency-related or migration-related issues.
+
+Your Docker services should now be up and running 🎉
+
+You can access to the project by going to <http://localhost:3000>.
+
+You will be prompted to log in, the default credentials are:
+
+```
+username: impress
+password: impress
+```
+
+📝 Note that if you need to run them afterwards, you can use the eponym Make rule:
+
+```shellscript
+$ make run
+```
+
+⚠️ For the frontend developer, it is often better to run the frontend in development mode locally.
+
+To do so, install the frontend dependencies with the following command:
+
+```shellscript
+$ make frontend-development-install
+```
+
+And run the frontend locally in development mode with the following command:
+
+```shellscript
+$ make run-frontend-development
+```
+
+To start all the services, except the frontend container, you can use the following command:
+
+```shellscript
+$ make run-backend
+```
+
+**Adding content**
+You can create a basic demo site by running:
+
+```shellscript
+$ make demo
+```
+
+Finally, you can check all available Make rules using:
+
+```shellscript
+$ make help
+```
+
+**Django admin**
+
+You can access the Django admin site at
+
+<http://localhost:8071/admin>.
+
+You first need to create a superuser account:
+
+```shellscript
+$ make superuser
+```
+
+### Development environment
+
+@todo: the linter, sdk project files, cursor prompt
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,38 @@
+# 📖 Welcome to the Docs Documentation
+
+Below is a table of contents to help you navigate the documentation
+files available in this folder.
+
+## 📚 Table of Contents
+
+### 🏁 Getting Started
+- 📖 [Introduction](./introduction.md)
+- 👨‍💻 [Development Setup](./development.md)
+- 🤝 [Contributing](https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md)
+
+### 📡 API
+- 🌐 [API Overview](./api.md)
+
+### 🚀 Deployment Options
+- ⚙️ [Installation Guide](./installation.md)
+  - 💻 [Standalone Installation](./installation-standalone.md)
+  - 🐳 [Docker Setup](./installation-docker.md)
+  - ☸️ [Kubernetes Deployment](./installation-k8s.md)
+  - 🛠️ [Advanced Configuration](./installation-advanced.md)
+
+### 🔖 Release & Maintenance
+- 🗒️ [Release Notes](./release.md)
+- 🧾 [Changelog](https://github.com/suitenumerique/docs/blob/main/CHANGELOG.md)
+- ⬆️ [Upgrade Guide](https://github.com/suitenumerique/docs/blob/main/UPGRADE.md)
+- 🔐 [Security Policy](https://github.com/suitenumerique/docs/blob/main/SECURITY.md)
+
+### 🌍 Community & Governance
+- 📜 [Code of Conduct](https://github.com/suitenumerique/docs/blob/main/CODE_OF_CONDUCT.md)
+<!-- - 🙋 [Questions & FAQ](./faq.md) -->
+<!-- - 🗺️ [Roadmap](./roadmap.md) -->
+<!-- - 🙌 [Credits](./credits.md) -->
+
+
+Looking for help? Reach out via [Matrix](https://matrix.to/#/#docs-official:matrix.org) or email us at [[email protected]](mailto:[email protected]).
+
+[Back to repo](https://github.com/suitenumerique/docs)