### Manage frontend development

Source: https://github.com/suitenumerique/docs/blob/main/README.md

Commands to install frontend dependencies and start the development server outside of the Docker container environment.

```bash
make frontend-development-install
make run-frontend-development
```

--------------------------------

### Get User Information Example

Source: https://github.com/suitenumerique/docs/blob/main/docs/resource_server.md

Example of how to retrieve the current user's information using the Docs API.

```APIDOC
## GET /external_api/v1.0/users/me/

### Description
Retrieves the current user's information.

### Method
GET

### Endpoint
`/external_api/v1.0/users/me/`

### Parameters
None

### Request Body
None

### Request Example
```python
import requests
from django.conf import settings

# Assume access_token is already obtained
access_token = "your_access_token"

response = requests.get(
    f"{settings.DOCS_API}/users/me/",
    headers={
        "Authorization": f"Bearer {access_token}",
        "Content-Type": "application/json"
    }
)

response.raise_for_status()
data = response.json()
print(f"User Info: {data}")
```

### Response
#### Success Response (200)
- **user_info** (object) - An object containing the user's details.

#### Response Example
```json
{
  "user_info": {
    "id": "user-id-789",
    "username": "currentuser",
    "email": "current@example.com"
  }
}
```
```

--------------------------------

### Changelog Update Example

Source: https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md

An example of how to format a changelog entry, including a gitmoji, type, description, and pull request ID.

```markdown
## [Unreleased]

## Added

- ✨(frontend) add AI to the project #321
```

--------------------------------

### Create Document Example

Source: https://github.com/suitenumerique/docs/blob/main/docs/resource_server.md

Example of how to create a new document from a Markdown file using the Docs API.

```APIDOC
## POST /external_api/v1.0/documents/

### Description
Creates a new document from a file.

### Method
POST

### Endpoint
`/external_api/v1.0/documents/`

### Parameters
#### Request Body
- **file** (file) - Required - The document file to upload (e.g., a Markdown file).

### Request Example
```python
import requests
from io import BytesIO
from django.conf import settings

# Assume access_token is already obtained
access_token = "your_access_token"

file_content = b"# Test Document\n\nThis is a test."
file = BytesIO(file_content)
file.name = "readme.md"

response = requests.post(
    f"{settings.DOCS_API}/documents/",
    files={
        "file": ("readme.md", file, "text/markdown")
    },
    headers={
        "Authorization": f"Bearer {access_token}"
    }
)

response.raise_for_status()
data = response.json()
print(f"Document created with ID: {data['id']}")
```

### Response
#### Success Response (200)
- **id** (string) - The ID of the newly created document.

#### Response Example
```json
{
  "id": "new-document-id-456"
}
```
```

--------------------------------

### Bootstrap and run development environment

Source: https://github.com/suitenumerique/docs/blob/main/README.md

Commands to initialize the project, build containers, run migrations, and start the development server.

```bash
make bootstrap FLUSH_ARGS='--no-input'
make run
```

--------------------------------

### Download Keycloak Installation Files (Bash)

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/keycloak/README.md

This snippet downloads the necessary Docker Compose file and environment configuration files for Keycloak installation using curl. It prepares the working directory and fetches remote files.

```bash
mkdir keycloak
curl -o keycloak/compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/keycloak/compose.yaml
curl -o keycloak/env.d/kc_postgresql https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/kc_postgresql
curl -o keycloak/env.d/keycloak https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/keycloak
```

--------------------------------

### Nginx Proxy Configuration Example for Docker Compose

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/compose.md

An example snippet from a Docker Compose file demonstrating how to configure the frontend service to work with an Nginx reverse proxy. It includes environment variables for virtual host, port, and Let's Encrypt integration, along with network configuration.

```yaml
frontend:
    ...
    # Uncomment and set your values if using our nginx proxy example
    #environment:
    # - VIRTUAL_HOST=${DOCS_HOST} # used by nginx proxy 
    # - VIRTUAL_PORT=8083 # used by nginx proxy
    # - LETSENCRYPT_HOST=${DOCS_HOST} # used by lets encrypt to generate TLS certificate
    ...
# Uncomment if using our nginx proxy example
#    networks:
#    - proxy-tier
#
#networks:
#  proxy-tier:
#    external: true
```

--------------------------------

### Start Nginx Proxy Service (Bash)

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/nginx-proxy/README.md

This command starts the Nginx proxy and acme-companion services in detached mode using Docker Compose. It requires Docker Compose to be installed and a valid compose.yaml file.

```bash
docker compose up -d
```

--------------------------------

### Commit Message Format Example

Source: https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md

An example demonstrating the required commit message format, including gitmoji, type, title, and description.

```git
✨(frontend) add user authentication logic 

Implemented login and signup features, and integrated OAuth2 for social login.
```

--------------------------------

