Bundle Markdown pour Symfony

Développement
Package markdown pour Symfony 4 ou 5

Qu’est-ce que le markdown ?

“Markdown est un langage de balisage léger créé en 2004 par John Gruber avec l’aide d’Aaron Swartz1,2. Elle a été créée dans le but d’offrir une syntaxe facile à lire et à écrire. Un document balisé par Markdown peut être lu en l’état sans donner l’impression d’avoir été balisé ou formaté par des instructions particulières”.

Source : Wikipedia

Le markdown est un atout majeur pour faciliter l’écriture d’une documentation technique. Il permet de spécifier le langage de l’extrait du code source. Ce qui permet de colorer intelligemment cet extrait comme le fait un éditeur de code.

Exemple de documentation
docs.monofony.com

Pourquoi utiliser ce package Symfony ?

Écrire un grand nombre de fichiers de documentation dans une arborescence n’est pas très pratique si l’on ne peut pas retrouver facilement l’information.

L’objectif de ce package est justement de vous permettre de naviguer facilement entre les fichiers, grâce à plusieurs fonctionnalités :

  • Chacun de vos fichiers sera détecté automatiquement dans l’arborescence et tous les fichiers à la racine de votre répertoire de doc seront le 1er niveau de votre menu ;
  • Créer des sous-chapitres en faisant des dossiers. Ainsi, un fil ariane permettra de naviguer aisément entre les niveaux ;
  • Effectuer une recherche full-text ;
  • Utiliser votre documentation dans une interface web pour le rendre navigable ;
  • Parcourir toutes vos pages les unes après les autres comme si vous lisiez un livre, grâce à la pagination.
Github
github.com/mobizel/markdown-docs-bundle
Exemple de documentation technique Markdown pour Symfony

Vous pouvez l'utiliser pour écrire :

  • Une documentation technique d’une application ou de votre package
  • Une notice d’utilisation d’un back office ou d’une application quelle qu’elle soit
  • Un tutoriel de développement
  • Votre livre de développement en ligne
Exemple de navigation dans une documentation en Markdown

Les avantages

  • Une documentation mise en forme automatiquement
  • Ne nécessite aucune base de données
  • Peut s’intégrer au sein d’une application Symfony ou Monofony existante ou dans un projet dédié.
  • Facile à déployer chez un hébergeur
  • Configuration des droits d’accès à cette documentation (ou à certaines rubriques) à l’aide de Symfony.