---
title: "FAQ"
weight: 70
description: "Réponses aux questions fréquentes et résolution de problèmes courants."
---

# FAQ

## Comment changer le mot de passe administrateur ?

Générez un nouveau hash bcrypt :

```bash
php -r "echo password_hash('NouveauMotDePasse', PASSWORD_BCRYPT) . PHP_EOL;"
```

Remplacez la valeur de `ADMIN_PASSWORD_HASH` dans votre fichier `data/config.local.php`.

## La page d'accueil affiche "Installation incomplète"

Cette alerte apparaît lorsqu'un ou plusieurs éléments ne sont pas configurés :

| Message | Solution |
|---------|----------|
| Base de données non initialisée | Accédez à `/admin/` pour déclencher l'initialisation automatique |
| Mot de passe admin non configuré | Renseignez `ADMIN_PASSWORD_HASH` dans `config.local.php` |
| Dossier de données inaccessible | Vérifiez que `data/` existe et est accessible en écriture par le serveur web |
| Dossier des documents inaccessible | Vérifiez que `data/documents/` existe et est accessible en écriture |

Une fois tout résolu, allez dans **Paramètres du site** et cochez **Marquer comme terminée** pour masquer l'alerte.

## Le fichier config.local.php n'est pas trouvé

L'application cherche `config.local.php` dans plusieurs emplacements. Vérifiez :

1. Que le fichier existe dans `data/config.local.php`
2. Que le DocumentRoot de votre serveur web pointe sur le dossier `htdocs/`
3. En cas de symlinks, définissez la variable d'environnement `MARGINALIA_DATA` (voir [Configuration](/marginaliamd/configuration))

Pour tester depuis la ligne de commande :

```bash
cd /chemin/vers/marginaliamd
php -r "define('MARGINALIA', true); require 'htdocs/includes/config.php'; echo DATA_PATH;"
```

## Le CSS ne s'affiche pas correctement

Si l'interface apparaît sans style :

1. Vérifiez que le frontend est compilé :
   ```bash
   ls htdocs/assets/
   ```
2. Si le dossier est vide, recompilez :
   ```bash
   cd frontend && npm install && npm run build && cd ..
   ```

> **Fallback** : En l'absence d'assets compilés, l'application tente de charger TailwindCSS et DaisyUI depuis un CDN. Si le serveur n'a pas accès à Internet, la compilation locale est indispensable.

## Comment activer le mode documentation ?

Modifiez le paramètre `SITE_MODE` dans `data/config.local.php` :

```php
define('SITE_MODE', 'documentation');
```

Puis déposez vos fichiers Markdown dans `data/documents/` et lancez l'indexation :

```bash
php cli/index-documents.php
```

## Les documents n'apparaissent pas dans le portail

Vérifiez les points suivants :

1. Les fichiers `.md` sont bien dans `data/documents/`
2. Les fichiers sont indexés (lancez `php cli/index-documents.php`)
3. Les documents sont marqués comme actifs dans l'administration
4. Le mode est bien `documentation` ou `hybrid`

## La recherche ne fonctionne pas

La recherche plein texte utilise SQLite FTS5. Elle n'est disponible qu'en mode `documentation` ou `hybrid`.

Si la recherche ne retourne aucun résultat :

1. Vérifiez que les documents sont indexés (`php cli/index-documents.php`)
2. La recherche nécessite au moins 2 caractères
3. Vérifiez que votre version de SQLite supporte FTS5 (compilé par défaut depuis SQLite 3.9.0)

## Comment sauvegarder mon instance ?

Sauvegardez ces éléments :

```bash
# Base de données
cp data/marginalia.db data/marginalia.db.backup

# Configuration
cp data/config.local.php data/config.local.php.backup

# Documents (si nécessaire)
tar cf data/documents-backup.tar data/documents/
```

## Le rate limiting est trop restrictif

Par défaut, la limite est de 60 requêtes par minute et par IP. Si vos utilisateurs rencontrent des erreurs 429 (Too Many Requests) :

```php
define('RATE_LIMIT', 120);
```

Pour vider le cache de rate limiting :

```bash
rm data/ratelimit/*
```

## Les annotations ne s'affichent pas

- En mode **documentation** : les annotations sont désactivées par conception.
- En mode **hybrid** : vérifiez que le document contient `annotations: true` dans son front matter.
- En mode **revue** : les annotations sont toujours activées. Vérifiez que le document est actif et accessible via son hash.

## Comment déployer la documentation d'un module ?

Si vous utilisez MarginaliaMD comme portail pour documenter des modules, la méthode recommandée est de rédiger la documentation dans le dépôt du module (`docs/users/`) et de la déployer via rsync :

```bash
rsync -avLP docs/users/ serveur:chemin/vers/data/documents/nom-du-module/
```

Voir le guide de rédaction USERDOC.md pour les conventions de rédaction.

## Quelles sont les limitations connues ?

- Pas de système de comptes utilisateur (un seul mot de passe administrateur)
- Pas de notifications par email (infrastructure en place mais non finalisée)
- Pas de coloration syntaxique dans les blocs de code
- Les liens relatifs entre documents (ex: `[voir](page.md)`) ne sont pas résolus, utilisez les URLs propres (`/projet/page`)