### Verify Docker installation

Source: https://github.com/suitenumerique/docs/blob/main/README.md

Checks the installed versions of Docker and Docker Compose to ensure prerequisites are met for local development.

```bash
docker -v
docker compose version
```

--------------------------------

### Retrieve User Information via API

Source: https://github.com/suitenumerique/docs/blob/main/docs/resource_server.md

Example of an authenticated GET request to the /users/me/ endpoint to fetch current user details.

```python
response = requests.get(
    "{settings.DOCS_API}/users/me/",
    headers={"Authorization": f"Bearer {access_token}", "Content-Type": "application/json"},
)
```

--------------------------------

### Manage Docs Deployment via CLI

Source: https://context7.com/suitenumerique/docs/llms.txt

Common shell commands for managing the Docs lifecycle, including starting services, running database migrations, creating administrative users, and monitoring logs.

```bash
docker compose up -d
docker compose run --rm backend python manage.py migrate
docker compose run --rm backend python manage.py createsuperuser --email admin@example.com --password securepassword
docker compose logs -f backend
```

--------------------------------

### Start Keycloak Service (Bash)

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/keycloak/README.md

This command initiates the Keycloak Docker service in detached mode. It assumes that the Docker Compose file and necessary environment variables are already configured.

```bash
`docker compose up -d`
```

--------------------------------

### JavaScript Code Block Example

Source: https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/e2e/__tests__/app-impress/assets/base-content-test-pdf.txt

A demonstration of a JavaScript code block within the documentation. This snippet showcases syntax highlighting and structure.

```javascript
const text = "Hello World";
console.log(text);
```

--------------------------------

### Deploy Minio for S3 Bucket Storage

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/kubernetes.md

Deploys a Minio instance using Helm to provide S3-compatible object storage for documents. This setup is for testing and requires configuration of the Helm chart. It enables the project to store and retrieve documents from an S3-like interface.

```bash
$ helm install --repo https://suitenumerique.github.io/helm-dev-backend -f docs/examples/helm/minio.values.yaml minio dev-backend
$ kubectl get pods
NAME                                       READY   STATUS    RESTARTS   AGE
keycloak-dev-backend-keycloak-0            1/1     Running   0          6m12s
keycloak-dev-backend-keycloak-pg-0         1/1     Running   0          6m12s
minio-dev-backend-minio-0                  1/1     Running   0          10s
postgresql-dev-backend-postgres-0          1/1     Running   0          2m43s
redis-dev-backend-redis-68c9f66786-4dgxj   1/1     Running   0          4m21s
```

--------------------------------

### Deploy PostgreSQL Database

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/kubernetes.md

Deploys a PostgreSQL instance using Helm to serve as the primary database for the Docs project. This setup provides the necessary connection details, including host, database name, user, and password, which are often retrieved from Kubernetes secrets.

```bash
$ helm install --repo https://suitenumerique.github.io/helm-dev-backend -f docs/examples/helm/postgresql.values.yaml postgresql dev-backend
$ kubectl get pods
NAME                                       READY   STATUS    RESTARTS   AGE
keycloak-dev-backend-keycloak-0            1/1     Running   0          3m42s
keycloak-dev-backend-keycloak-pg-0         1/1     Running   0          3m42s
postgresql-dev-backend-postgres-0          1/1     Running   0          13s
redis-dev-backend-redis-68c9f66786-4dgxj   1/1     Running   0          111s
```

```yaml
DB_HOST: postgresql-dev-backend-postgres
DB_NAME:
    secretKeyRef:
        name: postgresql-dev-backend-postgres
        key: database
DB_USER:
    secretKeyRef:
        name: postgresql-dev-backend-postgres
        key: username
DB_PASSWORD:
    secretKeyRef:
        name: postgresql-dev-backend-postgres
        key: password
DB_PORT: 5432
```

--------------------------------

### Download Nginx-Proxy Configuration Template

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/compose.md

This command downloads a template configuration file for nginx-proxy, which is used in conjunction with Docker Compose for routing traffic to the Docs application. This is optional and depends on whether you are using the sample nginx-proxy setup.

```bash
curl -o default.conf.template https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docker/files/production/etc/nginx/conf.d/default.conf.template
```

--------------------------------

### JavaScript Hello World Function

Source: https://github.com/suitenumerique/docs/blob/main/src/frontend/apps/e2e/__tests__/app-impress/assets/test_import.md

A simple JavaScript function that logs 'Hello, world!' to the console. This is a basic example demonstrating function declaration and console output.

```javascript
const hello_world = () => {
    console.log("Hello, world!");
}
```

--------------------------------

### Deploy Keycloak for OIDC Authentication

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/kubernetes.md

Deploys a Keycloak instance using Helm for OpenID Connect (OIDC) authentication. This setup is for demonstration purposes and requires specific values from the provided YAML file. It outputs OIDC endpoint configurations needed for client applications.

