Conversion Markdown en HTML

Compétence spécialisée pour convertir des documents Markdown en HTML en utilisant la bibliothèque marked.js, ou en écrivant des scripts de conversion de données ; dans ce cas, des scripts similaires au repository markedJS/marked. Pour les scripts personnalisés, les connaissances ne sont pas limitées à marked.js, mais les méthodes de conversion de données sont exploitées à partir d'outils comme pandoc et gomarkdown/markdown pour la conversion de données ; jekyll/jekyll et gohugoio/hugo pour les systèmes de templating.

Le script ou l'outil de conversion doit gérer les fichiers individuels, les conversions par batch, et les configurations avancées.

Quand utiliser cette compétence

• L'utilisateur demande de « convertir markdown en html » ou « transformer des fichiers md »
• L'utilisateur veut « afficher du markdown » en tant que sortie HTML
• L'utilisateur a besoin de générer de la documentation HTML à partir de fichiers .md
• L'utilisateur construit des sites statiques à partir de contenu Markdown
• L'utilisateur construit un système de template qui convertit markdown en html
• L'utilisateur travaille sur un outil, widget, ou template personnalisé pour un système de templating existant
• L'utilisateur veut prévisualiser du Markdown en tant que HTML rendu

Conversion de Markdown en HTML

Conversions fondamentales essentielles

Pour plus de détails, voir basic-markdown-to-html.md

    ```markdown
    # Level 1
    ## Level 2

    One sentence with a [link](https://example.com), and a HTML snippet like `<p>paragraph tag</p>`.

    - `ul` list item 1
    - `ul` list item 2

    1. `ol` list item 1
    2. `ol` list item 1

    | Table Item | Description |
    | One | One is the spelling of the number `1`. |
    | Two | Two is the spelling of the number `2`. |

    ```js
    var one = 1;
    var two = 2;

    function simpleMath(x, y) {
     return x + y;
    }
    console.log(simpleMath(one, two));

```

```html
<h1>Level 1</h1>
<h2>Level 2</h2>

<p>One sentence with a <a href="https://example.com">link</a>, and a HTML snippet like <code>&lt;p&gt;paragraph tag&lt;/p&gt;</code>.</p>

<ul>
 <li>`ul` list item 1</li>
 <li>`ul` list item 2</li>
</ul>

<ol>
 <li>`ol` list item 1</li>
 <li>`ol` list item 2</li>
</ol>

<table>
 <thead>
  <tr>
   <th>Table Item</th>
   <th>Description</th>
  </tr>
 </thead>
 <tbody>
  <tr>
   <td>One</td>
   <td>One is the spelling of the number `1`.</td>
  </tr>
  <tr>
   <td>Two</td>
   <td>Two is the spelling of the number `2`.</td>
  </tr>
 </tbody>
</table>

<pre>
 <code>var one = 1;
 var two = 2;

 function simpleMath(x, y) {
  return x + y;
 }
 console.log(simpleMath(one, two));</code>
</pre>
```

### Conversions de blocs de code

Pour plus de détails, voir [code-blocks-to-html.md](references/code-blocks-to-html.md)

```text

    ```markdown
    your code here

```html
<pre><code class="language-md">
your code here
</code></pre>
```

```js
console.log("Hello world");
```

```html
<pre><code class="language-js">
console.log("Hello world");
</code></pre>
```

```markdown
  ```

  ```
  visible backticks
  ```

  ```
```

```html
  <pre><code>
  ```

  visible backticks

  ```
  </code></pre>
```

### Conversions de sections repliables

Pour plus de détails, voir [collapsed-sections-to-html.md](references/collapsed-sections-to-html.md)

```text
    ```markdown
    <details>
    <summary>More info</summary>

    ### Header inside

    - Lists
    - **Formatting**
    - Code blocks

        ```js
        console.log("Hello");

</details>
```

```html
<details>
<summary>More info</summary>

<h3>Header inside</h3>

<ul>
 <li>Lists</li>
 <li><strong>Formatting</strong></li>
 <li>Code blocks</li>
</ul>

<pre>
 <code class="language-js">console.log("Hello");</code>
</pre>

</details>
```

### Conversions d'expressions mathématiques

Pour plus de détails, voir [writing-mathematical-expressions-to-html.md](references/writing-mathematical-expressions-to-html.md)

```text
    ```markdown
    This sentence uses `$` delimiters to show math inline: $\sqrt{3x-1}+(1+x)^2$

```html
<p>This sentence uses <code>$</code> delimiters to show math inline:
 <math-renderer><math xmlns="http://www.w3.org/1998/Math/MathML">
  <msqrt><mn>3</mn><mi>x</mi><mo>−</mo><mn>1</mn></msqrt>
  <mo>+</mo><mo>(</mo><mn>1</mn><mo>+</mo><mi>x</mi>
  <msup><mo>)</mo><mn>2</mn></msup>
 </math>
