Rédiger votre contenu

Mise en forme Markdown et HTML

La plupart de nos contenus sur DevSite sont écrits en Markdown, un format d'écriture conçu pour la simplicité et la lisibilité du texte brut. DevSite convertit automatiquement le code Markdown en HTML pour l'affichage sur le Web.

Pour connaître l'équivalent Markdown spécifique à Google des éléments HTML courants, consultez le mémo sur go/g3mark-cheat. Pour accéder à la documentation complète de Markdown de Google, également appelé CommonMark, cliquez ici.

Voici quelques exemples :

HTML Markdown
<b>bold text</b>
<strong>bold text</strong>		 **bold text**
<i>italic text</i>
<em>italic text</em>		 *italic text*
<h2>Heading 2</h2>
<h3>Heading 3</h3>		 ## Heading 2
### Heading 3
<a href="url.com">Link</a> [Link](url.com)
<p>paragraph</p> Paragraph
<ol>
  <li>Ordered list first item</li>
  <li>Second item</li>
</ol>		 1. Ordered list first item
1. Second item
1. Third item
<ul>
<li>Unordered list first item</li>
  <ul>
    <li>Nested list item</li>
  </ul>
<li>Second item</li>
</ul>		 * Unordered list first item
    * Nested item (indent 4-spaces)
* Second item

Quand utiliser HTML plutôt que Markdown

Certains éléments ne sont pas rédigés en Markdown, y compris :

  • Inclure des fichiers : tous les fichiers inclus doivent être des fichiers HTML et ne doivent donc pas inclure d'éléments écrits en Markdown. Pour obtenir des conseils sur la création de fichiers d'inclusion, consultez Réutiliser du contenu sur plusieurs pages.

  • Tableaux : les tableaux Markdown peuvent être difficiles à mettre en forme et à gérer. Nous utilisons donc le format HTML pour les tableaux, même dans les fichiers Markdown.

  • Images : l'utilisation du code HTML pour les images offre plus de flexibilité en termes de format et d'emplacement. Consultez le guide de publication DevSite pour les images.

  • Zippies : les zippies, également appelés widgets extensibles sur Devsite, doivent être au format HTML et être placés dans une balise <div>.

Formats de contenu courants

Suivez les consignes concernant les liens pour savoir quand ouvrir les liens dans le même onglet ou dans un nouvel onglet. Si vous devez ouvrir un lien dans un nouvel onglet, vous pouvez le mettre en forme de l'une des manières suivantes :

Markdown

[Accessible content](/style/accessibility){:target="_blank"}

HTML

<a href="/style/accessibility" target="_blank">Accessible content</a>

Tables

Pour connaître les types de tableaux proposés par Devsite et leur code HTML correspondant, consultez le guide de publication Devsite pour les tableaux.

Remarques :

  • Si vous ne souhaitez pas que votre tableau comporte de bordures, utilisez class="columns".

  • Si vous souhaitez que votre tableau comporte des marges intérieures et des lignes de séparation (comme cette page), utilisez class="columns extra-padding" et les balises <hr> sur une ligne distincte entre les lignes de contenu.

Pochettes extensibles

Pour Workspace, nous utilisons la classe arrow-icon pour styliser le zippy. Voici un exemple de zippy (widget extensible) pour Workspace :

<div>
  <devsite-expandable class="arrow-icon" id="UNIQUE_ZIPPY_ID">
    <h4 class="showalways">ZIPPY_HEADING</h4>
    <div>
      YOUR_CONTENT
    </div>
  </devsite-expandable>
</div>

Pour utiliser cet exemple, remplacez les variables suivantes :

  • UNIQUE_ZIPPY_ID : saisissez un ID descriptif et unique pour pouvoir pointer directement vers le zippy, par exemple direct-admin-access.
  • ZIPPY_HEADING : saisissez le texte que l'utilisateur doit voir avant de développer le zippy.
  • YOUR_CONTENT : saisissez le contenu que l'utilisateur doit voir lorsque le zippy est développé.

Pour en savoir plus sur le widget extensible de DevSite, consultez le guide de publication DevSite, Widgets : extensible.

Inclure le contenu partagé

Pour réutiliser du contenu sur plusieurs pages, vous pouvez utiliser des inclusions. Il s'agit de la version DevSite de l'utilisation d'extraits dans plusieurs articles de Composer.

Pour obtenir des conseils sur la création de fichiers d'inclusion et l'utilisation d'inclusions dans votre contenu, consultez Réutiliser du contenu sur plusieurs pages.

Ajouter des ancres personnalisées aux titres

DevSite crée un attribut d'ID HTML pour chaque en-tête. Pour assurer la cohérence en cas de modification du titre, vous pouvez ajouter un ID d'ancrage personnalisé à un titre en ajoutant {:#your-id} à côté du texte du titre, par exemple :

## Apply filters to your search results {:#apply-filters}

Conseil : Pour créer automatiquement des ID d'ancrage personnalisés pour tous les titres d'un fichier, appuyez sur Cmd (⌘)+H (Ctrl+H sur Windows). Les ID d'ancres personnalisés existants ne seront pas modifiés.

Pour en savoir plus, consultez le guide de publication DevSite pour les ID d'en-tête.