Widgets de contenu

Transforme les listes de liens en une grille réactive. Meilleur sur les pages d'index et de hub qui envoient les lecteurs ailleurs.

• Chaque en-tête devient une petite étiquette en majuscules au-dessus de sa grille. Les en-têtes sont optionnels.
• - [Title](/href) — Description. donne une carte avec un titre et une description.
• Terminez un élément avec {icon-name} pour ajouter une icône, par exemple {rocket}, {book-open}. Les noms proviennent de l'ensemble Lucide. Un nom inconnu est silencieusement ignoré — les accolades n'atteignent jamais la page.
• Mettez une image ![alt](https://raw.githubusercontent.com/docsbook-io/docs/main/content/features/url) dans l'élément pour utiliser une vraie photo au lieu d'une icône — elle remplit la même zone que l'icône. Mieux qu'une icône lorsque la carte concerne quelque chose dont vous avez une photo.
• Un élément sans lien s'affiche comme une carte non cliquable.

<!-- widget:cards -->
 
## Start here
 
- [Search](/docsbook-io/docs/content/features/search) — Let readers find a page by keyword {search}
- [Page feedback](/docsbook-io/docs/content/features/feedback) — Ask whether the page helped {thumbs-up}
 
<!-- /widget -->

Donnez un corps à une carte. Laissez une ligne vide après l'élément et indentez plus de markdown en dessous — paragraphes, une courte liste, un extrait. Cela s'affiche sous la description. Cela en vaut la peine lorsque la carte a quelque chose à expliquer ; une carte qui ne fait que désigner une destination se lit mieux en une ligne.

Donnez à une carte sa propre action. Si la dernière ligne indentée ne contient que des liens, elle devient la ligne d'appel à l'action de la carte. Une phrase qui contient simplement un lien reste un texte ordinaire.

Choisissez la mise en page. cols=1, cols=2, cols=3 ou cols=4 fixe le nombre de colonnes ; horizontal place l'icône à côté du texte au lieu de dessus, pour une ligne compacte. Les deux vont sur le marqueur d'ouverture et peuvent être combinés. Sans cols, la grille s'adapte au maximum de cartes par ligne que la largeur de la page permet, ce qui est généralement ce que vous voulez. Les écrans étroits obtiennent toujours moins de colonnes.

<!-- widget:cards cols=2 -->
 
- [Full-text search](/docsbook-io/docs/content/features/search) — Match a reader's keyword against your pages {search}
 
  Indexes every markdown file the site publishes and rebuilds itself when the
  repository changes. Nothing to reindex by hand.
 
  [Read the guide](/docsbook-io/docs/content/features/search)
 
- [Page feedback](/docsbook-io/docs/content/features/feedback) — Ask whether the page helped {thumbs-up}
 
  One click from the reader, no form and no email address. Results land per
  page, so you can sort by the pages rated worst.
 
  [Read the guide](/docsbook-io/docs/content/features/feedback)
 
<!-- /widget -->

Transforme les sections avec en-tête en une bande d'onglets avec un panneau visible. Utilisez-le lorsque la même instruction existe dans plusieurs versions parallèles et que le lecteur a besoin d'exactement l'une d'elles : un gestionnaire de paquets, un système d'exploitation, un SDK de langage, un chemin hébergé contre auto-hébergé.

• Chaque en-tête devient un onglet ; tout ce qui se trouve en dessous jusqu'au prochain en-tête du même niveau devient le panneau de cet onglet.
• Le premier onglet est celui qui s'ouvre, donc mettez la variante que la plupart des lecteurs veulent en premier.
• Un en-tête peut se terminer par {icon-name}, par exemple ### macOS {apple}. Donnez à chaque onglet une icône ou aucune — une bande où seuls certains onglets en ont une est perçue comme cassée.
• Tous les markdown fonctionnent à l'intérieur d'un panneau, y compris les tableaux et les blocs de code avec coloration syntaxique.
• Le contenu avant le premier en-tête s'affiche au-dessus de la bande comme une introduction. Utilisez-le pour la phrase qui est vraie pour chaque onglet.
• Gardez les étiquettes à un ou deux mots. La bande défile horizontalement plutôt que de s'enrouler, donc une étiquette de longueur phrase pousse les autres onglets hors de vue.
• Jusqu'à 8 onglets sont interchangeables. Une 9ème section et au-delà s'affichent en dessous de la bande comme des en-têtes ordinaires — rien n'est perdu, mais un ensemble aussi long voulait une liste d'en-têtes.
• Les panneaux sont tous dans le code source de la page et le changement est uniquement CSS, donc chaque variante reste lisible avec JavaScript désactivé et visible pour les robots d'exploration.

Ne l'utilisez pas pour cacher du contenu dont le lecteur a besoin. C'est accordion sur le matériel de référence scanné, et des en-têtes simples pour une séquence.

Transforme les sections avec en-tête en lignes que le lecteur peut développer. Meilleur pour le matériel que les gens parcourent plutôt que lisent : FAQ, dépannage, détails par option.

• Chaque en-tête devient une ligne ; tout ce qui se trouve en dessous jusqu'au prochain en-tête du même niveau devient le corps de la ligne.
• Tous les markdown fonctionnent à l'intérieur d'une ligne, y compris les blocs de code et les tableaux.
• Chaque ligne commence réduite, donc écrivez des en-têtes qui disent suffisamment pour choisir sans ouvrir.
• Le contenu avant le premier en-tête s'affiche au-dessus de l'accordéon comme une introduction.

Transforme les sections avec en-tête en une séquence connectée, de haut en bas. Utilisez-le lorsque l'ordre est important — installation, configuration, un tutoriel en plusieurs étapes. Si l'ordre n'a pas d'importance, utilisez accordion à la place.

• Chaque en-tête devient une étape, numérotée dans l'ordre du document.
• Ajouter ou supprimer une étape renumérote automatiquement le reste.

Transforme les plans en une rangée de cartes comparables, ou un tableau de plans en une matrice de comparaison. Utilisez-le là où un lecteur doit choisir entre des niveaux plutôt que de lire à leur sujet.

Le widget choisit sa forme en fonction de ce que vous avez écrit : des en-têtes présents donnent une carte par plan, une région qui est un tableau simple est redessinée en matrice. Écrivez quelle que soit la forme que la page a déjà.

Forme du plan. Chaque en-tête est un nom de plan.

• Le premier paragraphe sous l'en-tête est le prix, affiché en grand : **$20** / month met l'accent sur le nombre et garde l'unité à côté. Écrivez Free ou Contact sales de la même manière lorsqu'il n'y a pas de chiffre.
• Le deuxième paragraphe est une ligne sur qui est le plan. Il se situe entre le prix et la liste, qui est la partie la plus étroite de la carte.
• Une liste devient ce que le plan inclut, chaque élément étant coché. Un élément écrit barré — ~~Priority support~~ — obtient un tiret et s'affiche en sourdine, ce qui montre ce qu'un plan moins cher laisse de côté sans une seconde liste.
• Un paragraphe qui est uniquement **bold text** directement sous l'en-tête devient le badge de ce plan et le marque comme en vedette : un anneau autour de la carte et un bouton solide. Utilisez-le sur au maximum un plan.
• Le dernier paragraphe uniquement avec un lien du plan devient ses boutons, exactement comme dans cta. Le premier bouton du plan en vedette est solide et les autres sont fantômes, donc le bloc a une chose forte dedans.

Forme de matrice. La première colonne nomme la fonctionnalité et chaque autre colonne est un plan. Une cellule dont tout le texte est yes, no, ✓, —, included ou none devient une coche ou un tiret, avec le mot conservé dans le balisage pour les lecteurs d'écran. Une cellule contenant autre chose — 3 seats, Unlimited, une note de bas de page — est laissée exactement comme écrite. Une cellule vide reste vide : le silence n'est pas un "non".

cols=1|2|3|4 sur le marqueur d'ouverture fixe la grille à ce nombre de colonnes. La valeur par défaut s'adapte à autant de cartes que la page le permet.

Ne jamais écrire un prix, un nom de plan, une limite ou un engagement de service dans ce widget que vous n'avez pas lu à partir de la source. C'est le seul widget dont le contenu est une promesse commerciale.

Transforme les sections d'endpoint REST en un formulaire à partir duquel le lecteur peut envoyer une vraie requête, avec sa propre clé et ses paramètres.

• Un en-tête qui est une méthode et un chemin — ## POST /api/v1/chat — devient un bloc d'endpoint.
• Le premier tableau en dessous avec une colonne Field (ou Name / Parameter) devient le formulaire de requête, une entrée par ligne. Les colonnes Type, Required et Description sont utilisées lorsqu'elles sont présentes.
• Les segments de chemin modélisés comme /project/update/{projectId} obtiennent toujours leur propre entrée.
• Une entrée d'autorisation est toujours ajoutée. La clé du lecteur est envoyée depuis son propre navigateur et n'atteint jamais Docsbook.
• Documenter Authorization comme une ligne dans le tableau est acceptable : cette ligne est revendiquée par l'entrée d'en-tête ci-dessus, gardant votre description, au lieu de se redessiner une seconde fois comme un champ qui mettrait la clé dans l'URL.
• Une sous-section ### contenant un bloc de code — ### Example, ### Response — se déplace dans un panneau d'exemples à côté du formulaire, gardant son titre. Toute autre sous-section, comme un tableau ### Errors, reste dans le flux du document en dessous.

Un petit bloc bordé fermant une page avec la seule chose que le lecteur devrait faire ensuite.

• Le premier en-tête devient le titre du bloc. Il s'affiche comme une ligne stylisée plutôt qu'un véritable en-tête, donc il reste en dehors de votre plan de page.
• Un paragraphe d'introduction qui est uniquement **bold text** devient une petite sourcille en majuscules.
• Un paragraphe contenant uniquement des liens devient les boutons : le premier est solide, les autres sont en contour. Une phrase qui contient simplement un lien reste de la prose.
• Utilisez-en un par page et au maximum deux liens. Un second bloc entre en concurrence avec le premier et les deux convertissent moins bien.

<!-- widget:cta -->
 
## Publish your docs from GitHub
 
Connect a repository and your markdown is live.
 
[Create a project](https://docsbook.io/start) · [See pricing](https://docsbook.io/pricing)
 
<!-- /widget -->

Le même bloc, avec l'action principale rendue sous forme de formulaire à un champ. Ce que le lecteur tape est transmis à l'URL cible, afin qu'il puisse commencer sans avoir à le retaper sur la page suivante.

• L'URL du premier lien est la cible du formulaire, et son texte de lien étiquette le bouton.
• Nommez le champ avec un paramètre de requête vide : ?email= soumet ce que le lecteur a tapé en tant que email. Sans chaîne de requête, le champ est nommé email.
• Un paramètre qui a déjà une valeur reste inchangé — ?email=&ref=docs conserve ref=docs sur l'URL soumise, ce qui est utile pour l'attribution.
• Définissez le placeholder avec le titre markdown du lien : [Join](https://example.io/signup?email= "you@company.com").
• Le clavier suit le nom du champ : email obtient un clavier email, url / site / domain un clavier URL.
• Une cible qui ne peut pas prendre un formulaire, comme mailto: ou une ancre dans la page, se dégrade en un bouton simple.

Dirigez-le uniquement vers une URL qui lit réellement le paramètre. Une page qui l'ignore abandonne silencieusement ce que le lecteur a tapé, ce qui est pire qu'un bouton simple.

Transforme une liste de constatations en une grille de cartes, chacune portant un badge de gravité et un lien pour agir. Utilisez-le pour des constatations concrètes et prioritaires concernant votre propre documentation — résultats d'audit, problèmes de santé du contenu, toute liste "voici ce qu'il faut corriger, classée". Pour une liste simple de destinations, utilisez cards à la place.

• Chaque en-tête devient une petite étiquette de groupe en majuscules au-dessus de sa liste. Les en-têtes sont optionnels — omettez-les pour une seule liste non groupée.
• Chaque élément de la liste devient une recommandation. - [Title](/href) — Explanation. {severity} : le texte du lien est le titre, le texte après le tiret explique pourquoi c'est important et ce qu'il faut faire.
• Terminez chaque élément par un marqueur de gravité — {urgent}, {worth-doing} ou {later}. Un élément sans marqueur reconnu s'affiche comme {worth-doing} plutôt que de perdre sa gravité.
• Un élément sans lien s'affiche comme une recommandation non cliquable. Écrivez-en un uniquement lorsqu'il n'y a vraiment nulle part où envoyer le lecteur.
• Les paragraphes entre un en-tête et sa liste passent comme une prose d'introduction ordinaire.

<!-- widget:recommendations -->
 
- [You are paying to keep the same page twice](/docs/quickstart) — "Quickstart" and "Getting started" are 96% the same and neither links to the other. Keep one, merge the other into it. {urgent}
- [214 people found "Webhooks" the hard way](/docs/webhooks) — No page links to it, yet it still gets visits. Add a link from "Integrations". {worth-doing}
- [Nobody reads "Migration notes"](/docs/migration-notes) — Zero visits although 2 pages link to it. Reword the link text. {later}
 
<!-- /widget -->