```bash
$ helm install --repo https://suitenumerique.github.io/helm-dev-backend -f docs/examples/helm/keycloak.values.yaml keycloak dev-backend
$ #wait until
$ kubectl get pods
NAME                                 READY   STATUS    RESTARTS   AGE
keycloak-dev-backend-keycloak-0      1/1     Running   0          20s
keycloak-dev-backend-keycloak-pg-0   1/1     Running   0          20s
```

```yaml
OIDC_OP_JWKS_ENDPOINT: https://docs-keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/certs
OIDC_OP_AUTHORIZATION_ENDPOINT: https://docs-keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/auth
OIDC_OP_TOKEN_ENDPOINT: https://docs-keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/token
OIDC_OP_USER_ENDPOINT: https://docs-keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/userinfo
OIDC_OP_LOGOUT_ENDPOINT: https://docs-keycloak.127.0.0.1.nip.io/realms/impress/protocol/openid-connect/logout
OIDC_RP_CLIENT_ID: impress
OIDC_RP_CLIENT_SECRET: ThisIsAnExampleKeyForDevPurposeOnly
OIDC_RP_SIGN_ALGO: RS256
OIDC_RP_SCOPES: "openid email"
```

--------------------------------

### Create Document via API

Source: https://github.com/suitenumerique/docs/blob/main/docs/resource_server.md

Example of a Django view method that uses an OIDC access token to upload a markdown file and create a new document in Docs.

```python
@method_decorator(refresh_oidc_access_token)
def create_document_from_markdown(self, request):
    access_token = request.session.get('oidc_access_token')
    file_content = b"# Test Document\n\nThis is a test."
    file = BytesIO(file_content)
    file.name = "readme.md"
    response = requests.post(
        f"{settings.DOCS_API}/documents/",
        {"file": file},
        format="multipart",
    )
    response.raise_for_status()
    data = response.json()
    return {"id": data["id"]}
```

--------------------------------

### Configure Celery Container Arguments

Source: https://github.com/suitenumerique/docs/blob/main/src/helm/impress/README.md

Defines the command-line arguments used to start the Celery worker process. This allows overriding the default entrypoint behavior for the container.

```yaml
backend.celery.args: ["celery", "-A", "impress.celery_app", "worker", "-l", "INFO", "-n", "impress@%h"]
```

--------------------------------

### Keycloak Docker Compose Configuration (YAML)

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/keycloak/README.md

This YAML snippet illustrates the configuration for a Keycloak service within a Docker Compose setup. It includes commented-out sections for environment variables and networks, typically used when integrating with a reverse proxy like Nginx for SSL termination.

```yaml
version: '3' 
services:
  keycloak:
   ...
    # Uncomment and set your values if using our nginx proxy example
    # environment:
    # - VIRTUAL_HOST=id.yourdomain.tld # used by nginx proxy 
    # - VIRTUAL_PORT=8080 # used by nginx proxy
    # - LETSENCRYPT_HOST=id.yourdomain.tld # used by lets encrypt to generate TLS certificate
   ...
# Uncomment if using our nginx proxy example
#    networks:
#    - proxy-tier
#    - default

# Uncomment if using our nginx proxy example
#networks:
#  proxy-tier:
#    external: true
```

--------------------------------

### Create Docker Network (Bash)

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/nginx-proxy/README.md

This command creates a Docker network named 'proxy-tier' which is necessary for containers to share for auto-discovery with Nginx proxy. It requires Docker to be installed.

```bash
docker network create proxy-tier
```

--------------------------------

### Get Document Tree (Navigation)

Source: https://context7.com/suitenumerique/docs/llms.txt

Retrieves the hierarchical structure of documents, including ancestors and siblings, useful for navigation. Requires an authentication token.

```bash
curl -X GET "https://docs.example.com/api/v1.0/documents/child-doc-uuid-1/tree/" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Manage Document Invitations (API)

Source: https://context7.com/suitenumerique/docs/llms.txt

Handles invitations for users to access documents. Allows listing pending invitations, creating new invitations with specified roles, updating invitation roles, and deleting invitations. Uses GET, POST, PATCH, and DELETE methods with JSON payloads.

```bash
curl -X GET "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/invitations/" \
  -H "Authorization: Bearer <token>"
```

```bash
curl -X POST "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/invitations/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "newuser@example.com",
    "role": "editor"
  }'
```

```bash
curl -X PATCH "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/invitations/invitation-uuid/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "reader"
  }'
```

```bash
curl -X DELETE "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/invitations/invitation-uuid/" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Manage Document Accesses (API)

Source: https://context7.com/suitenumerique/docs/llms.txt

