Shortcodes

Les shortcodes sont des gabarits invoqués depuis l’intérieur du markdown avec la syntaxe [= name =]. Le thème juicerdocs en livre 16, couvrant les encadrés, les blocs de documentation structurés, les intégrations et les atomes en ligne. Cette page est le catalogue — une entrée par shortcode avec la syntaxe exacte, le rendu visuel et les arguments qu’il accepte.

Encadrés

Cinq variantes d’admonition, chacune un shortcode apparié qui enveloppe un corps markdown. Elles partagent leur style : un fond teinté, une petite icône, un rembourrage généreux.

[= note =]

Information neutre. À utiliser pour les apartés « au fait » que le lecteur peut sauter sans rien manquer d’essentiel.

[= note =]
The frontmatter format is YAML. JSON and TOML frontmatter are
**not** supported.
[= /note =]

[= tip =]

Une suggestion ou un raccourci. À utiliser pour le contenu « vous pouvez aussi … » où le chemin alternatif est parfois le meilleur.

[= tip =]
The `juicer config` subcommand prints the merged config — it's
the fastest way to debug "why is this key not doing what I expect?"
[= /tip =]

[= warning =]

Quelque chose qui vaut la peine de ralentir. À utiliser quand ignorer cette information produira une défaillance déroutante plus tard.

[= warning =]
Permalink templates change both the URL and the on-disk write
location. Juicer doesn't keep both copies.
[= /warning =]

[= danger =]

Une mise en garde sérieuse. À utiliser pour « ceci va casser des choses » — opérations destructrices, mises en garde de sécurité, options irréversibles.

[= danger =]
Never expose a shortcode that takes user input straight into HTML.
Run it through `markdownify` or escape it explicitly.
[= /danger =]

Choisir le bon encadré

Une règle empirique : note pour l’information, tip pour un meilleur chemin, warning pour un piège, danger pour quelque chose qui cassera activement.

Blocs structurés

[= steps =]

