====== Guide de création de documents avec Markdown ======
===== Introduction =====
Le [[https://daringfireball.net/projects/markdown/|Markdown]] est un langage de balisage de type //markup language// qui présente un contenu texte mais de façon enrichie.
L'intérêt est d'avoir un texte facile à lire et écrire tout en ayant ce qu'un IDE pourrait apporter de hiérarchisation, mise en évidence, tableaux...
L'autre intérêt est la possibilité, à l'instar de **LaTeX**, de pouvoir générer un document dans un autre format apportant un rendu graphique. Ceci est possible avec un outil tel que **Pandoc** (qui se base entre autres sur LaTeX).
===== Pandoc =====
[[http://pandoc.org/|Pandoc]] est un outil de conversion de document gérant un grand nombre de formats en entrée et proposant un très grand nombre de formats en sortie.
Il permet de transformer du Markdown en HTML, en PDF, et en Dokuwiki.
===== Markdown vers Dokuwiki =====
Ce wiki est basé sur [[https://www.dokuwiki.org/fr:dokuwiki|Dokuwiki]] avec une syntaxe spécifique.
Pandoc gère le format //Dokuwiki// en entrée comme en sortie.
Il est ainsi possible d'écrire des articles au format //Markdown// puis de les convertir en //Dokuwiki//.
Pour ce faire, il faut enregistrer votre texte dans un fichier, par exemple ''article.md'', puis utiliser //Pandoc// avec la commande suivante :
pandoc -f markdown -t dokuwiki article.md -o article.wiki
Cela créera le fichier //article.wiki// qui contiendra l'article au format //Dokuwiki//.
===== Présentations en Markdown =====
Afin de générer une présentation automatiquement à partir d'un fichier en Markdown, nous allons utiliser Pandoc.
==== Format du contenu en Markdown ====
Il est possible de commencer le document par des métadonnées au format //YAML// (encadrées par des ''%%---%%'').
Ensuite il suffit d'utiliser les niveaux de titres (commençant par un plusieurs dièse(s) ''%%#%%'' en fonction du niveau) pour faire varier le niveau du titre de présentation.
L'utilisation de ''%%-%%'' ou ''%%*%%'' sera interprété comme des puces. L'indentation en caractères d'espace permet de régler le niveau.
Exemple de présentation complète :
---
title: Présentation Markdown
author: Adel Daouzli
date: 25 novembre 2016
---
# Introduction
## Introduction de la présentation
**HADOLY** : Hébergeur Associatif Décentralisé et Ouvert à Lyon
Voici un exemple de présentation
# Problématique
## Constat actuel
### Pésentations Office PPT :
- Logiciel propriétaire
- Impose Windows
- Pas portable
- Formats de sortie limités
- Chronophage
- Dépendance contenu / rendu
## Attentes actuelles
### Formats de sorties :
- Orienté web, dynamique
- Orienté bureau (pdf)
- Autre (office, libre office)
- Séparation contenu / rendu
# Solutions
## Solutions disponibles
###
- Format de fichier texte type Markdown
- Pandoc pour générer différents type de sorties
## Avantages
###
- Libre
- Génère de nombreuses formats de sortie
- Dissocie le contenu du rendu
==== Conversion en PDF ====
Afin de convertir la présentation en PDF, Pandoc permet de passer par //LaTex/////Beamer//, qui devront être installés au préalable.
Pour utiliser le thème Warsaw (le classique de Beamer) la commande suivante doit être exécutée :
$ pandoc presentation.md -t beamer -V theme:Warsaw -o pres.pdf
Afin de convertir en PDF un document Markdown préalablement converti en HTML avec une feuille de style (cf //Conversion en HTML//) :
wkhtmltopdf pres.html pres.pdf
==== Conversion en HTML ====
Il est possible de générer du HTML et même en spécifiant du CSS :
$ pandoc --standalone -c style.css --from markdown --to html -o pres.html presentation.md
==== Conversion en Reveal.js ====
Il est possible de générer une présentation en HTML/JS utilisant le framework [[http://lab.hakim.se/reveal-js|Reveal.js]].
Il faudra télécharger reaveal.js dans le dossier de travail :
$ git clone https://github.com/hakimel/reveal.js
Puis convertir :
$ pandoc presentation.md -f markdown -t revealjs -s > pres.html