Syntaxe wiki

Spécifications d'une syntaxe wiki utilisée depuis 2004 pour rédiger le contenu du site et la plupart de mes notes. Elle s'inspire très largement de ce qui existe déjà.

Présentation

INFO: 2018-01-22: Pages en cours de fusion et de réécriture.

Projet initié en 2004 afin de rédiger le contenu de ce site web, cette syntaxe wiki est devenue depuis le format de prédilection de la quasi-totalité de mes documents écrits, vu que je passe les 3/4 du temps à lire et/ou écrire des documents web et que le principal logiciel de prise de notes que j'utilise, Zim, fonctionne aussi avec des fichiers formatés en syntaxe wiki.

Les spécifications s'enrichissent au fur et à mesure des besoins mais restent guider par le fait que la cible principale de rendu est le HTML.

Elle n'est ni mieux ni moins bien qu'une autre syntaxe wiki ; elle reprend d'ailleurs un très grand nombre de conventions que l'on retrouve ailleurs, certaines depuis le temps béni des emails sans HTML. C'est seulement celle qui m'a permis jusqu'à maintenant d'écrire tout ce que je voulais en gardant 2 objectifs en tête : simplicité et lisibilité.

Eléments blocs

Tout élément bloc doit être précédé/suivit d'une ligne vide, à l'exception des éléments « complexes » comme les listes ou les tableaux. Pour créer un paragraphe, il suffit de sauter une ligne. Pour le reste...

Titres