</math-renderer>
</p>
```

```markdown
**The Cauchy-Schwarz Inequality**\
$$\left( \sum_{k=1}^n a_k b_k \right)^2 \leq \left( \sum_{k=1}^n a_k^2 \right) \left( \sum_{k=1}^n b_k^2 \right)$$
```

```html
<p><strong>The Cauchy-Schwarz Inequality</strong><br>
 <math-renderer>
  <math xmlns="http://www.w3.org/1998/Math/MathML">
   <msup>
    <mrow><mo>(</mo>
     <munderover><mo data-mjx-texclass="OP">∑</mo>
      <mrow><mi>k</mi><mo>=</mo><mn>1</mn></mrow><mi>n</mi>
     </munderover>
     <msub><mi>a</mi><mi>k</mi></msub>
     <msub><mi>b</mi><mi>k</mi></msub>
     <mo>)</mo>
    </mrow>
    <mn>2</mn>
   </msup>
   <mo>≤</mo>
   <mrow><mo>(</mo>
    <munderover><mo>∑</mo>
     <mrow><mi>k</mi><mo>=</mo><mn>1</mn></mrow>
     <mi>n</mi>
    </munderover>
    <msubsup><mi>a</mi><mi>k</mi><mn>2</mn></msubsup>
    <mo>)</mo>
   </mrow>
   <mrow><mo>(</mo>
     <munderover><mo>∑</mo>
      <mrow><mi>k</mi><mo>=</mo><mn>1</mn></mrow>
      <mi>n</mi>
     </munderover>
     <msubsup><mi>b</mi><mi>k</mi><mn>2</mn></msubsup>
     <mo>)</mo>
   </mrow>
  </math>
 </math-renderer></p>
```

### Conversions de tableaux

Pour plus de détails, voir [tables-to-html.md](references/tables-to-html.md)

```text
    ```markdown
    | First Header  | Second Header |
    | ------------- | ------------- |
    | Content Cell  | Content Cell  |
    | Content Cell  | Content Cell  |

```html
<table>
 <thead><tr><th>First Header</th><th>Second Header</th></tr></thead>
 <tbody>
  <tr><td>Content Cell</td><td>Content Cell</td></tr>
  <tr><td>Content Cell</td><td>Content Cell</td></tr>
 </tbody>
</table>
```

```markdown
| Left-aligned | Center-aligned | Right-aligned |
| :---         |     :---:      |          ---: |
| git status   | git status     | git status    |
| git diff     | git diff       | git diff      |
```

```html
<table>
  <thead>
   <tr>
    <th align="left">Left-aligned</th>
    <th align="center">Center-aligned</th>
    <th align="right">Right-aligned</th>
   </tr>
  </thead>
  <tbody>
   <tr>
    <td align="left">git status</td>
    <td align="center">git status</td>
    <td align="right">git status</td>
   </tr>
   <tr>
    <td align="left">git diff</td>
    <td align="center">git diff</td>
    <td align="right">git diff</td>
   </tr>
  </tbody>
</table>
```

## Travailler avec [`markedJS/marked`](references/marked.md)

### Prérequis

- Node.js installé (pour l'utilisation en CLI ou programmatique)
- Installer marked globalement pour la CLI : `npm install -g marked`
- Ou installer localement : `npm install marked`

### Méthodes de conversion rapides

Voir [marked.md](references/marked.md) **Méthodes de conversion rapides**

### Flux de travail étape par étape

Voir [marked.md](references/marked.md) **Flux de travail étape par étape**

### Configuration en CLI

### Utiliser des fichiers de configuration

Créez `~/.marked.json` pour des options persistantes :

```json
{
  "gfm": true,
  "breaks": true
}

Ou utilisez une configuration personnalisée :

marked -i input.md -o output.html -c config.json

Référence des options CLI

Avertissement de sécurité

⚠️ Marked ne nettoie PAS la sortie HTML. Pour les entrées non fiables, utilisez un sanitizer :

import { marked } from 'marked';
import DOMPurify from 'dompurify';

const unsafeHtml = marked.parse(untrustedMarkdown);
const safeHtml = DOMPurify.sanitize(unsafeHtml);

Sanitizers recommandés :

• DOMPurify (recommandé)
• sanitize-html
• js-xss

Saveurs Markdown supportées

Dépannage

Travailler avec pandoc

Prérequis

