Accès direct au contenu Accès direct à la navigation

DocBook est une application PHP permettant de construire des vues HTML5 riches à partir d’une architecture de fichiers Markdown. Il inclus des fonctionnalités classiques d’un CMS comme une recherche dans les contenus, un flux RSS et une gestion des traductions.

DocBook construit un "livre" web interactif à partir de simples fichiers Markdown

Présentation

DocBook est une simple application organisée depuis un système de fichiers Markdown structuré. Chaque fichier est une "page" et chaque sous-répertoire est une "section" de pages. Les titres des fichiers et des répertoires sont utilisés comme titre de la page ou de la section.

Les vues générées par BocBook sont construites en HTML5 grâce à l’utilisation de Bootstrap.

Fichiers spéciaux

Tout fichier nommé INDEX.md dans un répertoire sera considéré comme son index et présenté lorsqu’aucun autre fichier du répertoire ne sera demandé dans l’URL.

Tout fichier nommé README.md dans un répertoire sera présenté sous la liste des contenus de ce répertoire, exactement comme le comportement par défaut d’Apache.

Fichiers d’information

Pour chaque fichier de contenu, un panel de dépendances peut être défini pour surcharger les comportements par défaut :

  • *.copyright.md : une information de copyright, de licence de protection etc,
  • *.author(s).md : une information sur le(s) auteur(s) du fichier,
  • *.changelog.md : les évolutions du fichier.

La syntaxe Markdown

La syntaxe Markdown utilisée par DocBook suit les règles du paquet Markdown Extended. Elles héritent de :

Traductions

Tout document peut être traduit en nommant ses traductions de la façon suivante :

  1. CONTENT.md
  2. CONTENT.fr.md // traduction en français
  3. ...

Règles URL

Pour tout fichier de DocBook, les règles d’URL suivantes s’appliquent :

  • */ln?LN : permet d’obtenir le contenu dans la langue LN si elle existe,
  • */download : permet de télécharger la version originale du fichier,
  • */htmlonly : rend la version HTML seule du fichier (sans navigation et outil DocBook),
  • */plain : rend la version brute du contenu (Markdown).

Organisation des fichiers

Tous les fichiers Markdown, les "pages" du site, sont stockées dans le répertoire www/ et ses sous-répertoires.

Tout média que vous souhaitez inclure dans un contenu Markdown doit être stocké dans un sous-répertoire assets/ du répertoire du fichier. Si vous ne suivez pas cette règles, votre média ne sera pas accessible par le navigateur.

Par défaut, tout fichier contenu dans un sous-répertoire nommé wip/ ne sera pas rendu public ni référencé dans le plan du site ; pour le voir, vous devrez écrire son URL manuellement.

Une organisation classique de DocBook est la suivante :

  1. | chapter-name/
  2. | ------------- README.md           // the first file shown loading the directory
  3. | ------------- assets/             // a directory containing your medias
  4. | ------------- wip/                // a directory containing your work-in-progress contents
  5. | ------------- PAGE.md             // a Markdown content file (page 1)
  6. | ------------- OTHER-PAGE.md       // another Markdown content file (page 2)
  7. | ------------- OTHER-PAGE.fr.md    // the french translation of page 2
  8. | ------------- sub-chapter1/       // a sub-directory containing a sub-chapter
  9. | ------------- sub-chapter2/       // a sub-directory containing another sub-chapter
Voir en ligne : Sources sur GitHub
GNU GPL
Les sources disponibles à l'adresse « https://github.com/atelierspierrot/docbook  » sont mises à disposition sous les termes de la licence Licence Publique Générale (GNU General Public License).