Provides endpoints for managing user and team access to documents. Supports listing, granting, updating, and removing access with roles like owner, administrator, editor, and reader. Operations include GET, POST, PUT, and DELETE requests with JSON payloads for modifications.

```bash
curl -X GET "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/accesses/" \
  -H "Authorization: Bearer <token>"
```

```bash
curl -X POST "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/accesses/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "target-user-uuid",
    "role": "editor"
  }'
```

```bash
curl -X POST "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/accesses/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "engineering-team",
    "role": "reader"
  }'
```

```bash
curl -X PUT "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/accesses/access-uuid-1/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "administrator"
  }'
```

```bash
curl -X DELETE "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/accesses/access-uuid-1/" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Configure Docs Environment Variables

Source: https://context7.com/suitenumerique/docs/llms.txt

A template for the backend environment configuration file, covering database connections, S3 storage, OIDC authentication, collaboration settings, and AI integration.

```bash
DJANGO_SECRET_KEY=<generate-secure-key>
DJANGO_ALLOWED_HOSTS=docs.example.com
DB_HOST=postgresql
DB_NAME=docs
DB_USER=docs
DB_PASSWORD=<secure-password>
AWS_S3_ENDPOINT_URL=https://s3.example.com
AWS_S3_ACCESS_KEY_ID=<access-key>
AWS_S3_SECRET_ACCESS_KEY=<secret-key>
AWS_STORAGE_BUCKET_NAME=docs-media
OIDC_OP_AUTHORIZATION_ENDPOINT=https://id.example.com/auth
OIDC_OP_TOKEN_ENDPOINT=https://id.example.com/token
OIDC_OP_USER_ENDPOINT=https://id.example.com/userinfo
OIDC_OP_JWKS_ENDPOINT=https://id.example.com/jwks
OIDC_RP_CLIENT_ID=docs
OIDC_RP_CLIENT_SECRET=<client-secret>
COLLABORATION_WS_URL=wss://docs.example.com/collaboration/
COLLABORATION_SERVER_SECRET=<collaboration-secret>
Y_PROVIDER_API_BASE_URL=http://y-provider:4444
Y_PROVIDER_API_KEY=<provider-key>
AI_FEATURE_ENABLED=true
AI_FEATURE_BLOCKNOTE_ENABLED=true
AI_BASE_URL=https://api.openai.com/v1
AI_API_KEY=<openai-key>
AI_MODEL=gpt-4
DJANGO_EMAIL_HOST=smtp.example.com
DJANGO_EMAIL_FROM=noreply@example.com
DJANGO_EMAIL_HOST_USER=<smtp-user>
DJANGO_EMAIL_HOST_PASSWORD=<smtp-password>
```

--------------------------------

### Build impress-frontend Application with Yarn

Source: https://github.com/suitenumerique/docs/blob/main/docs/env.md

Instructions to build the impress-frontend application using yarn, setting the NODE_ENV and NEXT_PUBLIC_PUBLISH_AS_MIT environment variables.

```bash
cd src/frontend/apps/impress
NODE_ENV=production NEXT_PUBLIC_PUBLISH_AS_MIT=false yarn build
```

--------------------------------

### Download Docker Compose Configuration Files

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/compose.md

This snippet downloads the necessary configuration files for setting up Docs with Docker Compose. It includes the main compose file, common environment variables, and specific configurations for backend, yprovider, and postgresql.

```bash
mkdir -p docs/env.d
cd docs
curl -o compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/compose.yaml
curl -o env.d/common https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/common
curl -o env.d/backend https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/backend
curl -o env.d/yprovider https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/yprovider
curl -o env.d/postgresql https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/env.d/production.dist/postgresql
```

--------------------------------

### GET /api/v1.0/documents/trashbin/

Source: https://context7.com/suitenumerique/docs/llms.txt

Lists all soft-deleted documents currently in the trashbin.

```APIDOC
## GET /api/v1.0/documents/trashbin/

### Description
Lists soft-deleted documents in the trashbin.

### Method
GET

### Endpoint
https://docs.example.com/api/v1.0/documents/trashbin/

### Response
#### Success Response (200)
- **count** (integer) - Number of trashed items
- **results** (array) - List of trashed documents

#### Response Example
{
  "count": 2,
  "results": [
    {
      "id": "deleted-doc-uuid",
      "title": "Archived Document",
      "deleted_at": "2024-01-18T10:00:00Z"
    }
  ]
}
```

--------------------------------

### GET /api/v1.0/users/me/

Source: https://context7.com/suitenumerique/docs/llms.txt

Retrieves the profile information for the currently authenticated user.

```APIDOC
## GET /api/v1.0/users/me/

### Description
Fetches the details of the currently authenticated user.

### Method
GET

### Endpoint
https://docs.example.com/api/v1.0/users/me/

### Response
#### Success Response (200)
- **id** (string) - User UUID
- **email** (string) - User email address
- **full_name** (string) - User full name

