Composants de contenu

Les composants de contenu rendent du texte et de la prose. Ils couvrent le texte enrichi et le markdown, les blocs de code avec coloration syntaxique, les accordéons repliables, les encarts stylisés, les citations, une table des matières générée automatiquement et l'interface de recherche au niveau de la page. Tous les composants de contenu prennent en charge la substitution de variables dans leur content ($record.*, $vars.*, key) et acceptent l'ensemble partagé props, ainsi que les modules visibility, responsive et i18n.

components:
  - type: text
    element: h1
    content: Getting Started
  - type: text
    content: '$record.body'
    props: { format: markdown }
  - type: alert
    props: { variant: info, dismissible: true }
    content: 'Heads up — this is a callout.'

text

Le composant de contenu principal. Rend du texte inline, un élément sémantique (titre, paragraphe, citation) ou du markdown complet. Le même type text couvre les titres, paragraphes et citations via son element/props.

element: code rend un simple élément <code> inline — il n'applique pas de coloration syntaxique. Pour un bloc coloré avec langue, numéros de ligne et bouton de copie, utilisez le type code.

La sortie markdown est assainie pour prévenir les attaques XSS (pas de balises <script> ni d'attributs gestionnaires d'événements). Les blocs de code incluent un bouton de copie vers le presse-papiers.

code

Un bloc de code autonome, avec coloration syntaxique. Contrairement à text avec element: code — qui rend un simple <code> inline — ce type colore la source, numérote les lignes et ajoute un bouton de copie.

Cadres, sortie et bouton de copie

Un bloc de code nu laisse le lecteur deviner : est-ce un fichier à enregistrer, ou une commande à exécuter ? Ces propriétés dessinent un cadre autour du bloc pour y répondre, et contrôlent ce que le bouton de copie place dans le presse-papiers. Elles se déclarent à la racine du composant, à côté de props.

Le cadre est résolu dans cet ordre, la première correspondance l'emportant :

1. un codeFrame explicite — y compris none, qui supprime le cadre qui serait sinon déduit ;
2. sinon un filename est présent, donc le cadre est file ;
3. sinon un output est présent, donc le cadre est terminal (seule une commande produit une sortie) ;
4. sinon none.

Les cas courants ne demandent donc qu'une seule propriété, pas deux :

components:
  # Un fichier. `filename` seul suffit à obtenir le cadre de fichier.
  - type: code
    props:
      language: yaml
    filename: hello-world.yaml
    content: |
      name: hello-world
      pages:
        - name: home
          path: /

  # Une commande et ce qu'elle affiche. `output` seul suffit à obtenir le cadre terminal.
  - type: code
    props:
      language: bash
    content: sovrium init hello-world
    output: |
      Created hello-world.yaml
      Run sovrium start hello-world.yaml to boot it.

Le bouton de copie copie la commande seule. La sortie output et l'en-tête de nom de fichier sont tous deux exclus : coller dans un shell exécute une seule commande, et coller un fichier de configuration nommé donne une configuration valide plutôt qu'une configuration précédée de son propre nom. Aucun symbole d'invite n'est rendu dans le bloc pour la même raison : un $ décoratif finirait dans le presse-papiers.

toc

Génère automatiquement une table des matières à partir de la hiérarchie de titres de la page. Cliquer sur un lien fait défiler en douceur jusqu'à l'ancre du titre ; la section active est mise en évidence selon la position de défilement.

accordion

Sections de contenu repliables, chacune avec un déclencheur de résumé et un panneau de détail.

blockquote

Un bloc de citation stylisé (text avec element: blockquote rend la même balise, sans style). Les citations imbriquées sont rendues avec une indentation croissante.

alert

Un bloc d'encart stylisé pour mettre en évidence des informations.

searchInput

Un contrôle de champ de recherche au niveau de la page qui pilote le filtrage côté client d'une liste ou d'une table liée. (La configuration du moteur plein texte — indexation, poids, recherche publique — se trouve dans la section Recherche ; ceci est le bloc de construction de l'interface.)

pageSearch

Une expérience de recherche à portée de page composée d'un champ et d'une région de résultats, liée à une table consultable. À utiliser pour le filtrage d'enregistrements au sein de la page.

Pages connexes

• Présentation des pages — structure de page et substitution de variables.
• Composants de mise en page — conteneurs, grilles, cartes.
• Composants média — images, vidéo, icônes, intégrations.
• Recherche — moteur de recherche plein texte et recherche publique.
• Composants de recherche — blocs de construction de l'interface de recherche (dans la section Recherche).
• SEO et métadonnées — en-tête de document et données structurées.