FAQ

FAQ

Comment changer le mot de passe administrateur ?

Générez un nouveau hash bcrypt :

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)

Pour tester depuis la ligne de commande :

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é :
    ls htdocs/assets/
  2. Si le dossier est vide, recompilez :
    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 :

define('SITE_MODE', 'documentation');

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

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 :

# 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) :

define('RATE_LIMIT', 120);

Pour vider le cache de rate limiting :

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 :

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)
Éditeur de documents