Étapes numérotées, disposées verticalement. Les titres à l’intérieur (## Nom de l'étape) sont auto-numérotés ; le corps de chaque étape est du markdown ordinaire.

[= steps =]
## Install Juicer

Clone the repo and verify with `sbt 'juicerJVM/run --help'`.

## Make a site directory

Create `site.toml`, a `content/` folder, and `layouts/_default/`.

## Build & serve

Run `sbt 'juicerJVM/run serve -s .'` and open <http://localhost:8080>.
[= /steps =]

[= tabs =] / [= tab "Label" =]

Volets de contenu à onglets. Le tabs externe est un conteneur ; chaque tab prend un libellé comme argument positionnel et un corps markdown.

[= tabs =]
[= tab "JVM" =]
sbt 'juicerJVM/run build -s docs'
[= /tab =]
[= tab "Native" =]
juicer build -s docs
[= /tab =]
[= /tabs =]

sbt 'juicerJVM/run build -s docs'

juicer build -s docs

node ./juicer-cli.js build -s docs

[= filetree =]

Rend le contenu intérieur dans une boîte à chasse fixe. À utiliser pour les listings de répertoires en arbre — les caractères de dessin de boîtes se collent tels quels.

[= filetree =]
my-site/
├── content/
│   ├── _index.md
│   └── about.md
└── site.toml
[= /filetree =]

my-site/
├── content/
│   ├── _index.md
│   └── about.md
├── layouts/
│   └── _default/
│       ├── file.html
│       └── folder.html
└── site.toml

[= collapse "Summary" =]

<details> / <summary> natif avec le style juicerdocs. L’argument positionnel est le texte de résumé ; le corps est le contenu replié (le markdown y est rendu).

[= collapse "Why no JSON frontmatter?" =]
YAML covers the use case fluently, and supporting three formats
triples the surface area to keep correct.
[= /collapse =]

Atomes en ligne

Shortcodes auto-fermants pour de courtes fioritures d’UI en ligne.

[= kbd "Ctrl+K" /=]

Rend un élément <kbd> stylé pour ressembler à une touche de clavier. Un argument positionnel : la combinaison de touches à afficher.

Press [= kbd "Ctrl+K" /=] to focus search.
Press [= kbd "Cmd+Shift+R" /=] to hard-reload.

Appuyez sur Ctrl+K pour activer la recherche. Appuyez sur Cmd+Shift+R pour un rechargement forcé.

[= badge "alpha" /=]

Une petite étiquette en forme de pilule. Un argument positionnel : le texte intérieur.

Tag your alpha pages with [= badge "alpha" /=] so readers know.
[= badge "v0.2" /=] [= badge "beta" /=] [= badge "experimental" /=]

Marquez vos pages alpha avec alpha pour que les lecteurs le sachent. v0.2 beta experimental

Boutons et appels à l’action

[= button "Label" href="..." /=] / [= buttons =]

Un lien stylé qui ressemble à un bouton. Le premier argument positionnel est le libellé ; href est l’URL ; définir primary="true" bascule vers la variante primaire pleine. Enveloppez-en un ou plusieurs dans [= buttons =] pour un groupe en ligne.

[= buttons =]
[= button "Get started" href="/getting-started/" primary="true" /=]
[= button "Browse on GitHub" href="https://github.com/edadma/juicer" /=]
[= /buttons =]

Médias

[= figure "/img/foo.png" alt="..." caption="..." /=]

Une <figure> avec une image et une légende optionnelle. Le premier argument positionnel est l’URL de l’image. Arguments nommés : alt (texte d’accessibilité), caption (légende visible sous l’image).

[= figure "/img/diagram.svg" alt="Build pipeline diagram" caption="The juicer build pipeline" /=]

[= github "owner/repo" /=]

Une carte cliquable de dépôt GitHub. Un argument positionnel : le radical owner/repo. Rend l’icône octocat de GitHub plus le radical et le sous-titre « GitHub repository », lié au dépôt.

[= github "edadma/juicer" /=]

[= youtube "<video-id>" /=]

Une intégration iframe respectueuse de la vie privée (youtube-nocookie.com). Un argument positionnel : l’ID de la vidéo YouTube (la partie après ?v= dans l’URL).

[= youtube "dQw4w9WgXcQ" /=]

Table de référence

Pour consultation rapide :

Rédiger les vôtres

Déposez un gabarit à <src>/shortcodes/<name>.html (ou, dans un thème, à <theme>/shortcodes/<name>.html). À l’intérieur, vous avez accès à :

Un encadré minimal — gabarit à <src>/shortcodes/callout.html :

<aside class="callout callout-{{ if .kind }}{{ .kind }}{{ else }}note{{ end }}">
  {{ markdownify .content }}
</aside>

Invoquez-le depuis le markdown :

[= callout kind="success" =]
The build passed.
[= /callout =]

Voir Concepts → Shortcodes pour la syntaxe complète (règles de mise entre guillemets, échappement, paire vs auto-fermant).

Shortcodes différés — le délimiteur [~ … ~]

La syntaxe classique [= … =] s’exécute avant l’analyse du markdown. C’est la bonne phase pour les shortcodes qui émettent du markdown — un encadré note produisant <aside>…</aside> traverse correctement l’analyseur markdown parce que l’analyseur voit du HTML brut dans l’entrée.

Ce que cette phase ne peut pas faire, c’est atteindre .page.pages, .page.subsections, .section.*, ou tout champ de .site.* — ces enregistrements n’existent pas encore pendant la passe markdown. Tenter de rendre un gabarit de shortcode qui dit {{ for p <- .page.pages }} depuis [= … =] produit silencieusement une liste vide.

Juicer fournit une seconde paire de délimiteurs de shortcode, [~ … ~], qui s’exécute après que le pipeline page + section + site a terminé. À l’intérieur d’un shortcode [~, le gabarit voit :

\[~ section-list /~]

{{ // shortcodes/section-list.html — must be invoked from the deferred
   // pass because it depends on .page.pages and .page.subsections.   }}
{{ if .page.pages }}
  <ul>{{ for p <- .page.pages }}<li><a href="{{ p.url }}">{{ p.title }}</a></li>{{ end }}</ul>
{{ end }}