### Response Example
{
  "id": "user-uuid",
  "email": "user@example.com",
  "full_name": "John Doe"
}
```

--------------------------------

### Build Docker Image for impress-frontend

Source: https://github.com/suitenumerique/docs/blob/main/docs/env.md

Command to build the Docker image for the impress-frontend, specifying the Dockerfile, build target, and a build argument for PUBLISH_AS_MIT.

```bash
docker build -f src/frontend/Dockerfile --target frontend-production --build-arg PUBLISH_AS_MIT=false docs-frontend:latest
```

--------------------------------

### POST /api/v1.0/documents/

Source: https://context7.com/suitenumerique/docs/llms.txt

Create a new document or upload a file to initialize a document.

```APIDOC
## POST /api/v1.0/documents/

### Description
Create a new document by providing a title and content, or by uploading a file (markdown or docx).

### Method
POST

### Endpoint
/api/v1.0/documents/

### Parameters
#### Request Body
- **title** (string) - Required - The title of the document
- **content** (string) - Optional - Base64 encoded Yjs content
- **file** (file) - Optional - Multipart file upload

### Response
#### Success Response (201)
- **id** (string) - The unique identifier of the created document
```

--------------------------------

### GET /documents/search/

Source: https://context7.com/suitenumerique/docs/llms.txt

Search for documents using keywords and optional path filtering.

```APIDOC
## GET /documents/search/

### Description
Performs a full-text search across documents or within a specific hierarchy.

### Method
GET

### Endpoint
https://docs.example.com/api/v1.0/documents/search/

### Parameters
#### Query Parameters
- **q** (string) - Required - The search query string.
- **path** (string) - Optional - The document path to restrict search scope.

### Response
#### Success Response (200)
- **results** (array) - List of matching documents with id, title, and excerpt.
```

--------------------------------

### Create Minio Bucket with Versioning

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/minio/README.md

Creates a new bucket on the Minio server using the `mc` client and enables versioning for it. This is essential for data protection and recovery within the Minio storage.

```shellscript
mc mb --with-versioning minio/<your-bucket-name>
```

--------------------------------

### GET /documents/{id}/accesses

Source: https://context7.com/suitenumerique/docs/llms.txt

Retrieves the list of users and teams with access to a specific document.

```APIDOC
## GET /documents/{id}/accesses

### Description
Lists all user and team access permissions for a document.

### Method
GET

### Endpoint
https://docs.example.com/api/v1.0/documents/{id}/accesses/

### Parameters
#### Path Parameters
- **id** (string) - Required - The unique identifier of the document.

### Response
#### Success Response (200)
- **accesses** (array) - List of access objects containing user, team, and role information.

#### Response Example
[
  {
    "id": "access-uuid-1",
    "role": "owner",
    "user": {"id": "user-uuid", "email": "user@example.com"}
  }
]
```

--------------------------------

### GET /api/v1.0/documents/

Source: https://context7.com/suitenumerique/docs/llms.txt

Retrieve a list of documents accessible to the authenticated user, with support for filtering and ordering.

```APIDOC
## GET /api/v1.0/documents/

### Description
List all documents accessible to the authenticated user. Supports filtering by title, favorite status, and ordering.

### Method
GET

### Endpoint
/api/v1.0/documents/

### Parameters
#### Query Parameters
- **title** (string) - Optional - Filter documents by title
- **is_favorite** (boolean) - Optional - Filter by favorite status
- **ordering** (string) - Optional - Field to order results by (e.g., -updated_at)

### Response
#### Success Response (200)
- **count** (integer) - Total number of documents
- **results** (array) - List of document objects

#### Response Example
{
  "count": 1,
  "results": [
    {
      "id": "9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4",
      "title": "Project Documentation",
      "is_favorite": true
    }
  ]
}
```

--------------------------------

### Run quality assurance and administration tasks

Source: https://github.com/suitenumerique/docs/blob/main/README.md

Commands for executing frontend tests, linting, and managing administrative tasks like creating a superuser.

```bash
make frontend-test
make frontend-lint
make superuser
```

--------------------------------

### Configure mc Alias for Minio Server

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/minio/README.md

Sets up an alias for the Minio server using the `mc` command-line client. This requires the Minio server URL, root user, and root password, allowing `mc` to connect and manage the Minio instance.

```shellscript
mc alias set minio <MINIO_SERVER_URL> <MINIO_ROOT_USER> <MINIO_ROOT_PASSWORD>
```

--------------------------------

### GET /api/v1.0/documents/{uuid}/content/

Source: https://context7.com/suitenumerique/docs/llms.txt

Exports document content in specified formats like JSON, Markdown, or HTML.

```APIDOC
## GET /api/v1.0/documents/{uuid}/content/

### Description
Retrieve document content in different formats.

### Method
GET

