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 grand nombre de formats en sortie.

Il permet en l'occurrence de transformer du Markdown en HTML ou en PDF.

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