Documentation Crawler

Un outil puissant pour crawler et extraire le contenu des sites de documentation technique, avec conversion automatique en Markdown.

📋 Sommaire

• Présentation
• Fonctionnalités
• Installation
• Utilisation
• Configuration
• Architecture
• Stratégies de Crawling
• Build et Distribution
• Exemples
• Contribution
• Licence

🚀 Présentation

Documentation Crawler est un outil conçu pour extraire et sauvegarder le contenu des sites de documentation technique. Il permet de créer une copie locale de la documentation, à la fois en HTML et en Markdown, facilitant ainsi la consultation hors ligne et l'intégration dans d'autres systèmes.

Le crawler utilise différentes stratégies en fonction du type de site à crawler, avec des mécanismes de fallback pour garantir la récupération du contenu même dans des conditions difficiles.

✨ Fonctionnalités

• Crawling multi-stratégies : Utilise différentes approches selon le type de site
• Conversion HTML → Markdown : Transforme automatiquement le contenu HTML en Markdown
• Sauvegarde double format : Enregistre à la fois en HTML et en Markdown
• Fusion des pages : Option pour fusionner toutes les pages crawlées dans un seul fichier
• Gestion de la profondeur : Contrôle la profondeur de crawling
• Support GitHub : Crawling spécifique pour les repositories GitHub
• Gestion des sites JavaScript : Support des sites générés dynamiquement via Chromium/Puppeteer
• Interface CLI : Utilisation simple en ligne de commande

📥 Installation

Prérequis

• Node.js (v14 ou supérieur)
• npm ou yarn

Installation depuis le code source

# Cloner le repository
git clone https://github.com/votre-username/documentation-crawler.git
cd documentation-crawler

# Installer les dépendances
npm install

# Compiler le projet
npm run build

# Créer un package tarball
npm pack

# Installer globalement
npm install -g crawler-docs-1.0.x.tgz

Installation depuis npm (si publié)

npm install -g crawler-docs

🔧 Utilisation

Ligne de commande

Après installation globale, vous pouvez utiliser la commande crawler :

# Format de base
crawler <url> [output-dir] [--merge]

# Exemple standard (un fichier par page)
crawler https://docs.nestjs.com/ ./output

# Exemple avec fusion des pages dans un seul fichier
crawler https://docs.nestjs.com/ ./output --merge

Options disponibles

| Option | Description | |--------|-------------| | --merge | Fusionne toutes les pages crawlées dans un seul fichier HTML et un seul fichier Markdown |

Utilisation depuis le code source

Si vous travaillez directement avec le code source sans installation globale :

# Utiliser npm start
npm start <url> [output-dir]

# Exemple
npm start https://docs.nestjs.com/ ./output

Programmation

import { crawlSite } from './dist/main';

// Configuration du site à crawler
const siteConfig = {
  title: 'NestJS Documentation',
  startUrl: 'https://docs.nestjs.com/',
  maxDepth: 3,
  mergeOutput: true // Activer la fusion des pages dans un seul fichier
};

// Lancer le crawling
crawlSite(siteConfig, './output')
  .then(() => console.log('Crawling terminé !'))
  .catch(err => console.error('Erreur:', err));

⚙️ Configuration

Le crawler peut être configuré via un fichier config.json à la racine du projet :

{
  "docs": [
    {
      "title": "NestJS Documentation",
      "startUrl": "https://docs.nestjs.com/",
      "maxDepth": 3,
      "mergeOutput": true
    }
  ],
  "useChromiumForDocsCrawling": false
}

Options de configuration

| Option | Description | Valeur par défaut | |--------|-------------|-------------------| | docs | Liste des sites à crawler | [] | | useChromiumForDocsCrawling | Utiliser Chromium pour le crawling | false | | maxDepth | Profondeur maximale de crawling | 3 | | maxRequestsPerCrawl | Nombre maximum de requêtes par crawl | 100 | | mergeOutput | Fusionner toutes les pages dans un seul fichier | false |

🏗️ Architecture

Le projet est structuré autour de plusieurs composants clés :

• DocsCrawler : Orchestrateur principal qui sélectionne la stratégie appropriée
• Stratégies de crawling :
  • CheerioCrawler : Crawler léger basé sur Cheerio pour les sites statiques
  • ChromiumCrawler : Utilise Puppeteer pour les sites JavaScript
  • GitHubCrawler : Spécialisé pour les repositories GitHub
  • DefaultCrawler : Utilise un service externe pour le crawling

🔄 Stratégies de Crawling

CheerioCrawler

Utilise Cheerio pour parser le HTML statique. C'est la stratégie la plus rapide et la plus légère, adaptée aux sites de documentation simples.

ChromiumCrawler

Utilise Puppeteer et Chromium pour rendre les pages JavaScript. Cette stratégie est plus lente mais permet de crawler des sites avec du contenu généré dynamiquement.

GitHubCrawler

Spécialisé pour les repositories GitHub, utilise l'API GitHub pour récupérer le contenu des fichiers Markdown.

DefaultCrawler

Utilise un service externe pour le crawling, servant de fallback lorsque les autres stratégies échouent.

💻 Build et Distribution

Ce projet utilise esbuild pour créer un bundle JavaScript à partir du code TypeScript, et npm pour la distribution.

Configuration du build

• esbuild.config.mjs : Configuration d'esbuild (format ESM)
• package.json : Configuration du package avec "type": "module"
• index.cjs : Fichier bundle généré (format CommonJS)

Processus de build

Le processus de build utilise esbuild pour créer un bundle unique qui inclut toutes les dépendances nécessaires, à l'exception des modules natifs qui sont marqués comme externes. Cette approche permet d'avoir un exécutable unique et portable.

# Construire le projet
npm run build

# Créer un package tarball
npm pack

# Installer globalement
npm install -g crawler-docs-1.0.x.tgz

📝 Exemples

Crawler la documentation NestJS

crawler https://docs.nestjs.com/ ./output

Crawler un repository GitHub

crawler https://github.com/nestjs/nest ./output

Crawler et convertir en Markdown

Le crawler convertit automatiquement le contenu HTML en Markdown et enregistre les deux formats :

crawler https://www.moritzjung.dev/obsidian-meta-bind-plugin-docs ./output

Fusionner toutes les pages dans un seul fichier

Utilisez l'option --merge pour fusionner toutes les pages crawlées dans un seul fichier HTML et un seul fichier Markdown :

crawler https://docs.nestjs.com/ ./output --merge

Cela génèrera deux fichiers dans le répertoire de sortie :

• ./output/docs.nestjs.com/merged.html (version HTML)
• ./output/docs.nestjs.com/merged.md (version Markdown)

Les fichiers fusionnés incluent une table des matières avec des liens vers chaque page, facilitant la navigation.

🤝 Contribution

Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une issue ou une pull request.

1. Forkez le projet
2. Créez votre branche de fonctionnalité (git checkout -b feature/amazing-feature)
3. Committez vos changements (git commit -m 'Add some amazing feature')
4. Poussez vers la branche (git push origin feature/amazing-feature)
5. Ouvrez une Pull Request

📄 Licence

Ce projet est sous licence MIT. Voir le fichier LICENSE pour plus de détails.