Ecrivez des ebooks “web” avec GitBook et GitHub

Il y a quelques temps je m’étais mis de côté le projet GitBook http://www.gitbook.io/ qui permet de générer à partir d’un ensemble de fichiers markdown structurés une site web statique qui se parcourt comme un livre. GitBook peut aussi générer des e-books (epub) ou du pdf mais ce n’est pas là qu’il est le meilleur, préférez Pandoc pour le moment (GitBook est jeune, mais ça évoluera certainement).

Je trouve que le site généré à partir de vos fichiers markdown est particulièrement réussi et se comporte à merveille sur mobile.

Il y a plusieurs façons de l’utiliser, je vais uniquement vous parler de “ma chaîne d’édition”, pour le reste vous trouverez toutes les informations nécessaires sur https://github.com/GitbookIO/gitbook/.

Ma vie, mon œuvre

Je me suis servi de GitBook pour “concaténer” 3 articles de mon blog :

• Préparer son projet javascript
• Un peu d’interactivité dans vos outils node
• Faites vos outils avec npm et node

Cela me permettra de regrouper des sujets sur le même thèmes

GitBook a besoin d’une table des matières qui pointe sur les différents fichiers markdown de votre futur ouvrage. Cela m’a obligé à découper chacun de mes articles en plusieurs morceaux, pour avoir une TDM “équilibrée” et ce n’est finalement pas plus mal, cela donne une autre dynamique de lecture, voire même cela facilite la lecture.

Prérequis :

• node
• npm
• grunt
• un compte Github

# Installer GitBook

npm install gitbook -g

Création d’un repository Github, clonage et paramétrages

Cette étape n’est pas obligatoire, mais dans ma chaîne d’édition c’est important, mais vous n’êtes pas obligé. J’ai donc créé un repository ma-vie-mon-oeuvre chez Github que j’ai ensuite cloné sur mon poste. L’avantage d’utiliser Github, c’est aussi de pouvoir faire des e-books collaboratifs.

Ensuite dans le répertoire du projet j’ajoute :

# Un fichier README.md

Ce fichier représente l’introduction de votre livre avec du contenu au format markdown :

# TITRE DU LIVRE

Blablabla ...

## UN PARAGRAPHE

Blablabla ...

## UN AUTRE PARAGRAPHE

Etc. ...

# Un fichier SUMMARY.md qui décrit la structure de votre ouvrage

#  Summary

* [Chapitre 1](chap-01/README.md)
    * [Partie 1](chap-01/01-mon-texte.md)
    * [Partie 1](chap-01/02-mon-texte.md)
* [Chapitre 2](chap-02/README.md)
    * [Partie 1](chap-02/01-mon-texte.md)
    * [Partie 1](chap-02/02-mon-texte.md)

Donc l’arborescence de mon projet sera la suivante :

ma-vie-mon-oeuvre/
├── chap-01/
|   ├── README.md
|   ├── 01-mon-texte.md         
|   └── 02-mon-texte.md
├── chap-02/
|   ├── README.md
|   ├── 01-mon-texte.md         
|   └── 02-mon-texte.md
├── README.md
├── SUMMARY.md

Notez que chaque chapitre comme le début de l’ouvrage comporte un fichier README.md

# Un fichier package.json

avec le contenu suivant :

{
  "name": "ma-vie-mon-oeuvre",
  "version": "0.0.1",
  "description": "",
  "repository": {
    "type": "git",
    "url": "https://github.com/e-books/ma-vie-mon-oeuvre.git"
  },
  "author": "@k33g_org <https://twitter.com/k33g_org>",
  "license": "MIT",
  "dependencies": {},
  "devDependencies": {
    "grunt": "~0.4.1",
    "grunt-gitbook": "0.4.2",
    "grunt-gh-pages": "0.9.1",
    "grunt-contrib-clean": "~0.5.0"
  },
  "peerDependencies": {
    "grunt": "~0.4.1"
  }
}

# Installation des dépendances

Dans votre répertoire, faites un npm install

# Création des tâches Grunt de publication : Gruntfile.js

Il est bien sûr possible de tout faire à la main, mais Grunt vous permet d’automatiser le processus de génération, mais aussi de publication vers une branche gh-pages du repository (donc y avoir accès façon “site web”).

Créez un fichier Gruntfile.js à la racine de votre projet, avec le contenu suivant :

var path = require("path");

module.exports = function (grunt) {
  grunt.loadNpmTasks('grunt-gitbook');
  grunt.loadNpmTasks('grunt-gh-pages');
  grunt.loadNpmTasks('grunt-contrib-clean');

  grunt.initConfig({
    'gitbook': {
      development: {
        input: "./",
        github: "e-books/ma-vie-mon-oeuvre"
      }
    },
    'gh-pages': {
      options: {
        base: '_book'
      },
      src: ['**']
    },
    'clean': {
      files: '.grunt'
    }
  });

  grunt.registerTask('publish', [
    'gitbook',
    'gh-pages',
    'clean'
  ]);
  grunt.registerTask('default', 'gitbook');
};

# Ajouter une couverture

Pour cela il suffit d’ajouter à la racine du projet un fichier cover.png ou cover.jpg

# Dernier petit réglage : .gitignore

Ajouter un fichier .gitignore (toujours à la racine) avec le contenu

node_modules
.grunt
/_book/

C’est tout bon, vous êtes prêts à générer votre e-book web et à le publier. (une fois que vous avez assez de contenu).

Génération de l’e-book

Vous avez pour cela 2 possibilités:

• lancez gitbook serve, cela va générer l’e-book et vous pourrez le “visionner” dans votre navigateur à cette adresse : http://localhost:4000/
• ou bien gitbook build qui génère l’e-book mais ne lance pas de serveur http

L’e-book sera généré dans le répertoire _book (celui que nous avons exclu dans .gitignore).

Si vous êtes content de vous, vous pouvez déjà commiter et synchroniser votre projet.

Publication de l’e-book

Pour publier l’e-book sous gh-pages, il suffit de lancer la commande grunt-publish qui va générer l’e-book et le publier dans la branche gh-pages.

C’est tout!

• Vous trouverez le template projet ici : https://github.com/e-books/ma-vie-mon-oeuvre
• Le rendu html ici : http://e-books.github.io/ma-vie-mon-oeuvre/
• Et un exemple plus complet (en cours de rédaction) : http://e-books.github.io/preparer.son.projet.js/

A demain.