### Endpoint
https://docs.example.com/api/v1.0/documents/{uuid}/content/

### Parameters
#### Query Parameters
- **content_format** (string) - Required - Format to export: "json", "markdown", or "html".

### Response Example
{
  "id": "9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4",
  "title": "Project Documentation",
  "content": "# Project Documentation\n\nWelcome to our project...",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-20T14:22:00Z"
}
```

--------------------------------

### Download Minio Docker Compose File

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/minio/README.md

Downloads the Minio `compose.yaml` file from a remote URL to set up a local Minio instance. This is the initial step for deploying Minio using Docker Compose.

```bash
mkdir minio
curl -o minio/compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/minio/compose.yaml
```

--------------------------------

### GET /api/v1.0/documents/{uuid}/tree/

Source: https://context7.com/suitenumerique/docs/llms.txt

Retrieves the document tree structure, including ancestors and siblings, for navigation purposes.

```APIDOC
## GET /api/v1.0/documents/{uuid}/tree/

### Description
Retrieves the document tree structure, including ancestors and siblings, for navigation purposes.

### Method
GET

### Endpoint
https://docs.example.com/api/v1.0/documents/{uuid}/tree/

### Parameters
#### Path Parameters
- **uuid** (string) - Required - The unique identifier of the document.

### Request Example
curl -X GET "https://docs.example.com/api/v1.0/documents/child-doc-uuid-1/tree/" -H "Authorization: Bearer <token>"

### Response
#### Success Response (200)
- **id** (string) - Document ID
- **title** (string) - Document title
- **children** (array) - List of child documents

#### Response Example
{
  "id": "9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4",
  "title": "Project Documentation",
  "children": [
    {
      "id": "child-doc-uuid-1",
      "title": "Chapter 1",
      "children": []
    }
  ]
}
```

--------------------------------

### GET /api/v1.0/documents/{id}/children/

Source: https://context7.com/suitenumerique/docs/llms.txt

List child documents for a specific parent document to navigate the tree structure.

```APIDOC
## GET /api/v1.0/documents/{id}/children/

### Description
Retrieve all direct children of a specific document to support hierarchical navigation.

### Method
GET

### Endpoint
/api/v1.0/documents/{id}/children/

### Parameters
#### Path Parameters
- **id** (string) - Required - The UUID of the parent document

### Response
#### Success Response (200)
- **results** (array) - List of child document objects

#### Response Example
{
  "count": 2,
  "results": [
    {
      "id": "child-doc-uuid-1",
      "title": "Chapter 1"
    }
  ]
}
```

--------------------------------

### Prepare Nginx Proxy Environment (Bash)

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/nginx-proxy/README.md

This snippet prepares the working environment for Nginx proxy by creating a directory and downloading the compose file. It requires `curl` and `bash`.

```bash
mkdir nginx-proxy
curl -o nginx-proxy/compose.yaml https://raw.githubusercontent.com/suitenumerique/docs/refs/heads/main/docs/examples/compose/nginx-proxy/compose.yaml
```

--------------------------------

### Retrieve system configuration

Source: https://context7.com/suitenumerique/docs/llms.txt

Fetches public configuration settings for the frontend, including AI feature flags, allowed file extensions, and theme customization data.

```bash
curl -X GET "https://docs.example.com/api/v1.0/config/"
```

--------------------------------

### Get Favorite Documents List

Source: https://context7.com/suitenumerique/docs/llms.txt

Retrieves a list of all documents that the current user has marked as favorites for quick access. Requires authentication.

```bash
curl -X GET "https://docs.example.com/api/v1.0/documents/favorite_list/" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Create document from external application

Source: https://context7.com/suitenumerique/docs/llms.txt

Demonstrates how an external application can act as an OAuth2 client to upload and create a document from a file.

```python
from io import BytesIO
import requests

def create_document_from_markdown(access_token, docs_api_url):
    file_content = b"# Test Document\n\nThis is a test."
    file = BytesIO(file_content)
    file.name = "readme.md"

    response = requests.post(
        f"{docs_api_url}/external_api/v1.0/documents/",
        files={"file": file},
        headers={"Authorization": f"Bearer {access_token}"}
    )
    response.raise_for_status()
    return response.json()
```

--------------------------------

### Get Specific Document Version Content

Source: https://context7.com/suitenumerique/docs/llms.txt

Retrieves the content of a specific version of a document. Requires the document ID and the version ID. Authentication is required.

```bash
curl -X GET "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/versions/v1.abc123/" \
  -H "Authorization: Bearer <token>"
```

--------------------------------

### Manage user profile and search

Source: https://context7.com/suitenumerique/docs/llms.txt

Endpoints to retrieve current user details, search for other users for collaboration, update language preferences, and mark onboarding as complete.

