Guide de création de documents avec Markdown

Le 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 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.

Ce wiki est basé sur 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.

Afin de générer une présentation automatiquement à partir d'un fichier en Markdown, nous allons utiliser Pandoc.

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
![logo hadoly](logo-hadoly.jpg "logo Hadoly")
**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

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

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

Il est possible de générer une présentation en HTML/JS utilisant le framework 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