🚀 NotionDoc — Homebrew Tap

Synchronisez votre savoir, sans effort.

NotionDoc est une CLI TypeScript puissante qui transforme votre structure de fichiers locale en un espace de documentation Notion élégant, organisé et toujours à jour. Il fait le pont entre la documentation technique stockée dans Git et les parties prenantes non-techniques.

Dépôt principal : vincentlauriat/NotionDoc

---

🍺 Installation via Homebrew

brew tap vincentlauriat/notiondoc
brew install notiondoc

Mise à jour

brew upgrade notiondoc

Désinstallation

brew uninstall notiondoc
brew untap vincentlauriat/notiondoc

---

💡 Pourquoi NotionDoc ?

Dans le cadre du Spec Driven Development (SDD), les outils comme Bmad ou SpecKit permettent de générer une documentation riche directement depuis le code. Cependant, pour un profil non-IT, consulter cette documentation dans un dépôt Git n'est pas intuitif.

NotionDoc résout ce problème en :

• Accessibilité : Synchronisant vos specs Git vers une page Notion accessible à tous.
• Collaboration : Permettant aux métiers de consulter et de modifier la doc dans Notion.
• Cohérence : Grâce à la synchronisation bidirectionnelle, les retours faits dans Notion peuvent être réimportés dans votre dépôt.

---

✨ Points forts

• 📂 Synchronisation Intelligente : Scanne vos dossiers et ne synchronise que ce qui a changé grâce à une détection par hash SHA256 robuste.
• 🖼️ Mise en page Premium : Vos pages Notion sont automatiquement embellies avec des couvertures thématiques, des fils d'Ariane (breadcrumbs) et des bannières de métadonnées.
• 🔄 Bidirectionnel : Modifiez votre Markdown dans Notion et rapatriez les changements localement en une commande.
• 📸 Gestion des Images : Vos images locales sont automatiquement hébergées sur ImgBB et intégrées dans vos pages Notion.
• 📦 Multi-format : Support natif du Markdown, texte brut, JSON, CSV, Excel et PDF.
• 💬 Commentaires Notion : Rapatriez les commentaires de page et inline directement dans vos fichiers Markdown.
• 👀 Mode Watch : Surveillance en temps réel des fichiers locaux avec synchronisation automatique.
• 🔍 Diagnostic Intégré : Une commande check pour valider votre configuration et vos accès en un clin d'œil.

---

🚀 Démarrage en 3 étapes

1. Authentification

notiondoc auth login

2. Configuration

Initialisez un projet dans votre répertoire courant :

notiondoc config init

Modifiez ensuite la configuration sans toucher aux fichiers JSON :

notiondoc config set local enableToc true
notiondoc config set local syncDirection bidirectional
notiondoc config set local filePatterns "**/*.md,**/*.txt"

3. Synchronisation

# Synchronisation standard (local → Notion)
notiondoc sync

# Mode Watch (temps réel)
notiondoc sync --watch

# Forcer la mise à jour (écrase Notion)
notiondoc sync --force

# Exporter tout Notion → local (sans push)
notiondoc export

# Ouvrir la page Notion d'un fichier dans le navigateur
notiondoc open docs/architecture.md

# Générer un rapport Markdown après la sync
notiondoc sync --report

# Sortie JSON structurée (CI/CD)
notiondoc sync --json

---

⚙️ Configuration

Variables d'environnement

Dans votre fichier .env à la racine du projet :

NOTION_TOKEN=secret_xxx       # Votre jeton d'intégration Notion
IMGBB_API_KEY=xxx             # Optionnel : pour l'hébergement d'images

Fichier .notiondoc.json

Créé automatiquement par notiondoc config init :

{
  "notionParentPageId": "votre-page-id",
  "filePatterns": ["**/*.md", "**/*.txt"],
  "exclude": ["node_modules/**", "dist/**"],
  "syncDirection": "push",
  "enableToc": false,
  "autoArchiveOrphans": true
}

Ignorer des fichiers

Créez un fichier .notiondocignore à la racine de votre projet (syntaxe identique à .gitignore) :

dist/
node_modules/
*.tmp

---

🛠️ Options notiondoc sync

Option	Description
--watch, -w	Surveille les changements locaux et synchronise en temps réel
--force, -f	Ignore les hashs et renvoie tout vers Notion
--bidirectional, -b	Active la synchronisation descendante Notion → local
--no-archive	Désactive l'archivage automatique des pages Notion orphelines
--with-comments	Rapatrie les commentaires Notion dans les fichiers Markdown locaux
--report [chemin]	Génère un rapport Markdown après la sync (défaut : sync-report.md)
--json	Sortie JSON structurée, silences les logs (utile en CI/CD)
--dry-run	Simule la sync sans écrire dans Notion

📋 Autres commandes

Commande	Description
notiondoc export [projet]	Tire tout le contenu Notion → local sans push
notiondoc open <fichier>	Ouvre la page Notion correspondante dans le navigateur
notiondoc status	Résumé de l'état de synchronisation
notiondoc config list	Liste les projets configurés
notiondoc config check	Vérifie les tokens et la configuration
notiondoc auth login	Authentification OAuth Notion
notiondoc auth status	Vérifie l'état du token

---

🗺️ Architecture

NotionDoc est conçu pour être modulaire et extensible :

• SyncEngine : Le cœur de la logique de détection et de décision (push/pull/skip/conflict).
• FileProcessor : Transforme vos fichiers physiques en structures Notion.
• ConfigManager : Gère la résolution de configuration locale (.notiondoc.json) et globale.
• CommentReader : Récupère les commentaires Notion (page et inline) et résout les noms d'auteurs.
• UserCache : Cache persistant des utilisateurs Notion (~/.config/notiondoc/users-cache.json, TTL 24h).
• RenameDetector : Détecte les renommages/déplacements de fichiers pour préserver l'historique Notion.
• WatchEngine : Surveille le système de fichiers et déclenche la sync en temps réel.

---

🤖 Automatisation CI/CD

GitHub Actions

name: Sync to Notion
on:
  push:
    branches: [main]
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20', cache: 'npm' }
      - run: npm install && npm run build
      - run: node dist/index.js sync
        env:
          NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }}
          IMGBB_API_KEY: ${{ secrets.IMGBB_API_KEY }}

Ajoutez NOTION_TOKEN et IMGBB_API_KEY dans les Secrets de votre dépôt GitHub (Settings > Secrets and variables > Actions).

GitLab CI/CD

default:
  image: node:20-alpine
stages:
  - sync
sync-to-notion:
  stage: sync
  script:
    - npm ci
    - npm run build
    - node dist/index.js sync
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

Ajoutez NOTION_TOKEN et IMGBB_API_KEY dans les variables CI/CD GitLab (Settings > CI/CD > Variables), en les marquant masquées.

---

🚀 Roadmap

• Diff bloc-à-bloc Notion (éviter le remplacement complet à chaque update).
• Paralléliser les uploads ImgBB pour réduire la durée de sync.
• Cache ImgBB par hash d'image (éviter de ré-uploader une image déjà publiée).
• Chiffrement du token Notion via le keychain système (keytar).
• Webhook Notion → local pour un pull automatique lors de modifications côté Notion.
• Notification desktop à la fin d'une sync en mode watch.

Retrouvez toutes les idées d'évolutions dans TODOS.md.

---

📄 Licence

MIT — vincentlauriat/NotionDoc