^(<?level>#){1,6}\s+(<?title>.+)$
Regex d'une ligne de titre

Les lignes de titres commencent par une série de une à six croisillons (U+0023).

# Titre de niveau 1

## Titre de niveau 2

### Titre de niveau 3

#### Titre de niveau 4

##### Titre de niveau 5

###### Titre de niveau 6
Syntaxe wiki des titres.
<h1>Titre de niveau 1</h1>
<h2>Titre de niveau 2</h2>
<h3>Titre de niveau 3</h3>
<h4>Titre de niveau 4</h4>
<h5>Titre de niveau 5</h5>
<h6>Titre de niveau 6</h6>
Rendu HTML de la syntaxe wiki des titres.

Bloc de citation

  • Chaque ligne d'un bloc de citation commence par le caractère « > » (U+003E) suivit d'un espace (U+0020).
  • Le bloc est ensuite traité comme une série d'éléments blocs.
> Premier paragraphe de la citation.
> 
> Deuxième paragraphe de la citation.
Syntaxe wiki des blocs de citation.
<blockquote>
    <p>Premier paragraphe de la citation.</p>
    <p>Deuxième paragraphe de la citation.</p>
</blockquote>
Rendu HTML de la syntaxe wiki des citations.

Cette notation est celle utilisée dés 1992 par Setext.

Blocs préformatés

Les blocs préformatés sont marqués par des lignes commençant par 4 espaces (U+0020).

    bloc préformaté
    bloc préformaté
Syntaxe wiki des blocs préformatés.
<pre>bloc préformaté
bloc préformaté</pre>
Rendu HTML de la syntaxe wiki des blocs préformatés.

Listes à puces

Listes ordonées

Liste de description

Listes de tâches

  • Syntaxe pensée pour permettre d'écrire une liste de tâches
  • Inspirée par ce qui se fait dans Zim
[ ] Tâche ouverte.
[_] Tâche en cours.
[*] Tâche effectuée.
[x] Tache annulée.
Différents états de tâches.
[ ] (1) Tâche importante.
[ ] (2) Tâche moins importante.
[ ] (3) Tâche encore moins importante.
Priorité des tâches.

Tableau

Figure

  • Une ligne de 4 tirets (U+002D) délimite le début de la figure et la séparation entre le contenu et la légende.
  • Le contenu est traité comme un bloc.
  • La légende est considérée comme une collection d'éléments textuels.
----
content
----
legend
Syntaxe wiki pour les figures.
<figure>
    content
    <figcaption>legend</figcaption>
</figure>
Rendu HTML5 de la syntaxe wiki des figures.

La syntaxe a été principalement pensé pour pouvoir définir une image accompagnée de sa légende. Elle entre en conflit avec la définition d'une ligne de séprataion (hr) de certaines syntaxes.

Details

  • Le bloc commence par un double caractère « > » (U+003E) suivit d'un espace (U+0020) puis du contenu du sommaire.
  • Le détail est ensuite inséré en dessous avec une indentation minimale de 4 espaces.
  • Le détail est considéré comme une suite d'éléments blocs.
>> summary
    
    First paragraph.
    
    Second paragraph.
Syntaxe wiki pour les détails.
<details>
    <summary>summary</summary>
    <p>First paragraph.</p>
    <p>Second paragraph.</p>
</details>
Rendu HTML5 de la syntaxe wiki des détails.
chapter
4.11.1 The details element

Éléments textuels

Emphases

  • L'emphase simple commence et fini par 2 apostrophes « ' » (U+0027).
  • L'emphase forte commence et fini par 2 astérisques « * » (U+002A).
''Emphase''
**Emphase forte**
Exemple
<em>Emphase</em>
<strong>Emphase forte</strong>
Rendu HTML
[url]()
[text](url)
Syntaxe wiki pour les liens.
<a href="url">url</a>
<a href="url">text</a>
Rendu HTML de la syntaxe wiki des liens.

Markdown utilise un autre syntaxe :

[text](url "title")

Citation : référence

{{text}}
Syntaxe wiki pour la citation d'une oeuvre.
<cite>text</cite>
Rendu HTML de la syntaxe wiki pour la citation d'une oeuvre.

Citation : quote

%%text%%
%%text|source%%
Syntaxe wiki pour les citations de contenu.
<q>text</q>
<q cite="source">text</q>
Rendu HTML de la syntaxe wiki des citations de contenu.

Code

``code``
Syntaxe wiki.
<code>code</code>
Rendu HTML.

Touches clavier

~~shift~~
Syntaxe wiki.
<kbd>shift</kbd>
Rendu HTML.

Abbréviations

??Accronym|value??
Syntaxe wiki.
<abbr title="value">Accronym</abbr>
Rendu HTML.

Mesures

  • Syntaxe pensée au début pour un système de notation
((value/max))
Syntaxe wiki pour une notation.
<meter value="value" min="0" max="max">value/max</meter>
Rendu HTML de la syntaxe wiki des mesures.
((value))
((content|value))
((value/max))
((value|min|max))
((content|value|min|max))
((value|min|max|low|high|optimum))
((content|value|min|max|low|high|optimum))
Syntaxe wiki pour les mesures.
<meter value="value" min="0" max="1"></meter>
<meter value="value" min="0" max="1">content</meter>
<meter value="value" min="0" max="max">value/max</meter>
<meter value="value" min="min" max="max"></meter>
<meter value="value" min="min" max="max">content</meter>
<meter value="value" min="min" max="max" low="low" high="high" optimum="optimum"></meter>
<meter value="value" min="min" max="max" low="low" high="high" optimum="optimum">content</meter>
Rendu HTML de la syntaxe wiki des mesures.

Dates (time)

øø2022-04-11øø
øø2022-04-11|Aujourd'huiøø
Syntaxe wiki pour les dates.
<time datetime="2022-04-11">11 avril 2022</time>
<time datetime="2022-04-11">Aujourd'hui</time>
Rendu HTML des dates.

Insertions

++text++
++date|text++
Syntaxe wiki pour l'insertion de contenu.
<ins>text</ins>
<ins datetime="date">text</ins>
Rendu HTML de la syntaxe wiki pour l'insertion de contenu.

Suppressions

--text--
--date|text--
Syntaxe wiki pour la suppression de contenu.
<del>text</del>
<del datetime="date">text</del>
Rendu HTML de la syntaxe wiki pour la suppression de contenu.

Contenus embarqués

Audio

  • Recyclage de la syntaxe des liens
  • Utilisation d'un prefixe « audio: » pour préciser la nature de la source
  • L'attribut « controls » est implicite
[audio:text](audio-file)
Syntaxe pour la définition d'une source audio
<audio controls src="audio-file">
    text
</audio>
Rendu HTML

Iframes

  • Reprise de la syntaxe des liens
  • Utilisation du préfixe « iframe: » pour distinguer une iframe
[iframe:text](url)
Syntaxe pour la définition d'une iframe
<iframe src="url">
    text
</iframe>
Rendu HTML

Images

![alt](url)
Syntaxe wiki pour les éléments en ligne.
<img src="url" alt="alt">
Rendu HTML de la syntaxe wiki des images.

video

  • Même principe que pour audio
  • Utilisation du préfixe « video: »
[video:text](video-file)
Syntaxe pour la définition d'une source audio
<video controls src="video-file">
    text
</video>
Rendu HTML

Syntaxes particulières

Attributs d'éléments

Les attributs peuvent être déclarés entre deux symboles °. Leur utilisation dépend du type d'élément auquel on a à faire mais ils doivent toujours débuter la ligne ou l'élément auquel ils s'appliquent.

°°class|id|attr1=value1|attr2=value2|...°°
Définitions d'attributs

Les attributs d'éléments bloc peuvent commencer la ligne ou être placé seuls sur la première ligne du bloc. Pour les éléments complexes comme les listes à puces ou les blockquotes, cette seconde syntaxe est obligatoire :

°°important°°Paragraphe avec une classe « important ».
Syntaxe pour les attributs d'éléments blocs.
°°important°°
Paragraphe avec une classe « important ».
Syntaxe alternative pour les attributs d'éléments blocs.
<p class="important">Paragraphe avec une classe « important ».</p>
Rendu HTML de la syntaxe wiki des attributs de bloc simple.
°°my-class|my-id°°
Lorem ipsum
Syntaxe avec une classe et un identifiant.
<p class="my-class" id="my-id">Lorem ipsum</p>
Rendu HTML.
°°||data-foo=bar°°
Lorem ipsum
Syntaxe avec un attribut data-foo.
<p data-foo="bar">Lorem ipsum</p>
Rendu HTML.

Les attributs des éléments en ligne doivent être placés tout de suite après le signe d'ouverture de l'élément :

Un paragraphe avec **°°important°°une emphase forte**.
Syntaxe pour les attributs d'éléments en ligne.
<p>Un paragraphe avec <strong class="important">une emphase forte</strong>.</p>
Rendu HTML de la syntaxe wiki des attributs (élément en ligne).
Titre
Attributs de blocs dans Wiki2xhtml
Auteurs
  • [[[[Steve Frécinaux]]]]
Éditeur
log.istique.net
Date

Commentaires

Une ligne commençant par un double slash sera considéré comme une ligne de commentaire, qui n'est donc pas destinée à être affiché.

// Ligne de commentaire.
// Deuxième ligne de commentaire.
Syntaxe wiki pour les commentaires.

Inclusions

.. include:: /path/to/file|start|end
Syntaxe wiki pour l'inclusion de fichier.
  • start : Numéro de la première ligne (0 par défaut).
  • end : Numéro de la dernière ligne (fin du fichier par défaut).

Notes

A transférer...

Références

A transférer...

Changelog

A transférer...

Scripts

  • Pour insérer ponctuellement du javascript dans une page
  • Le code inséré est considéré comme un module par défaut
[script]
import foo from './bar';
foo();
Syntaxe pour écrire du code javascript
<script type="module">
    import foo from './bar';
    foo();
</srcipt>
Rendu HTML

Styles

A écrire...

Ressources et références

Markdown et évolutions

Autres syntaxes wiki

Autres types de syntaxe

Historique

2014-01
2013-05
  • add: Nouvelles syntaxes pour les listes : (1), (a), 1..
  • add: Syntaxe pour les changelog.
  • upd: Adoption de la notation « directive » de reStructuredText pour certaines syntaxe (inclusion, table des matières).
2013-03
2012-12
  • upd: Les listes supportent des états plié / déplié.
2012-10
2012-09
  • upd: Syntaxe des notes, pour coller à la syntaxe markdown.
2012-07
  • add: Syntaxe pour les iframes.
  • upd: Syntaxe code identique à reStructuredText et markdown.
2012-05
2012-03
2011-08
2011-07
  • upd: Nouvelle syntaxe de figure : 4 tirets au lieu de 3.
2011-01
  • upd: Syntaxe alternative de titres.
2010-08
  • upd: Possibilité d'indenter un bloc dans un élément de description
2010-07
  • upd: Nouvelle syntaxe pour figure : encadrée par un triple tiret.
2010-05
  • add: Syntaxe pour les références.
2007-02
2006-01
  • upd: Tableaux : lignes et cellules préfixées de double pipe.
  • upd: Changement pour l'emphase forte : ///texte///.
  • upd: Changement pour les notes : ///[ftn]///.
2005-09
  • upd: Syntaxe enrichie par le wiki2xhtml de Dotclear avec le passage au PHP.
  • add: Données brutes entourées d'un triple slash.
  • add: Attributs d'éléments.
  • add: acronymes, citation, suppression, ajout.
  • upd: Changement pour les images : ///src///.
  • upd: Changement pour le préformaté : indentation de 4 espaces.
2005-04
  • add: Listes à puces / ordonnées imbriquées.
  • upd: blockquote à plusieurs paragraphes.
2004-12