Aide pour rédiger des documentations (.md)

Partagez ici vos guides et explications

Aide pour rédiger des documentations (.md)

Messagepar thrymartin » 17 Avr 2020 07:11

Aide pour rédiger des documentations (.md)

Alors que je suis familier du HTML, j'ai été un peu décontenancé par le format utilisé avec Eedomus pour rédiger les fichiers d'aide de nos plugins: le Markdown langage, il s'agit d'un nième avatar de la mise en forme de texte, je ne suis pas sur de sa pertinence, on avait déjà le BBCode par exemple, utilisé dans les forums (donc ici), ou simplement le HTML, qui, de base, n'offre pas vraiment de difficultés, bien que les éditeurs wysiwyg (Ce que tu vois est ce que tu obtiens) fassent des concours de complexité en ajoutant des tonnes de mise en forme pour une simple phrase contenant juste 2 mots (une centaine de ligne de code avec Word pour simplement écrire, sans mise en forme, "Hello World", c'est abuser !).
Pas de cela ici ! Il est vrai que pour écrire des titres, du gras ou du souligné, c'est plus rapide, mais il faut quand même apprendre les subtilités du langage, aussi simple soit-il ou...
utiliser un éditeur!


Markdown
Les fichiers d'aide des plugins Eedomus sont écrit dans le format Markdown. C'est un langage qui permet d'écrire du code HTML sans manipuler de balises pour les mises en forme simple de texte, ce qui n'empêche pas du tout de les utiliser ! Son extension est .md
Je ne vais pas détailler les codes du langage, puisqu'il existe un éditeur wysiwyg en ligne !

Références
Personnellement, je préfère vous orienter vers openclassrooms ne serait-ce que parce que c'est écrit en français mais vous avez aussi le lien qui apparait dans la fenêtre de publication des plugins.
Si vous voulez insérer du code HTML pour quelque chose de spécifique (par exemple mettre un texte en couleur) et que vous n'êtes pas à l'aise avec le HTML, tapez simplement votre recherche suivi de HTML, dans l'exemple des couleurs, recherchez : "mettre du texte en couleur HTML" en faisant très attention d'éviter les pages qui vont vous compliquer la vie avec des CSS et autres adeptes de "pourquoi faire simple quand on peut faire compliqué" : par exemple, si la balise <font> a disparue du HTML5, à ma connaissance, elle est toujours comprise par les navigateurs, mais vous pouvez utiliser à la place <p style..> pour un paragraphe ou <span style...> pour des(un) mots isolés. Par exemple...
Code : Tout sélectionner
  <font color="#FF0000">mots rouges</font>
  <p style="color:red";>pagraphe rouge</p>
  <span style="color:red";>mots rouge</span>
  <span style="color:#FFCC00";>mots orange</span>


Les tableaux
Les tableaux Markdown ne fonctionnent pas ! ne les composez pas avec les éditeurs en ligne, la seule solution, qui fonctionne fort bien, est de les rédiger en HTML !
dans ce code, il ya 3 lignes de 2 colonnes, la première ligne 'titre' est en gras (th), pour ajouter une ligne, ajoutez un ensemble (tr /tr), pour ajouter une colonne, ajoutez partout une ligne (td)
SI vous voulez des bordures, remplacez <table> par <table border="1">

Code : Tout sélectionner
<table>
   <tr>
      <th>Titre</th>
      <th>Données</th>
   </tr>
   <tr>
      <td>premier</td>
      <td>valeur1</td>
   </tr>
   <tr>
      <td>deuxième</td>
      <td>valeur2</td>
   </tr>
</table>


Editeur en ligne
Voila le lien de M Editor qui a une barre d'outils, contrairement à ses concurrents qui se contentent d'afficher le résultat de votre code. Notez qu'on n'a à sa disposition que les codes Markdown ! SI vous voulez aller plus loin, si vous désirez une mise en forme qui n'existe pas dans le langage, eh bien... vous utiliserez du code HTML tout simplement ! par exemple comme on l'a vu, mettre en couleur une partie du texte...
Pour une simple aide, on peut très bien se contenter des marqueurs de base, puisque ceci est fait justement pour ceux qui ne veulent pas apprendre un langage ou se compliquer la vie.
Attention si vous développez une aide dans une autre langue, je vous déconseille d'UTF8 qui pourra vous donner des caractères bizarres sur les accentués ! préférez l'ANSI (par exemple copier-coller dans notepad puis avec un "enregistrez-sous, choisissez le codage - (installez donc plutôt notepad++ qui permet de travailler du texte, de le surligner, le colorer automatiquement dans toutes sortes de langages, php, html, json, markdonn compris !)

Comment vérifier le résultat ?
On pourrait dire simplement : avec l'éditeur wysiwyg ci-dessus, mais ce n'est pas si simple ! on n'aura pas strictement la même apparence qu'avec le lien Eedomus, en outre le début de l'aide est spécifique puisqu'elle montre l'image du plugin ainsi que son nom !
Donc, le mieux, une fois fier de son travail, c'est d'aller directement voir ce que cela donne, et vous pouvez le faire, dès l'enregistrement du plugin, avant même de tester une création :
Vous avez déjà le lien dans la description... mais...
mais pas dans toutes les langues, si vous en avez rédigé, et pas non plus avec les ancres si vous en avez posé (vous pouvez dans la fenêtre de création poser des liens sur des parties spécifiques de l'aide)

Voila la syntaxe du plugin en mode privé :
Code : Tout sélectionner
https://secure.eedomus.com/pages/doc.php?type=nomduplugin_PRIVATE&file=readme_fr.md#Ancre


nomduplugin = le nom (du fichier) de votre plugin (sans extension évidemment)
lui est adjoint _PRIVATE pour le plugin en cours de test avant publication/mise à jour
pour le plugin en anglais, il suffit de remplacer readme_fr par readme_en
#Ancre est bien sur optionnel
thrymartin
 
Messages : 920
Inscription : 03 Mars 2019
Localisation : La Réunion

Retour vers Tutoriels

Qui est en ligne ?

Utilisateurs parcourant ce forum : Aucun utilisateur inscrit et 8 invité(s)