```bash
curl -X GET "https://docs.example.com/api/v1.0/users/me/" -H "Authorization: Bearer <token>"

curl -X GET "https://docs.example.com/api/v1.0/users/?q=john&document_id=9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4" -H "Authorization: Bearer <token>"

curl -X POST "https://docs.example.com/api/v1.0/users/onboarding-done/" -H "Authorization: Bearer <token>"

curl -X PUT "https://docs.example.com/api/v1.0/users/user-uuid/" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"language": "fr"}'
```

--------------------------------

### Run Database Migrations and Create Admin User

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/compose.md

Commands to execute Django database migrations and create a superuser for the admin interface. These are essential steps after initial deployment or upgrades.

```bash
docker compose run --rm backend python manage.py migrate
docker compose run --rm backend python manage.py createsuperuser --email <admin email> --password <admin password>
```

--------------------------------

### Configure Minio Environment Variables

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/minio/README.md

Sets the root user and password for the Minio instance within the `compose.yaml` file. These credentials are required for initial access and configuration of the Minio server.

```yaml
version: '3'
services:
  minio:
   ...
    environment:
    - MINIO_ROOT_USER=<Set minio root username>
    - MINIO_ROOT_PASSWORD=<Set minio root password>
```

--------------------------------

### Manage Document Hierarchies

Source: https://context7.com/suitenumerique/docs/llms.txt

Shows how to navigate and extend the document tree structure by listing children of a specific document or creating new nested subpages.

```bash
# List children of a document
curl -X GET "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/children/" -H "Authorization: Bearer <token>"

# Create a child document
curl -X POST "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/children/" -H "Authorization: Bearer <token>" -H "Content-Type: application/json" -d '{"title": "New Chapter"}'
```

--------------------------------

### Configure Frontend Theme Environment Variables

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/compose.md

Sets environment variables for customizing the frontend theme and CSS. `FRONTEND_THEME` specifies the theme name built with Cunningham, and `FRONTEND_CSS_URL` points to a custom CSS file for further styling.

```env
FRONTEND_THEME=default
FRONTEND_CSS_URL=https://storage.yourdomain.tld/themes/custom.css
```

--------------------------------

### POST /api/v1.0/documents/create-for-owner/

Source: https://context7.com/suitenumerique/docs/llms.txt

Creates a document on behalf of a user using server-to-server authentication.

```APIDOC
## POST /api/v1.0/documents/create-for-owner/

### Description
Allows external services to create documents for specific users via S2S tokens.

### Method
POST

### Endpoint
https://docs.example.com/api/v1.0/documents/create-for-owner/

### Parameters
#### Request Body
- **title** (string) - Required - Document title
- **content** (string) - Required - Markdown content
- **sub** (string) - Required - User OIDC subject
- **email** (string) - Required - User email

### Response
#### Success Response (200)
- **id** (string) - The UUID of the created document.

### Response Example
{
  "id": "new-doc-uuid"
}
```

--------------------------------

### Enable WATCHPACK_POLLING for Frontend File Watching on Windows

Source: https://github.com/suitenumerique/docs/blob/main/docs/troubleshoot.md

This YAML configuration snippet shows how to enable polling for the frontend development service in a Docker Compose setup. Setting `WATCHPACK_POLLING=true` resolves issues with file change detection on Windows by forcing the file watcher to periodically check for changes instead of relying on filesystem events.

```yaml
frontend-development:
  user: "${DOCKER_USER:-1000}"
  build: 
    context: .
    dockerfile: ./src/frontend/Dockerfile
    target: impress-dev
    args:
      API_ORIGIN: "http://localhost:8071"
      PUBLISH_AS_MIT: "false"
      SW_DEACTIVATED: "true"
  image: impress:frontend-development
  environment:
    - WATCHPACK_POLLING=true  # Add this line for Windows users
  volumes:
    - ./src/frontend:/home/frontend
    - /home/frontend/node_modules
    - /home/frontend/apps/impress/node_modules
  ports:
    - "3000:3000"
```

--------------------------------

### Linting and Testing Commands

Source: https://github.com/suitenumerique/docs/blob/main/CONTRIBUTING.md

Commands to check code linting and run tests to ensure code quality and functionality before pushing changes.

```bash
make lint && make frontend-lint
```

```bash
make test
```

--------------------------------

### Define Theme Customization File Path

Source: https://github.com/suitenumerique/docs/blob/main/docs/customization.md

Sets the path for the theme configuration file used to manage icons, footers, translations, and the Waffle widget.

```shellscript
THEME_CUSTOMIZATION_FILE_PATH=<path>
```

--------------------------------

### Configure Logging Levels

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/compose.md

This snippet shows how to set environment variables to configure the logging levels for the Docs backend. It allows customization of console output and root/application logger verbosity.

