Configuration

La configuration de MarginaliaMD repose sur deux niveaux : le fichier config.local.php (paramètres techniques) et les paramètres du site (accessibles depuis l'interface d'administration).

Fichier de configuration

Le fichier data/config.local.php contient les paramètres techniques de l'application. Il est créé une fois lors de l'installation à partir du modèle config.example.php.

Chemins

Paramètre	Description
`DATA_PATH`	Répertoire racine des données. Doit être en dehors du document root du serveur web.
`DOCUMENTS_PATH`	Répertoire contenant les fichiers Markdown. Par défaut `DATA_PATH . 'documents/'`.
`VERSIONS_PATH`	Répertoire des versions archivées. Par défaut `DATA_PATH . 'versions/'`.

Base de données

MarginaliaMD supporte SQLite et MySQL. SQLite est recommandé pour la plupart des installations.

SQLite :

define('DB_DRIVER', 'sqlite');
define('DB_PATH', DATA_PATH . 'marginalia.db');

MySQL :

define('DB_DRIVER', 'mysql');
define('DB_HOST', 'localhost');
define('DB_NAME', 'marginalia');
define('DB_USER', 'marginalia_user');
define('DB_PASS', 'votre_mot_de_passe');

Authentification

Le mot de passe administrateur est stocké sous forme de hash bcrypt :

define('ADMIN_PASSWORD_HASH', '$2y$10$...');

Pour générer un nouveau hash :

php -r "echo password_hash('VotreMotDePasse', PASSWORD_BCRYPT) . PHP_EOL;"

Langue par défaut

define('DEFAULT_LANG', 'fr');

Langues disponibles : fr, en, es, de, it, pt, nl, pl.

La langue est détectée automatiquement dans cet ordre : paramètre d'URL (?lang=en), cookie, en-tête Accept-Language du navigateur, puis valeur par défaut.

URL de l'application

define('APP_URL', 'https://docs.exemple.fr');

Utilisé pour générer les liens de partage et les notifications. Sans slash final.

Limitation de débit

define('RATE_LIMIT', 60);

Nombre maximum de requêtes API par minute et par adresse IP. Mettez 0 pour désactiver (non recommandé).

Notifications (optionnel)

SMTP :

define('SMTP_HOST', 'smtp.exemple.fr');
define('SMTP_PORT', 587);
define('SMTP_USER', 'notifications@exemple.fr');
define('SMTP_PASS', 'mot_de_passe_smtp');
define('SMTP_FROM', 'notifications@exemple.fr');

Webhook (Slack, Discord, etc.) :

define('WEBHOOK_URL', 'https://hooks.slack.com/services/...');

Laissez ces valeurs vides pour désactiver les notifications correspondantes.

Mode de fonctionnement

Le paramètre SITE_MODE détermine le comportement global de l'application :

define('SITE_MODE', 'review');

Les trois modes

Mode	Description
`review`	Mode revue (par défaut). Documents partagés par lien unique, annotations toujours activées. Pas de navigation publique.
`documentation`	Portail de documentation publique. Navigation arborescente, recherche plein texte, table des matières. Annotations désactivées.
`hybrid`	Portail de documentation avec annotations optionnelles. Les annotations sont activées par document via le front matter YAML (`annotations: true`).

Choisir le bon mode

Vous souhaitez faire relire des documents par des collaborateurs ? Utilisez le mode review.
Vous souhaitez publier de la documentation accessible à tous ? Utilisez le mode documentation.
Vous souhaitez publier de la documentation tout en permettant des commentaires sur certaines pages ? Utilisez le mode hybrid.

Changement de mode : Le mode est défini dans le fichier de configuration. Vous pouvez le changer à tout moment. Les données existantes (documents, annotations) sont conservées.

Paramètres du site

Les paramètres du site sont accessibles depuis l'interface d'administration, dans la page Paramètres du site.

Page des paramètres du site avec les sections informations, liens et attribution

Informations générales

Paramètre	Description
Nom du site	Affiché dans l'en-tête et le titre des pages. Par défaut : "MarginaliaMD".
Message de bienvenue	Texte affiché sur la page d'accueil. Le HTML est autorisé.

Liens du pied de page

Paramètre	Description
URL de contact	Lien vers une page de contact.
URL des mentions légales	Lien vers les mentions légales (obligatoire en France).
URL de confidentialité	Lien vers la politique de confidentialité (RGPD).
URL de donation	Lien vers une page de don (OpenCollective, Liberapay, etc.).

Attribution

Paramètre	Description
URL du code source	Lien vers le dépôt Git du projet.
Nom de l'auteur	Affiché dans le pied de page.
URL de l'auteur	Lien vers le site de l'auteur.

Le pied de page affiche automatiquement les liens configurés, la mention de licence et l'attribution de l'auteur.

Finalisation de l'installation

Tant que l'installation n'est pas marquée comme terminée, une alerte s'affiche sur la page d'accueil (en mode revue). Cochez la case Marquer comme terminée dans les paramètres pour masquer cette alerte.

Variable d'environnement

Pour les déploiements où htdocs/ est un lien symbolique (multi-instance), définissez la variable d'environnement MARGINALIA_DATA avec le chemin absolu vers le dossier data/.

Apache :

SetEnv MARGINALIA_DATA /chemin/absolu/vers/data

Nginx :

fastcgi_param MARGINALIA_DATA /chemin/absolu/vers/data;

Cette méthode est prioritaire sur toutes les autres stratégies de détection du fichier de configuration.