Quarkdown étend les capacités du Markdown standard pour permettre la création de documents dynamiques et interactifs. Il prend en charge des éléments comme les diagrammes, la coloration syntaxique et des composants interactifs, le tout à partir d'un fichier source unique. Ce guide couvre l'installation et les techniques essentielles pour utiliser Quarkdown de manière optimale.

Pourquoi Opter pour Quarkdown

Le Markdown traditionnel a des limites pour les documents complexes. Quarkdown permet de générer des pages web, des livres électroniques ou des présentations à partir d'un même fichier, idéal pour la documentation technique ou académique. Un exemple de configuration pour basculer en mode diapositive est :

.doctype {slides} // Active le mode présentation

L'architecture du projet se compose de plusieurs modules clés : l'outil en ligne de commande (quarkdown-cli/), le moteur de rendu principal (quarkdown-core/) et la bibliothèque standard (quarkdown-stdlib/).

Installation Rapide en 3 Étapes

Pour Windows

Utilisez le gestionnaire de paquets Scoop pour installer Quarkdown :

scoop bucket add quarkdown-repo https://example.com/quarkdown-repo
scoop install quarkdown

Pour macOS et Linux

Exécutez le script d'installation via curl :

curl -fsSL https://example.com/quarkdown/bootstrap.sh | sudo bash

Ce script, défini dans scripts/bootstrap.sh, gère automatiquemant les dépendances comme Java 17.

Installation Manuelle

Téléchargez la version stable et compilez-le avec Gradle :

./gradlew installDist

Les paramètres de build sont configurables dans gradle.properties.

Fonctionnalités Principales

Blocs de Code Avancés

La coloration syntaxique couvre plus de 20 langages, avec la possibilité de mettre en évidence des lignes spécifiques :

.code lang:{python} focus:{2..4}
    .read {examples/algorithm.py}

Cette syntaxe, détaillée dans mock/code.qd, supporte des options comme masquer les numéros de ligne ou ajouter un titre.

Génération de Diagrmames Dynamiques

Intégrez des diagrammes avec la syntaxe Mermaid, mis à jour en temps réel :

.mermaid
    .read {diagrams/workflow.mmd}

Les types supportés incluent les diagrammes de flux, de séquence et les camemberts, avec des exemples dans le répertoire mock/mermaid/.

Rendu de Formules Mathématiques

Les équations LaTeX sont rendues directement, avec support pour la numérotation et les références croisées :

Soit $ G(ω) $ la transformée de Fourier de $ g(t) $ :
$ G(ω) = \int_{-\infty}^{\infty} g(t) e^{-jωt} dt $

Cette fonctionnalité utilise le moteur KaTeX, comme illustré dans mock/math.qd.

Techniques Avancées

Fonctions Personnalisées

Définissez des fonctions réutilisables pour réduire la duplication de code :

.function {salutation}
    to depuis:
    **Bonjour, .to** depuis .depan !

.salutation {Monde} depuis:{Quarkdown}

L'implémentation de la syntaxe des fonctions se trouve dans quarkdown-stdlib/src/main/kotlin/com/quarkdown/stdlib/Function.kt.

Composition Multi-documents

Utilisez .include pour assembler des fichiers de manière modulaire, avec support pour les caractères génériques :

.includeall
    - chapitre1.qd
    - chapitre2.qd
    - annexes.qd

Un exemple de configuration est disponible dans mock/main.qd.

Composants Interactifs

Ajoutez des éléments comme des panneaux déroulants pour améliorer l'interaction :

.textcollapse {Cliquez pour voir la réponse}
    Contenu masqué qui s'affiche au clic

L'implémentation de ces composants est dans quarkdown-html/src/main/typescript/handlers/inline-collapsibles.ts.

Ressources Utiles