• Pandoc installé (télécharger depuis https://pandoc.org/installing.html)
• Pour la sortie PDF : installation LaTeX (MacTeX sur macOS, MiKTeX sur Windows, texlive sur Linux)
• Accès au terminal/invite de commande

Méthodes de conversion rapides

Méthode 1 : Conversion CLI basique

# Convertir markdown en HTML
pandoc input.md -o output.html

# Convertir en document autonome (inclut l'en-tête/pied de page)
pandoc input.md -s -o output.html

# Spécification explicite du format
pandoc input.md -f markdown -t html -s -o output.html

Méthode 2 : Mode filtre (interactif)

# Démarrer pandoc en tant que filtre
pandoc

# Taper du markdown, puis Ctrl-D (Linux/macOS) ou Ctrl-Z+Entrée (Windows)
Hello *pandoc*!
# Sortie : <p>Hello <em>pandoc</em>!</p>

Méthode 3 : Conversion de format

# HTML vers Markdown
pandoc -f html -t markdown input.html -o output.md

# Markdown vers LaTeX
pandoc input.md -s -o output.tex

# Markdown vers PDF (nécessite LaTeX)
pandoc input.md -s -o output.pdf

# Markdown vers Word
pandoc input.md -s -o output.docx

Configuration en CLI

Avertissement de sécurité

⚠️ Pandoc traite fidèlement l'entrée. Lors de la conversion de markdown non fiable :

• Utiliser le mode --sandbox pour désactiver l'accès aux fichiers externes
• Valider l'entrée avant le traitement
• Nettoyer la sortie HTML si elle est affichée dans les navigateurs

# Exécuter en mode sandbox pour les entrées non fiables
pandoc --sandbox input.md -o output.html

Saveurs Markdown supportées

Dépannage

Travailler avec gomarkdown/markdown

Prérequis

• Go 1.18 ou supérieur installé
• Installer la bibliothèque : go get github.com/gomarkdown/markdown
• Pour l'outil CLI : go install github.com/gomarkdown/mdtohtml@latest

Méthodes de conversion rapides

Méthode 1 : Conversion simple (Go)

package main

import (
    "fmt"
    "github.com/gomarkdown/markdown"
)

func main() {
    md := []byte("# Hello World\n\nThis is **bold** text.")
    html := markdown.ToHTML(md, nil, nil)
    fmt.Println(string(html))
}

Méthode 2 : Outil CLI

# Installer mdtohtml
go install github.com/gomarkdown/mdtohtml@latest

# Convertir un fichier
mdtohtml input.md output.html

# Convertir un fichier (sortie vers stdout)
mdtohtml input.md

Méthode 3 : Parser et Renderer personnalisés

package main

import (
    "github.com/gomarkdown/markdown"
    "github.com/gomarkdown/markdown/html"
    "github.com/gomarkdown/markdown/parser"
)

func mdToHTML(md []byte) []byte {
    // Créer un parser avec des extensions
    extensions := parser.CommonExtensions | parser.AutoHeadingIDs | parser.NoEmptyLineBeforeBlock
    p := parser.NewWithExtensions(extensions)
    doc := p.Parse(md)

    // Créer un renderer HTML avec des extensions
    htmlFlags := html.CommonFlags | html.HrefTargetBlank
    opts := html.RendererOptions{Flags: htmlFlags}
    renderer := html.NewRenderer(opts)

    return markdown.Render(doc, renderer)
}

Configuration en CLI

L'outil CLI mdtohtml a des options minimales :

mdtohtml input-file [output-file]

Pour une configuration avancée, utilisez la bibliothèque Go de manière programmatique avec des options de parser et renderer :

Avertissement de sécurité

⚠️ gomarkdown ne nettoie PAS la sortie HTML. Pour les entrées non fiables, utiliser Bluemonday :

import (
    "github.com/microcosm-cc/bluemonday"
    "github.com/gomarkdown/markdown"
)

maybeUnsafeHTML := markdown.ToHTML(md, nil, nil)
html := bluemonday.UGCPolicy().SanitizeBytes(maybeUnsafeHTML)

Sanitizer recommandé : Bluemonday

Saveurs Markdown supportées

Dépannage

Travailler avec jekyll

Prérequis

• Version Ruby 2.7.0 ou supérieure
• RubyGems
• GCC et Make (pour les extensions natives)
• Installer Jekyll et Bundler : gem install jekyll bundler

Méthodes de conversion rapides

Méthode 1 : Créer un nouveau site

# Créer un nouveau site Jekyll
jekyll new myblog

# Accéder au répertoire du site
cd myblog

# Construire et servir localement
bundle exec jekyll serve

# Accéder à http://localhost:4000

Méthode 2 : Construire un site statique

# Construire le site dans le répertoire _site
bundle exec jekyll build

# Construire avec l'environnement production
JEKYLL_ENV=production bundle exec jekyll build

Méthode 3 : Rechargement en direct pendant le développement

# Servir avec rechargement en direct
bundle exec jekyll serve --livereload

# Servir avec les brouillons
bundle exec jekyll serve --drafts

Configuration en CLI

Avertissement de sécurité

⚠️ Considérations de sécurité Jekyll :

• Éviter d'utiliser safe: false en production
• Utiliser exclude dans _config.yml pour empêcher la publication de fichiers sensibles
• Nettoyer le contenu généré par l'utilisateur en cas d'acceptation d'entrée externe
• Maintenir Jekyll et les plugins à jour

# Paramètres de sécurité dans _config.yml
exclude:
  - Gemfile
  - Gemfile.lock
  - node_modules
  - vendor

Saveurs Markdown supportées

Configurer le processeur markdown dans _config.yml :

markdown: kramdown
kramdown:
  input: GFM
  syntax_highlighter: rouge

Dépannage

Travailler avec hugo

Prérequis

• Hugo installé (télécharger depuis https://gohugo.io/installation/)
• Git (recommandé pour les thèmes et modules)
• Go (optionnel, pour les modules Hugo)

Méthodes de conversion rapides

Méthode 1 : Créer un nouveau site

# Créer un nouveau site Hugo
hugo new site mysite

# Accéder au répertoire du site
cd mysite

# Ajouter un thème
git init
git submodule add https://github.com/theNewDynamic/gohugo-theme-ananke themes/ananke
echo "theme = 'ananke'" >> hugo.toml

# Créer du contenu
hugo new content posts/my-first-post.md

# Démarrer le serveur de développement
hugo server -D

Méthode 2 : Construire un site statique

# Construire le site dans le répertoire public
hugo

# Construire avec minification
hugo --minify

# Construire pour un environnement spécifique
hugo --environment production

Méthode 3 : Serveur de développement

# Démarrer le serveur avec les brouillons
hugo server -D

# Démarrer avec rechargement en direct et se lier à toutes les interfaces
hugo server --bind 0.0.0.0 --baseURL http://localhost:1313/

# Démarrer avec un port spécifique
hugo server --port 8080

Configuration en CLI

Avertissement de sécurité

⚠️ Considérations de sécurité Hugo :

• Configurer la politique de sécurité dans hugo.toml pour les commandes externes
• Utiliser --enableGitInfo avec prudence avec les repositories publics
• Valider les paramètres de shortcode pour le contenu généré par l'utilisateur

# Paramètres de sécurité dans hugo.toml
[security]
  enableInlineShortcodes = false
  [security.exec]
    allow = ['^go$', '^npx$', '^postcss$']
  [security.funcs]
    getenv = ['^HUGO_', '^CI$']
  [security.http]
    methods = ['(?i)GET|POST']
    urls = ['.*']

Saveurs Markdown supportées

Configurer markdown dans hugo.toml :

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      strikethrough = true
      table = true
      taskList = true
    [markup.goldmark.renderer]
      unsafe = false  # Définir à true pour permettre le HTML brut

Dépannage

Références

Écriture et stylisation Markdown

• basic-markdown.md
• code-blocks.md
• collapsed-sections.md
• tables.md
• writing-mathematical-expressions.md
• Markdown Guide : https://www.markdownguide.org/basic-syntax/
• Stylisation Markdown : https://github.com/sindresorhus/github-markdown-css

markedJS/marked

• Documentation officielle : https://marked.js.org/
• Options avancées : https://marked.js.org/using_advanced
• Extensibilité : https://marked.js.org/using_pro
• Repository GitHub : https://github.com/markedjs/marked

pandoc

• Pour commencer : https://pandoc.org/getting-started.html
• Documentation officielle : https://pandoc.org/MANUAL.html
• Extensibilité : https://pandoc.org/extras.html
• Repository GitHub : https://github.com/jgm/pandoc

gomarkdown/markdown

• Documentation officielle : https://pkg.go.dev/github.com/gomarkdown/markdown
• Configuration avancée : https://pkg.go.dev/github.com/gomarkdown/markdown@v0.0.0-20250810172220-2e2c11897d1a/html
• Traitement Markdown : https://blog.kowalczyk.info/article/cxn3/advanced-markdown-processing-in-go.html
• Repository GitHub : https://github.com/gomarkdown/markdown

jekyll

• Documentation officielle : https://jekyllrb.com/docs/
• Options de configuration : https://jekyllrb.com/docs/configuration/options/
• Plugins : https://jekyllrb.com/docs/plugins/
  • Installation
  • Generators
  • Converters
  • Commands
  • Tags
  • Filters
  • Hooks
• Repository GitHub : https://github.com/jekyll/jekyll

hugo

• Documentation officielle : https://gohugo.io/documentation/
• Tous les paramètres : https://gohugo.io/configuration/all/
• Plugins d'éditeur : https://gohugo.io/tools/editors/
• Repository GitHub : https://github.com/gohugoio/hugo