From 9c9daff0270ea6eeab94d66fe58fec08078fc2c9 Mon Sep 17 00:00:00 2001
From: Manuel Raynaud <manu@raynaud.io>
Date: Wed, 1 Jul 2026 11:07:47 +0200
Subject: [PATCH] =?UTF-8?q?=F0=9F=93=9D(documentation)=20explain=20how=20c?=
 =?UTF-8?q?onversion=20format=20can=20be=20configured?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Create a dedicated documentation to explain how conversion format is
handled and how it can be configured. Docspec configuration is also
covered.
---
 documentation/README.md            |  1 +
 documentation/format_conversion.md | 73 ++++++++++++++++++++++++++++++
 2 files changed, 74 insertions(+)
 create mode 100644 documentation/format_conversion.md

diff --git a/documentation/README.md b/documentation/README.md
index d1e495c83..574c81736 100644
--- a/documentation/README.md
+++ b/documentation/README.md
@@ -21,6 +21,7 @@ Use the section below to quickly find what you are looking for.
   - [Environment variables](env.md)
   - [Object storage](s3.md)
   - [Collaboration](collaboration.md)
+  - [Format conversion](format_conversion.md)
   - [Customization](customization.md)
   - [Language configuration](languages-configuration.md)
   - [Search configuration](search.md)
diff --git a/documentation/format_conversion.md b/documentation/format_conversion.md
new file mode 100644
index 000000000..030e498e9
--- /dev/null
+++ b/documentation/format_conversion.md
@@ -0,0 +1,73 @@
+# Format conversion
+
+Docs allows manipulating a document in multiple formats. You can export in HTML, copy as markdown, import markdown files, etc.
+
+To make it work, some configuration should be made and another service enabled if you want to import files in docx format.
+
+## Conversion configuration
+
+The first configuration to make is related to converting a docs in multiple format. This will be used by the `formatted-content` endpoint (`/api/v1.0/documents/{document_id}/formatted-content/?content_format=(json|html|markdown)`).
+This service is also used by the `create-for-owner` endpoint and in the import of markdown file.
+To configure it, use this environment variables in the Django service:
+
+```yaml
+Y_PROVIDER_API_BASE_URL: http://{y-provider-service}:443/api/
+Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider
+```
+
+For the `Y_PROVIDER_API_BASE_URL`, it can be the FQDN of your docs instance if you have configured a reverse proxy in front of the y-provider service and created a route to the `/api` for this service. It can also be the internal `y-provider` service url if Django can access it directly. In the case you deploy in a Kubernetes cluster, you can use the `y-provider` service url. We prefer the usage of internal url.
+
+You also have to add an environment variable in your `y-provider` configuration, to share the same `Y_PROVIDER_API_KEY`:
+
+```yaml
+Y_PROVIDER_API_KEY: a-shared-private-key-with-y-provider
+```
+
+### Splitting conversion service
+
+The conversion service is present in the `y-provider` server. The same server used to manage websockets. You can split in one side the websocket server and in an other side the converter service.
+This feature is only available in our helm chart, if you are deploying an other way you can take example of what is made to implement it.
+The idea is to deploy twice the `y-provider` server, one dedicated for websockets and one dedicated to the conversion.
+
+In the helm chart, you can use this value that will do the job for you:
+
+```yaml
+yProvider:
+  converter:
+    enabled: true
+```
+
+Every parameter in the `yProvider` key can be overridden in the `yProvider.converter` key.
+
+Once enabled, you have to enable the `Y_PROVIDER_API_BASE_URL` with the url of the newly created service, it is the same as before with `-converter` at the end.
+If before it was
+
+```yaml
+Y_PROVIDER_API_BASE_URL: http://impress-docs-y-provider:443/api/
+```
+
+now it is
+
+```yaml
+Y_PROVIDER_API_BASE_URL: http://impress-docs-y-provider-converter:443/api/
+```
+
+## Docspec configuration
+
+[Docspec](https://github.com/docspec) is an external service made to transform legacy document formats into accessible, reusable content for modern editors. We are using it to import `.docx` file and convert them to be used with docs, enabling all the power of Docs without the caveats of this legacy format.
+
+You are responsible to deploy your own version of docspec, if you are using our helm chart, deploying docspec is really easy, you just have to enable it in your `values` configuration:
+
+```yaml
+docSpec:
+  enabled: true
+```
+
+If you deploy it your own way, be aware that this service exposes a public API, everybody knowing its url can use it. We highly suggest to deploy it in a private network, usable by docs.
+
+Once docspec is deployed, you have to enable its usage in Django by using these environment variables:
+
+```yaml
+CONVERSION_UPLOAD_ENABLED: True
+DOCSPEC_API_URL: http://impress-docs-docspec:4000/conversion
+```