Métadonnées de page
Une page DevSite est une unité de contenu unique sur un site. Une page peut comporter un titre, un corps de texte, des éléments d'en-tête et des attributs de métadonnées qui contrôlent les fonctionnalités du site. Lorsqu'un utilisateur consulte l'URL d'une page, le site affiche une page Web complète basée sur les propriétés de la page de contenu, en ajoutant des éléments dynamiques tels que l'en-tête, le pied de page et la barre latérale. Les comportements par défaut sont optimisés pour les pages de documentation technique, mais une page peut également être configurée pour d'autres utilisations, telles que le marketing et les pages de destination.
Structure d'une page
Une page DevSite est une page Web dont l'apparence générale et les fonctionnalités sont gérées par le site. Une page Google Developers s'affiche avec plusieurs zones communes. (Tous les sites ne sont pas compatibles avec l'ensemble des fonctionnalités.) Passez la souris sur le diagramme des étiquettes.
site header
Logo du site, widget de connexion, champ de recherche et barre de navigation supérieure. Commun à l'ensemble du site
project bar
Le titre du projet ou du produit, et les widgets spécifiques au projet (tels que le lien "Commentaires"). Cette zone est définie par les métadonnées du projet.
sidebar
Navigation hiérarchique dans l'ensemble du livre Cette zone est définie par les métadonnées du livre.
body
Titre et contenu de la page
page footer ("last updated")
Widgets spécifiques à la page (l'avis "Dernière mise à jour", par exemple) Peut également contenir une notification de licence CC, qui est un attribut de métadonnées du projet.
site footer
Les liens du pied de page du site, le widget de sélection de la langue. Commun à l'ensemble du site
Fichiers HTML sources
<html devsite>
<head>
<title>Page title</title>
<meta name="project_path" value="/path/to/_project.yaml" />
<meta name="book_path" value="/path/to/_book.yaml" />
</head>
<body>
<p>Body content goes here, implemented as HTML.</p>
</body>
</html>
L'attribut devsite de l'élément <html> indique au site DevSite qu'il doit être affiché sous la forme d'une page DevSite, et non textuellement sous la forme d'un élément HTML. Si votre page s'affiche sans mise en forme ni en-tête ou pied de page, vérifiez que <html devsite> apparaît dans la partie supérieure du fichier.
Les éléments <html>, <head> et <body> sont obligatoires, et doivent comporter des balises d'ouverture et de fermeture.
Une page type doit également comporter un élément <title>, à l'intérieur de <head>. Consultez la section Titre de la page.
Des balises <meta> spécifiques contrôlent les fonctionnalités de la page. Ceux-ci sont décrits dans ce document. Une page type comporte une balise Meta "project_path", qui fait référence à un fichier de métadonnées _project.yaml, et une balise Meta "book_path", qui fait référence à un fichier de métadonnées _book.yaml. Consultez la page Projets et livres. Les balises <meta> reconnues par DevSite n'apparaissent généralement pas sur la page finale.
Les autres éléments dans <head> et tous les éléments dans <body> sont affichés dans la page finale.
Fichiers sources Markdown
Project: /path/to/_project.yaml
Book: /path/to/_book.yaml
# Page title
Body content, specified in Markdown, goes here.
Une page type doit avoir un titre (par exemple, # Page title). Consultez la section Titre de la page.
Des balises Meta spécifiques contrôlent les fonctionnalités des pages. Ceux-ci sont décrits dans ce document. Une page type comporte une balise Meta Project:, qui fait référence à un fichier de métadonnées _project.yaml, et une balise Meta Book:, qui fait référence à un fichier de métadonnées _book.yaml. Voir les projets et les livres. Les balises Meta reconnues par DevSite n'apparaissent généralement pas sur la page finale.
Projets et livres
Un projet est décrit par un fichier de métadonnées de projet nommé _project.yaml. Un livre est décrit par un fichier de métadonnées de livre nommé _book.yaml. Ces fichiers sont publiés sur le site avec les fichiers de page et d'éléments, et peuvent être traduits dans plusieurs langues. Pour en savoir plus sur la structure et les attributs de ces fichiers, consultez les sections Métadonnées du projet et Métadonnées des livres.
Pour associer une page à un projet, fournissez l'attribut project_path. Sa valeur correspond au chemin d'accès au contenu du fichier _project.yaml.
HTML
<meta name="project_path" value="/path/to/_project.yaml" />
Markdown
Project: /path/to/_project.yaml
Si une page ne possède pas d'attribut project_path, elle s'affiche sans la région de la barre de projet ni ses éléments. La page ne sera pas considérée comme faisant partie d'un projet.
Pour associer une page à un livre, indiquez l'attribut book_path. Sa valeur correspond au chemin d'accès au contenu du fichier _book.yaml.
HTML
<meta name="book_path" value="/path/to/_book.yaml" />
Markdown
Book: /path/to/_book.yaml
Page title
<head>
<title>Page title</title>
...
</head>
Vous pouvez également utiliser un élément <h1> avec la classe page-title dans le <body> de la page.
HTML
<h1 class="page-title">Page title</h1>
Markdown
# Page title
Les pages d'accueil du projet n'ont pas besoin de titre,
HTML
<meta name="no_page_title" value="true" />
Markdown
no_page_title: true
Dans les cas particuliers où l'option <h1> automatique n'est pas souhaitée pour une mise en page particulière, mais qu'une page a tout de même besoin d'un titre de fenêtre, vous pouvez conserver le titre, mais le masquer avec l'attribut "hide_page_heading":
HTML
<title>Page title</title>
<meta name="hide_page_heading" value="true" />
Markdown
hide_page_heading: true
# Page title
Description de l'en-tête
De nombreux sites DevSite comportent une description dans l'en-tête. Ce paramètre est défini dans le fichier de métadonnées _project.yaml et s'affiche automatiquement sur les pages de destination DevSite. En d'autres termes, les pages créées à l'aide des modèles _index.yaml affichent automatiquement une description dans l'en-tête, qui est défini dans le fichier _project.yaml.
Cette description peut être remplacée pour la page en définissant un description à la racine du fichier _index.yaml, ou supprimée en définissant hide_description: true dans l'objet header de l'objet landing_page.
Mise en page pleine largeur
Si vous avez besoin de davantage de contrôle sur la mise en page, vous pouvez demander à DevSite de renoncer au contrôle de la mise en page dans la zone située sous l'en-tête du site et la barre de projet, ainsi qu'au-dessus du pied de page du site. Pour ce faire, définissez l'attribut de métadonnées "full_width" sur "true".
HTML
<meta name="full_width" value="true" />
Markdown
full_width: true
Date de la dernière mise à jour
Par défaut, à l'exception des pages full-width, la zone du pied de page de la page inclut automatiquement la mention "Dernière mise à jour" avis. Dans la plupart des cas, cela donne aux internautes un indicateur clair de l'actualisation du contenu de la page.
Dans certains cas, ces informations peuvent prêter à confusion ou être considérées comme confidentielles par l'équipe produit. Pour désactiver la dernière notification de mise à jour sur une page, définissez l'attribut hide_last_updated sur true:
HTML
<meta name="project_path" value="/time-travel/_project.yaml" />
<meta name="book_path" value="/time-travel/_book.yaml" />
<meta name="hide_last_updated" value="true" />
Markdown
Project: /time-travel/_project.yaml
Book: /time-travel/_book.yaml
hide_last_updated: true
Vous pouvez ignorer la "dernière mise à jour" calculée automatiquement en définissant la balise Meta refresh_date sur une date au format ISO 8601:
HTML
<meta name="project_path" value="/time-travel/_project.yaml" />
<meta name="book_path" value="/time-travel/_book.yaml" />
<meta name="refresh_date" value="2017-03-27" />
Markdown
Project: /time-travel/_project.yaml
Book: /time-travel/_book.yaml
refresh_date: 2017-03-27
Description de la page
La description d'une page est un résumé textuel du contenu de la page. Pour définir la description d'une page, fournissez un élément <meta name="description" content="DESCRIPTION" />. Notez que le texte de la description est placé dans un attribut nommé content, et non value. correspond à l'attribut standard Web.
HTML
<meta name="description" content="It was the best of times, it was the blurst of times..." />
Markdown
description: It was the best of times, it was the blurst of times...
Si vous définissez la description de la page, la balise <meta> sera incluse sur la dernière page.
Chemin de l'image
image_path est le chemin d'accès à l'image qui représente cette page dans les réseaux sociaux et dans les fonctionnalités DevSite telles que recommendations et dynamic content. Une fois définie, cette image sera utilisée comme image OpenGraph de la page, et remplace les paramètres social media du projet et les paramètres de marque tenant site's.
HTML
<meta name="image_path" value="/site-assets/developers_64dp.png" />
Markdown
image_path: /site-assets/developers_64dp.png
Mots clés
Le champ keywords est une liste de chaînes séparées par des virgules décrivant la page. Elle est utilisée dans les fonctionnalités de recherche et de découverte telles que Site Search et Dynamic Content.
Le champ keywords accepte les mots clés plats sans association dimensionnelle (par exemple, gettingstarted) et les mots clés structurés qui utilisent des espaces de noms dimensionnels pour représenter la relation entre les documents et des entités réelles, telles que les langages de programmation, les produits et les événements (par exemple, product:ComputeEngine ou language:Python3). Vous pouvez ajouter les deux types de keywords à n'importe quel champ de mot clé.
Si vous préproduisez un mot clé qui ne respecte pas les exigences de mise en forme, un avertissement indiquant la version correcte du mot clé s'affichera dans la sortie de l'outil que vous avez utilisé (généralement l'outil de ligne de commande DevSite ou DevSite Content Publisher).
HTML
<meta name="keywords" value="spacetime,timetravel,product:Delorean" />
Markdown
keywords: spacetime, timetravel, product:Delorean