Comment définir le fichier robots.txt et les balises méta Robots dans votre documentation HTML ?

Les rédacteurs techniques peuvent utiliser un fichier robots.txt spécial ou définir des balises méta robots dans leur documentation HTML pour spécifier comment les moteurs de recherche courants, tels que Google ou Bing, doivent indexer et présenter les pages individuelles dans les résultats de recherche. Dans cet article, nous verrons comment mettre à jour le modèle HTML par défaut, fourni par l’outil de création d’aide HelpNDoc, pour générer un fichier robots.txt, spécifier une valeur par défaut à l’échelle du projet pour la balise méta robots et remplacer son contenu pour des pages de documentation spécifiques. Il est inspiré du code fourni par Keith Phillips, un utilisateur de HelpNDoc que nous tenons à remercier pour sa contribution.

Créer un nouveau modèle HTML

En créant un nouveau modèle dans l’éditeur de modèles interne de HelpNDoc, nous pourrons le réutiliser pour tous les projets de documentation passés et futurs.

Il est très simple de créer un nouveau modèle HTML reposant sur le modèle par défaut :

Dans l’onglet “Outils” du ruban de HelpNDoc, cliquez sur le bouton “Éditeur de modèles” pour l’ouvrir
Cliquez sur le bouton “+”
Cliquez sur “Créer un modèle HTML”
Entrez le nom du nouveau modèle. Nous utiliserons “Modèle HTML avec méta Robots” dans cet article.

Cela créera un nouveau modèle HTML identique au modèle HTML par défaut fourni par HelpNDoc. Nous pouvons maintenant le personnaliser.

Ajouter un fichier robots.txt au modèle

Nous pouvons ajouter un fichier robots.txt statique au modèle : il sera exporté tel quel lorsque la documentation HTML sera générée et analysé par les moteurs de recherche lors de l’exploration.

Ajouter un fichier actif robots.txt à un modèle

Depuis l’éditeur de modèles de HelpNDoc, sélectionnez le nouveau modèle créé, puis accédez à la section “Actifs”. Nous pouvons maintenant créer le fichier robots.txt comme indiqué ci-dessous :

Cliquez sur “Nouveau fichier”
Nommez-le “robots.txt”
Sélectionnez-le, puis cliquez sur “Modifier l’actif” pour ouvrir votre éditeur de texte par défaut
Entrez le contenu souhaité de votre fichier robots.txt (consulter les instructions de Google pour en savoir plus). Nous pouvons par exemple permettre à tous les moteurs de recherche d’explorer et indexer toutes les pages en utilisant :

User-agent: *
Allow: /

Enregistrez le fichier et fermez l’éditeur de texte
Dans HelpNDoc, cliquez sur " Terminer l’édition"
Cliquez sur “Enregistrer” pour enregistrer le nouveau modèle créé

Désormais, les constructions utilisant ce modèle généreront automatiquement ce fichier robots.txt dans le même répertoire que la documentation générée.

Alternative : ajouter une variable de modèle pour définir la valeur par défaut de la balise méta Robots

Comme alternative à l’actif robots.txt, nous pouvons créer une variable de modèle pour préciser la valeur par défaut de la balise méta Robots qui sera ajoutée dans la section en-tête du document HTML généré.

1. Créer une nouvelle variable

Depuis l’éditeur de modèles de HelpNDoc, sélectionnez le nouveau modèle créé, puis accédez à la section “Variables”. Désormais, nous pouvons créer une nouvelle variable de balise méta par défaut :

Cliquez sur “Nouvelle Variable”
Dans la fenêtre Éditeur de variables, spécifiez ses paramètres :
Id: RobotsMetaDefault
Nom: Valeur par défaut de la balise méta Robots
Description: Valeur par défaut pour la balise méta robots
Type: string
Valeur par défaut: all
Cliquez sur “Enregistrer” pour enregistrer la nouvelle variable

2. Utiliser la variable dans les pages HTML générées

Utiliser la variable dans le HTML généré

Une fois la variable créée, nous pouvons l’utiliser dans l’un des fichiers script du modèle. Voici comment s’y prendre :

Naviguez vers la section “Fichiers script”
Sélectionnez le fichier “topics.pas.html”, qui est celui utilisé pour la production de contenu HTML dans chaque chapitre
Cliquez sur “Modifier le Script”
Après la section de déclaration des variables, ajoutez la fonction suivante :

function GetTopicRobotsMeta(): string;
begin
  // Si nous avons une valeur méta Robots par défaut, nous retournons son contenu
  if (HndGeneratorInfo.GetCustomSettingValue('RobotsMetaDefault') <> '') then
    Result := Format('<meta name="robots" content="%s" />', [HndGeneratorInfo.GetCustomSettingValue('RobotsMetaDefault')]);
end;

Faites défiler vers le bas jusqu’à la section <head> dans ce fichier, puis ajoutez une requête vers cette fonction pour produire le contenu méta :

<% print(GetTopicRobotsMeta()); %>

