markdown ~ afficher un fichier ou du contenu markdown

Conversion d'un contenu Markdown en HTML

➠ markdown : Affiche du contenu MARKDOWN provenant d'un fichier ou saisi entre les shortcodes DEMO
syntaxe 1: {up markdown}contenu{/up markdown}
syntaxe 2: {up markdown=nom_fichier_md}
author LOMART version 1.0 crédit erusev/parsedown license GNU/GPLv3
  • markdown: chemin et nom du fichier markdown ou vide pour contenu
  • strip_tags=true: 0 pour conserver les tags HTML dans le contenu saisi entre les shortcodes. Ils sont toujours conservés si la source est un fichier.
  • class: classe(s) pour bloc
  • style: style inline pour bloc

    J'ai créé cette action simple pour afficher le contenu du fichier changelog de UP: 'history.md'.

    Cette façon de procéder présente plusieurs avantages :

    • la mise à jour du plugin actualise automatiquement le fichier historique
    • le contenu est saisi dans l'IDE de développement. Moins de risque d'oubli
    • le style est celui du template du site

    Référence sur la syntaxe Mardown : wikipedia.org - michelf.ca

    Syntaxe 1 : texte saisi entre shortcode

    Mise en forme de texte au format markdown saisi dans l'éditeur de Joomla.

    Par défaut, le balisage HTML est supprimé avant la mise en forme. Pour le conserver, ajouter le paramétre strip_tags=0

    Texte codé en Markdown

    {up markdown | class=upmd }
    # titre 1
    ## titre 2
    ### titre 3
    #### titre 4
    ##### titre 5
    ###### titre 6
    
    titre 1 (autre syntaxe) 
    =======
    titre 2 (autre syntaxe) 
    -------
    
    du texte **gras**,  en *italique* ou ***gras et italique***
    
    --- une ligne séparatrice (hr)
    
    - liste à puce 
    - seconde ligne
    
    1. premièrement
    2. deuxièment
    
    > une citation 1er niveau
    >> une citation 2ème niveau
    
    ![Texte alternatif](images/admin/joomla-logo-32.png "title: Logo Joomla") une image
    
    [UN LIEN VERS GOOGLE](http://google.fr)
    
    https://up.lomart.fr    détection automatique des urls
    
        // un bloc de code
        $app = JFactory::getApplication();
        $menu = $app->getmenu();
        $homepage = ($menu->getActive() == $menu->getDefault());
        
    du texte avec `du code inline`
       
    |col 1|col 2|
    |-----|-----|
    | a   | b |
    
    {/up markdown}

    Résultat (en HTML)

    titre 1

    titre 2

    titre 3

    titre 4

    titre 5
    titre 6

    titre 1 (autre syntaxe)

    titre 2 (autre syntaxe)

    du texte gras, en italique ou gras et italique

    --- une ligne séparatrice (hr)

    • liste à puce
    • seconde ligne
    1. premièrement
    2. deuxièment

    une citation 1er niveau

    une citation 2ème niveau

    Texte alternatif une image

    UN LIEN VERS GOOGLE

    https://up.lomart.fr détection automatique des urls

    // un bloc de code
    $app = JFactory::getApplication();
    $menu = $app->getmenu();
    $homepage = ($menu->getActive() == $menu->getDefault());

    du texte avec du code inline

    col 1 col 2
    a b

    Note : pour cet exemple, j'ai ajouté du code pour styler la table avec l'action addcsshead

    {up addcsshead=.upmd table td,.upmd table th[border:#999 1px solid;padding:2px 10px]}

    Syntaxe 2 : fichier externe

    Le shortcode ci-dessous

    {up markdown=plugins/content/up/history.md |  style=border:1px green solid; padding:10px}

    affiche le contenu du fichier 'historique des modifications de UP'.

    29/6/2018 - version 1.33

    • action tab (prise en charge class et style, accordion)
    • action faq (ajout classe active sur titre ouvert)
    • modif interne
    • chgt nom : load_script_head -> load_js_code

    28/6/2018 - version 1.32

    • possibilité de personnalisation par sous-dossier custom
    • nouvelle action : kawa ;-)
    • tab : correction bug sur forcage accordion. Suppression espace sous onglets. CSS ul,li, prise en charge attributs dans regex. (merci woluweb)
    • lorem : appel du serveur en https
    • modif interne
    • link_humanise. ajout param $capitalize

    24/6/2018 - version 1.31

    • nouvelle action : addScript
    • ajout load_custom_code_head supprimé par erreur

    23/6/2018 - version 1.3

    • nouvelle action : OSMap
    • nouvelle action : facebook-timeline
    • nouvelle action : tweeter-timeline
    • markdown: suppression commentaires YAML et gestion chemin images
    • slider_owl : correction css inline
    • modif interne
    • json_arrtostr : retourne {} si vide
    • ajout load_script_head($code)
    • ajout get_jsontoarray($filename)
    • ajout strtoarray($str)
    • ajout get_content_shortcode($content, $key) array des shortcodes internes

    7/2/2018 - version 1.2

    • nouvelle action : markdown
    • ajout nouvelles actions dans le zip de base : imagemap
    • correction bug upAction.php pour compatibilité PHP 7.2
    • modif load_css_head pour
      • permettre sélecteur avec > au lieu de >
      • suppression tags HTML dans argument multilignes
    • up.xml : ajout note sur utilisation

    15/12/2017 - ajout actions

    • imagemap : création d'une image clicable et responsive

    3/12/17 - version 1.1

    • ajout action sound_hover
    • modif action html pour fermeture auto des balises
    • ajout action media_plyr
    • ajout action slider_owl
    • ajout action image_slideshow
    • ajout compilateur SCSS
    • script install pour préserver les configurations
    • bug: prise en compte argument false en json
    • reprise script exemple
    • fonction link_humanize
    • json_arrtostr. guillemets si argument chaine
    • controle non chevauchement des actions. Permet de mixer shortcode simple et avec contenu (voir slideshow_billboard)
    • correction str_append pour prise en charge de 0

    Un exemple vers la documentation de l'excellent Marknotes de Christophe Avonture

    Le texte ci-dessous est la présentation de Marknotes au Joomladay 2017 à Marseille. Il est lu directement sur son site avec le shorcode ci-dessous:

    On récupère uniquement le contenu, le CSS est celui du site d'accueil afin de préserver une unité de présentation.

    {up markdown=https://www.marknotes.fr/docs/marknotes/Presentation-de-marknotes.md | class=ombreMax p1 bg-jauneClair}

    title: 'Présentation du logiciel marknotes' created_time: '2018-08-14 23:33:44' language: fr subtitle: ''

    Présentation du logiciel marknotes

    v1 12 mai 2017

    https://www.marknotes.fr - https://github.com/cavo789/marknotes

    Téléchargement

    Cette présentation sera téléchargeable sur le site https://www.joomladay.fr/ dès la fin du #jd17fr.

    Elle sera également disponible en ligne sur le site https://www.marknotes.fr.

    Qui suis-je ?

    • Développeur d’aeSecure solution de sécurisation, d’optimisation et de nettoyage de sites web Apache
    • Développeur de marknotes, logiciel de conversion de notes en un site web de gestion de connaissances
    • Administrateur sur le forum de Joomla! France (cavo789)
    • Membre fondateur du JUG! Wallonie

    Logo marknotes

    1. Qu'est-ce que marknotes ?


    Logiciel pour centraliser en un seul endroit et

    dans un format simple et

    ouvert des notes

    en conservant la maîtrise totale des données.

    Des notes ?

    • des documentations techniques, mode d'emploi de logiciels, ...
    • des comptes-rendu de réunions,
    • des notes prises sur le vif,
    • des trucs & astuces, pense-bêtes,
    • des informations sur des abonnements,
    • des factures, tickets de caisse, comptabilité,
    • des présentations,
    • des marque-pages (bookmarks),
    • ...

    Evernote fait ça


    Et OneNote aussi en fait


    source


    Lisez-vous les conditions d'utilisation et leurs modifications ?

    Vous devriez...


    La dernière mise à jour de la Politique de confidentialité permet à certains employés d'Evernote d'exercer un contrôle des technologies d'apprentissage machine appliquées aux contenus des comptes, sous réserve des limites décrites ci-dessous, afin de développer et d'améliorer le service Evernote.

    Le principal objectif est de vérifier que nos technologies d'apprentissage machine fonctionnent correctement pour vous montrer des contenus et fonctionnalités pertinents. Nos systèmes informatiques font du bon travail, mais une intervention humaine est parfois indispensable pour vérifier que tout fonctionne comme prévu.

    https://blog.evernote.com/fr/2016/12/15/politique-de-confidentialite/

    marknotes est Open Source et ouvert

    • Vous l'auto-hébergez sur votre serveur web,
    • Il va convertir vos notes en un site web fonctionnel,
    • Vos informations restent votre propriété,
    • Parce qu'il est ouvert,
      • vos notes seront toujours accessibles,
      • modifiez-le grâce aux plugins.

    Format de fichier texte

    Les notes sont des fichiers textes sur votre disque et seront donc aisément modifiable et, mieux, réutilisable :

    docx epub html odt
    pdf txt ... ...

    Il suffit d'écrire un convertisseur (un plugin); plusieurs sont déjà disponibles. Écrivez le vôtre, c'est facile.

    Slideshow / Présentation en ligne

    Mais ce n'est pas tout, vous pourrez même écrire des notes qui seront affichées comme si vous aviez rédigé une présentation.

    Et cela sans rien faire (ou presque)

    Cette présentation est donc une note

    Voici le fichier sur le disque : md.

    Et mis en forme, avec un template basé sur reveal.js.

    Peut-être préférez-vous remark ou, plus simplement, en html.


    Notepad

    2. Installation de marknotes

    • Rendez-vous sur https://github.com/cavo789/marknotes
    • Cliquez sur le bouton Clone or download pour télécharger le zip
    • Décompressez l'archive; gardez juste le dossier /src
    • Uploadez le dossier /src sur votre serveur web (local ou distant)
    • Accédez au site, l'installation est déjà finie.

    Dossiers

    3. Écrire une note

    Écrire une note

    Choix d'un éditeur offline

    Une note, c'est juste un fichier texte.

    Vous pouvez utiliser l'éditeur le plus basique qui soit (Notepad, TextEdit, gedit, Vi, ...)

    Intérêt du mode offline

    Il n'est pas nécessaire de lancer un navigateur, ouvrir une URL, se connecter à une administration, se rendre dans un menu Article, nouvel article, ...

    On lance l'éditeur et on est prêt à écrire sa note

    On visualise sa note depuis son navigateur (mode slideshow p.ex.), on retourne dans son éditeur, on modifie, sauve et on rafraichit la page. C'est simple et rapide !

    Courbe d'apprentissage

    • Savez-vous écrire un document texte dans Notepad ?
    • Savez-vous créer un dossier sur votre disque dur ?

    Oui ? Vous maitrisez donc déjà marknotes.

    C'est ... simplissime !!!

    Mise en forme

    Pour avoir un minimum de mise en forme, marknotes supporte nativement le langage Markdown qui est cependant optionnel.

    # Écrire avec Mardown
    Il est vraiment très simple de mettre quelques mots en **gras**
    et d'autres en *italique* avec Markdown.
    Vous pouvez même ajouter un
    [lien vers marknotes.fr](https://www.marknotes.fr)

    Tutoriel : Mastering markdown sur GitHub


    Rappel de la syntaxe markdown

    Où sauver la note ?

    Vos notes doivent être sauvées dans le dossier /docs de votre installation marknotes. Vous pouvez créer autant de dossiers que vous le souhaitez; sur votre disque dur.

    Dossier où stocker les notes

    3. L'interface de marknotes

    Démo en ligne https://www.marknotes.fr


    L'interface de marknotes

    • Interface en deux partie : le `treeview` à gauche et le contenu de la note sélectionnée à droite
    • Moteur de recherche en haut à gauche
    • Grâce aux plugins, une zone de traduction en haut à gauche ou encore des icônes de partage en haut à droite
    • Deux boutons donnant accès à une multitude d'options à gauche et à droite

    Interface dépourvue car ...

    priorité au contenu

    marknotes propose la surcharge des templates, adaptez l'affichage selon vos préférences :-)

    Vous pouvez aussi activer/désactiver les plugins comme p.ex. ceux de la traduction et du partage et créer les vôtres !

    La recherche

    Lors de la frappe, la zone d'édition affiche une liste de tags. La recherche est multi-critère comme illustré ci-dessous.

    Recherche

    L'accès aux options

    marknotes affiche deux petites roues dentées à gauche pour l'application et à droite pour la note en cours d'affichage.

    Barres d'outils

    Un clic sur le bouton fait apparaître la liste des options.

    Édition en ligne d'une note

    Un éditeur basé sur Simple MarkDown Editor est accessible depuis le bouton des fonctionnalités.

    Bouton édition

    Selon que vous ayez désactivé ou pas l'authentication, il faudra d'abord s'authentifier pour accéder à l'option d'édition

    Connexion : login et mot de passe par défaut

    Le fichier settings.json.dist reprend le login et le mot de passe par défaut :

    "username": "admin",
    "password": "marknotes"

    Copiez settings.json.dist et créez le fichier settings.json pour spécifier vos propres paramètres.


    Éditeur en ligne

    L'éditeur permet, entre autre, un affichage en deux colonnes : le code source et le rendu HTML
    Il donne aussi accès à plusieurs options dont un bouton d'encryption

    4. Utilisation avancée

    Le routeur de marknotes

    Le mode réécriture des URLs est immédiatement activé.

    Les fichiers spécifiques

    Ces fichiers n'existent pas sur le disque :

    • tag.json - La liste de vos tags
    • timeline.html - Affichage de la liste des notes, par ordre chronologique inversé,
    • sitemap.xml - Liste de vos notes pour alimenter les moteurs de recherche

    Accès direct aux fichiers

    L'accès aux notes peut se faire au travers de l'interface ainsi qu'en accès direct en tapant le lien vers la note p.e. %ROOT%/docs/joomla/Presentation-de-marknotes.html et l'on peut utiliser les différents formats supportés (.epub, .docx, .html, .md, .odt, .pdf, .reveal, .remark, .txt, ...)

    Fichiers spécifiques

    Ligne du temps - timeline.html

    La ligne du temps (timeline.html) permet d'obtenir la liste des notes, de la plus récente à la plus ancienne.

    timeline

    Sitemap - sitemap.xml

    Une carte du site, générée en temps, réel est disponible à l'adresse sitemap.xml.

    sitemap

    .slides, .reveal ou .remark

    marknotes génère, en temps réel, des affichages au format slideshow de vos notes.

    Il suffit de changer l'extension en .reveal ou .remark (https://...ma-note.html, https://...ma-note.reveal, etc.)

    Le format .slides est dynamique et respecte le choix posé par le webmaster (fichier settings.json)

    https://github.com/hakimel/reveal.js - https://github.com/gnab/remark

    pdf

    L'exportation au format .pdf utilise dompdf mais il est possible de paramétrer son site pour utiliser decktape ou pandoc afin d'avoir un rendu nettement meilleur (actuellement uniquement sous Windows).

    epub, docx, odt, txt, ...

    L'exportation aux autres formats est pris en charge par des plugins nécessitant une installation de pandoc.

    Astuce : mode présentation - choix du thème

    Cliquez en bas à gauche sur le bouton hamburger puis sélectionnez Thèmes

    Themes

    Astuce : cacher des fichiers/dossiers

    Si vous désirez masquer certains dossiers comme les dossiers qui vont contenir des images, il suffit de préfixer le nom du dossier par un point.

    .images, .sauvegardes, ... seront ignoré et non mentionné dans la liste de gauche.

    Optimisation de la vitesse du logiciel

    marknotes utilise différents mécanismes de cache, tant au niveau du serveur qu'au niveau du navigateur pour fluidifier son utilisation.

    Le bouton des options, au niveau de la liste des fichiers, permet de vider le cache.

    Plugin d'encryption

    Parce qu'une note .md est un fichier texte, marknotes propose un plugin, actif par défaut, pour crypter ses données afin qu'elles ne soient pas lisibles par quiconque aurait accès au fichier sur le disque. Il suffit pour crypter quelque chose de l'inclure dans un tag <encrypt>

    <encrypt>Mot de passe</encrypt>

    Le texte sera alors immédiatement crypté sur le disque.

    Exemple de notes partiellement cryptée

    Sans votre mot de passe et votre mode de cryptage, il va être compliqué de décrypter votre contenu.

    Vous êtes développeur ?

    Plugins

    marknotes est structuré autour de dizaines de plugins; à la manière de Joomla!

    Des plugins de contenu, d'exportation, de tâches, ...

    Vous pouvez aisément greffer vos propres fonctionnalités et étendre le logiciel à vos besoins.

    Templates

    De la même manière, les modèles d'affichage sont surchargeables, comme pour Joomla! : vous pouvez redéfinir chaque écran du logiciel, comme une surcharge d'un template dans Joomla!

    Templates multiples

    3 niveaux de templating

    Vous pouvez définir un template pour tout le site marknotes ou par dossier (un template pour vos factures, un template pour vos trucs & astuces, ...) et même, un template précis pour une note précise.

    Personnalisation poussée

    Outre les plugins et les templates, vous pouvez modifier les paramètres de marknotes en intervenant dans le fichier settings.json (pour les paramètres) et intégrer sans difficulté aucune vos scripts javascript et feuille de style (fichiers custom.js et custom.css)

    Mode débogage

    Si vous souhaitez comprendre les arcannes du logiciel marknotes, le fichier settings.json permet d'activer deux modes de débogage : simple ou avancé.

    {
        "debug": 1,
        "development": 1,
    }

    Ce mode permet de générer un fichier tmp/debug.log ainsi que certains affichages à l'écran pour vous aider à, p.ex., développer votre propre plugin.

    Debugging

    Documenter vos extensions Joomla grâce à AllEvents

    Emmanuel Lecoester, le développeur de AllEvents a écrit un composant Joomla permettant de générer la documentation technique d'une extension Joomla!.

    Son logiciel est disponible sur gitHub : https://github.com/elecoest/Manifest2MD

    Démo : https://www.allevents3.com/documentation/

    Quelques liens utiles

    Extra : Écrire un livre en 2017

    https://www.quaternum.net/2017/03/07/ecrire-un-livre-en-2017/

    Cet article est vraiment très intéressant car il illustre le potentiel d'écrire un livre complet au départ de fichier écrit avec un langage nommé AsciiDoc (fort semblable à Markdown).

    L'auteur rédige des chapitres, peut p.ex. les publier sur une plateforme collaborative comme Git, autoriser certaines personnes à corriger le texte (comité de relecture, éditeur, ...), cela durant tout le processus d'écriture.

    Ensuite, l'auteur peut générer des fichiers en sortie en pdf, epub, odt, ... mais aussi générer un site web. Tout cela au départ d'une et une seule source et donc, si l'on modifie la source, il suffirait de regénérer les différentes publications (ce qui peut être automatisé bien sûr).

    marknotes est libre

    Usez-en ! Abusez-en !

    N'hésitez pas à me proposer vos suggestions et pourquoi pas, votre code, le plugin que vous auriez écris.

    ... et ouvert

    marknotes est disponible sur GitHub : n'hésitez pas à me rejoindre et à participer; à améliorer l'interface graphique, à proposer un plugin, une correction de code, résolution d'un bug, à proposer une traduction, ...

    Faisons-en un projet collaboratif !

    Merci pour votre attention

    • Blog: https://www.marknotes.fr
    • Facebook: https://www.facebook.com/marknotes789
    • Cette adresse e-mail est protégée contre les robots spammeurs. Vous devez activer le JavaScript pour la visualiser.