```env
LOGGING_LEVEL_HANDLERS_CONSOLE=DEBUG
LOGGING_LEVEL_LOGGERS_ROOT=DEBUG
LOGGING_LEVEL_LOGGERS_APP=DEBUG
```

--------------------------------

### Configure Runtime CSS Theming

Source: https://github.com/suitenumerique/docs/blob/main/docs/customization.md

Sets the FRONTEND_CSS_URL environment variable to load a custom stylesheet at runtime. This allows for dynamic visual changes without recompilation.

```javascript
FRONTEND_CSS_URL=http://anything/custom-style.css
```

```css
body {
  background-color: #3498db;
}
```

--------------------------------

### Create Docker Network for Minio

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/minio/README.md

Creates a Docker network named `storage-tier` to facilitate communication between services that need to access the Minio instance. This is particularly useful for internal network access.

```bash
docker network create storage-tier
```

--------------------------------

### Deploy Docs Services with Docker Compose

Source: https://context7.com/suitenumerique/docs/llms.txt

Defines the multi-container architecture for Docs including backend, frontend, y-provider, Celery, PostgreSQL, and Redis. This configuration manages service dependencies and environment variable injection.

```yaml
services:
  backend:
    image: lasuite/docs-backend:latest
    env_file:
      - ./env.d/common
      - ./env.d/backend
    depends_on:
      - postgresql
      - redis
  frontend:
    image: lasuite/docs-frontend:latest
    ports:
      - "8083:8083"
  y-provider:
    image: lasuite/docs-y-provider:latest
    env_file:
      - ./env.d/yprovider
    depends_on:
      - backend
  celery:
    image: lasuite/docs-backend:latest
    command: celery -A impress.celery worker -l INFO
    env_file:
      - ./env.d/common
      - ./env.d/backend
  postgresql:
    image: postgres:16
    env_file:
      - ./env.d/postgresql
  redis:
    image: redis:7
```

--------------------------------

### Keycloak Environment Variables Configuration (Env)

Source: https://github.com/suitenumerique/docs/blob/main/docs/examples/compose/keycloak/README.md

This snippet shows the essential environment variables that need to be configured for Keycloak. It includes placeholders for database passwords, Keycloak hostname, and admin credentials.

```env
POSTGRES_PASSWORD=<generate postgres password>
KC_HOSTNAME=https://id.yourdomain.tld # Change with your own URL
KC_BOOTSTRAP_ADMIN_PASSWORD=<generate your password>
```

--------------------------------

### Configure Mail Service Environment Variables

Source: https://github.com/suitenumerique/docs/blob/main/docs/installation/compose.md

Sets up essential environment variables for the mail service in the backend. These variables define SMTP host, credentials, port, sender email, and branding for email templates. Ensure these are correctly configured in `env.d/backend`.

```env
DJANGO_EMAIL_HOST=<smtp host>
DJANGO_EMAIL_HOST_USER=<smtp user>
DJANGO_EMAIL_HOST_PASSWORD=<smtp password>
DJANGO_EMAIL_PORT=<smtp port>
DJANGO_EMAIL_FROM=<your email address>
#DJANGO_EMAIL_USE_TLS=true
#DJANGO_EMAIL_USE_SSL=true
DJANGO_EMAIL_BRAND_NAME=<brand name used in email templates>
DJANGO_EMAIL_LOGO_IMG=<logo image to use in email templates.>
DJANGO_EMAIL_URL_APP=<url used in email templates to go to the app>
```

--------------------------------

### Create document via Server-to-Server

Source: https://context7.com/suitenumerique/docs/llms.txt

Allows external services to programmatically create documents on behalf of users using S2S authentication tokens.

```bash
curl -X POST "https://docs.example.com/api/v1.0/documents/create-for-owner/" \
  -H "Authorization: Bearer <s2s-token>" \
  -H "Content-Type: application/json" \
  -d '{"title": "Document Created via S2S", "content": "# Welcome\n\nThis document was created programmatically.", "sub": "user-oidc-subject", "email": "user@example.com", "language": "en", "subject": "New document created", "message": "A document has been created for you."}'
```

--------------------------------

### Manage Document Access Requests (API)

Source: https://context7.com/suitenumerique/docs/llms.txt

Handles requests for document access, including asking for access, listing pending requests, accepting, and rejecting them. Requires authentication with a bearer token.

```bash
curl -X POST "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/ask-for-access/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "editor"
  }'
```

```bash
curl -X GET "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/ask-for-access/" \
  -H "Authorization: Bearer <token>"
```

```bash
curl -X POST "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/ask-for-access/request-uuid/accept/" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "role": "editor"
  }'
```

```bash
curl -X DELETE "https://docs.example.com/api/v1.0/documents/9137bbb5-3e8a-4ff7-8a36-fcc4e8bd57f4/ask-for-access/request-uuid/" \
  -H "Authorization: Bearer <token>"
```