Désormais, si la Valeur par défaut de la balise méta Robots est définie dans les paramètres de construction, elle sera utilisée pour produire la balise méta pour toutes les pages générées pour ce projet.

Utiliser les propriétés du chapitre pour remplacer la valeur par défaut de certaines pages

Pour rendre le modèle aussi flexible que possible, nous pouvons exploiter les propriétés du chapitre pour remplacer la valeur par défaut de la balise méta Robots pour des chapitres spécifiques.

1. Gérer les propriétés du chapitre dans le modèle

Il nous faut d’abord mettre à jour notre fonction GetTopicRobotsMeta afin de vérifier si un chapitre spécifique a une valeur remplacée dans ses propriétés. Dans l’éditeur de modèles de HelpNDoc :

Naviguez vers la section “Fichiers script”
Sélectionnez le fichier “topics.pas.html”, qui est celui utilisé pour la production de contenu HTML dans chaque chapitre
Cliquez sur “Modifier le Script”
Remplacez la fonction GetTopicRobotsMeta créée précédemment par celle-ci :

function GetTopicRobotsMeta(): string;
var
  aRobotsMetaValue: string;
begin
  // Valeur vide par défaut
  Result := '';
  aRobotsMetaValue := '';
  // Si nous avons une propriété de chapitre remplacée, nous retournons son contenu
  if HndTopicsProperties.GetTopicCustomPropertyExists(HndGeneratorInfo.CurrentTopic, 'RobotsMetaOverride') then
    aRobotsMetaValue := HndTopicsProperties.GetTopicCustomPropertyValue(HndGeneratorInfo.CurrentTopic, 'RobotsMetaOverride')
  // Si nous avons une valeur méta Robots par défaut, nous retournons son contenu
  else if (HndGeneratorInfo.GetCustomSettingValue('RobotsMetaDefault') <> '') then
    aRobotsMetaValue := HndGeneratorInfo.GetCustomSettingValue('RobotsMetaDefault');
  // Si la valeur n'est pas vide, nous retournons la balise méta
  if (aRobotsMetaValue <> '') then
    Result := Format('<meta name="robots" content="%s"/>', [aRobotsMetaValue]);
end;

Cliquez sur “Enregistrer” pour enregistrer le fichier de script
Cliquez sur “Enregistrer” pour enregistrer le modèle

2. Remplacer la valeur de la balise méta robots pour certains chapitres

Le modèle étant dorénavant en place, nous pouvons simplement remplacer la valeur par défaut de la balise méta robots pour certains chapitres comme indiqué ci-dessous :

Dans l’éditeur de table des matières de HelpNDoc, rendez-vous vers le chapitre souhaitée
Dans le panneau “Propriétés du chapitre”, cliquez sur l’icône “+” pour créer une nouvelle propriété personnalisée
Spécifiez son nom : “RobotsMetaOverride”
Cliquez sur “OK”
Dans le panneau “Propriétés du chapitre”, sélectionnez et modifiez la valeur de la nouvelle propriété personnalisée créée. Par exemple noindex pour masquer cette page des résultats de recherche

Utiliser le nouveau modèle créé pour produire la documentation HTML finale

Tout est maintenant en place pour produire la documentation finale avec le nouveau modèle créé. Il suffit de le sélectionner pour la construction HTML souhaitée.

Générer de la documentation HTML avec le nouveau modèle

Le nouveau modèle créé peut à présent être utilisé par toute construction HTML dans tout projet HelpNDoc. Voici comment s’y prendre :

À partir de l’onglet “Accueil” du ruban “HelpNDoc”, dans le groupe “Projet”, cliquez sur la partie supérieure du bouton “Générer l’aide”
Sélectionnez la construction HTML dans la liste
Remplacez le modèle par le nouveau “Modèle HTML avec méta Robots” créé en cliquant sur le nom du modèle déjà sélectionné
Cliquez sur “Générer” pour créer la documentation finale

Afin de personnaliser la valeur par défaut de la balise méta robots, il est possible de le faire depuis la même boîte de dialogue :

Cliquez sur “Personnaliser” si l’onglet “Paramètres du modèle” n’est pas déjà visible.
Dans l’onglet “Paramètres du modèle”, repérez le paramètre “Robots meta default value”.
Modifiez sa valeur
Cliquez sur “Générer” pour créer la documentation finale mise à jour : chaque page HTML contiendra la nouvelle valeur par défaut si elle n’est pas remplacée pour un chapitre spécifique

Grâce au très puissant système de modèles et aux options de personnalisation de HelpNDoc, nous pouvons considérablement personnaliser l’aspect et la convivialité de la documentation HTML générée et l’améliorer à des fins de référencement web (SEO). Vous pouvez télécharger votre copie gratuite de HelpNDoc dès maintenant pour un test personnel aussi longtemps que nécessaire.

Voir aussi

23 Sep 2020

Catégories: articles

Tags: modèles variables de modèle actifs du modèle propriétés du chapitre trucs et astuces