Article original : freeCodeCamp Hashnode Publication Guide – How to Get Started Writing
Comme vous le savez peut-être, la communauté freeCodeCamp a une nouvelle passionnante : nous allons commencer à utiliser le nouveau CMS de Hashnode comme éditeur au lieu de l'éditeur Ghost.
Beaucoup de nos contributeurs ont déjà des comptes Hashnode et y publient régulièrement sur leurs blogs personnels. Mais si vous êtes nouveau sur Hashnode, ce guide vous aidera à commencer.
Et si vous êtes déjà familier avec Hashnode, continuez à lire quand même – il y aura quelques conseils importants que vous devrez connaître pour écrire et soumettre des brouillons pour la publication Hashnode de freeCodeCamp.
Voici ce que nous allons couvrir :
Comment configurer votre compte Hashnode
Comment soumettre des brouillons à l'équipe éditoriale de freeCodeCamp
Comment utiliser l'éditeur Hashnode
Mise en forme du texte dans l'éditeur Hashnode
Autres conseils d'écriture – guide de style de publication de freeCodeCamp
Comment configurer votre compte Hashnode
Pour commencer à écrire sur la nouvelle publication Hashnode de freeCodeCamp, vous aurez besoin d'un compte Hashnode. Si vous n'en avez pas déjà un, vous pouvez vous inscrire gratuitement sur hashnode.com.
Une fois que vous avez un compte, envoyez-nous votre nom d'utilisateur à editorial@freecodecamp.org et nous vous inviterons à la publication.
Vous verrez une notification dans votre profil Hashnode une fois que nous l'aurons fait :
Cliquez dessus et vous verrez alors la publication freeCodeCamp comme l'une de vos publications disponibles.
Ensuite, vous pourrez partager des brouillons avec nous lorsque vous serez prêt.
Quelque chose à garder à l'esprit : si vous avez un profil/nom d'utilisateur Hashnode différent de celui que vous aviez sur Ghost, l'URL de votre profil d'auteur changera. Nous aurons éventuellement des redirections en place, mais cela prendra un certain temps.
En attendant, nous voulons simplement que vous soyez conscient de cela au cas où vous auriez listé cette URL sur votre portfolio personnel, votre CV, etc. Nous apprécions votre patience pendant que nous mettons en place ces redirections.
Comment soumettre des brouillons à l'équipe éditoriale
Lorsque vous configurez votre compte et vous connectez à Hashnode, vous verrez l'écran d'accueil. Cliquez sur "Écrire", et vous serez redirigé vers cette page :
Allez-y et écrivez votre brouillon (ou collez-le depuis un autre éditeur que vous utilisez). Lorsqu'il est prêt à être soumis, vous cliquerez sur le bouton "Publier" en haut à droite. Ensuite, vous verrez l'option de choisir quelle publication – vous devriez voir à la fois votre propre blog et la publication de freeCodeCamp. Sélectionnez la publication de freeCodeCamp.
Hashnode vous demandera si vous souhaitez changer, et si vous le faites, il actualisera la page, passant à la publication de freeCodeCamp.
Ensuite, vous verrez un bouton "Soumettre l'article" en haut à droite. Cliquez dessus.
Mais il y a une étape clé (obligatoire) : vous devez également copier l'URL du brouillon et l'envoyer à editorial@freecodecamp.org. Assurez-vous d'envoyer l'URL du brouillon et non l'URL de l'aperçu – cela nous facilitera grandement l'accès à votre brouillon (car nous pourrons simplement cliquer dessus, plutôt que de chercher dans l'interface Hashnode).
Vous devrez faire cela – c'est-à-dire nous envoyer l'URL du brouillon par e-mail – afin que nous puissions établir une chaîne d'e-mails au cas où nous devrions partager des commentaires et faire des demandes de modification avant la publication.
Note : vous devez envoyer le brouillon à l'équipe éditoriale par e-mail pour que nous puissions le réviser (ainsi que le soumettre via le bouton "Soumettre l'article" de Hashnode). Vous ne pouvez pas simplement cliquer sur le bouton de soumission (ou simplement l'envoyer par e-mail) – les deux étapes sont requises.
Comment utiliser l'éditeur Hashnode
L'éditeur de Hashnode est assez simple à utiliser – et n'est pas si différent de l'éditeur Ghost.
Voici à quoi ressemble la page lorsque vous êtes prêt à écrire :
Lorsque vous écrivez un brouillon dans Hashnode, vous devrez :
Ajouter une image de couverture (vous pouvez créer la vôtre ou en ajouter une depuis un site comme Pexels ou Unsplash). Vous pouvez le faire en cliquant sur "Ajouter une couverture" en haut de la page.
Ajouter un titre d'article (nous n'utilisons généralement pas de sous-titres dans la publication de freeCodeCamp, vous pouvez donc ignorer cela)
Et ensuite vous pouvez commencer à écrire.
Assurez-vous d'ajouter votre image de couverture là où il est indiqué "Ajouter une couverture" en haut de la page. Ne l'ajoutez pas sous l'onglet "Publier" où il y a une option pour ajouter une "Image OG personnalisée". Cela ne s'affichera pas comme une image de couverture.
Une fois que vous avez terminé votre article, assurez-vous de cliquer sur le bouton "Publier". Vous verrez ce menu (vous pourrez faire défiler vers le bas pour plus d'options, dont je parlerai ci-dessous) :
Ensuite, vous devrez :
Sélectionner la publication freeCodeCamp ("Sélectionner un blog")
Vérifier le slug de votre article et vous assurer qu'il est clair et concis (comme javascript-array-tutorial ou learn-python-by-building-projects)
Créer une table des matières si vous souhaitez que votre article en ait une. Si elle fait plus de ~2000 mots, nous vous demandons d'en ajouter une (et c'est à vous de décider si vous incluez une ToC sur les articles plus courts). Notez que la fonction de génération automatique de ToC dans Hashnode ne fonctionnera pas pour notre publication – vous devrez donc créer manuellement la vôtre. Plus d'informations à ce sujet ci-dessous.
Sélectionner et ajouter les tags que vous souhaitez pour votre article. Nous recommandons 3-5 tags, ou selon les besoins.
Enfin, cliquez sur "Soumettre pour révision", puis envoyez l'URL du brouillon à editorial@freecodecamp.org. Encore une fois, les deux sont requis pour que nous puissions accéder et réviser votre brouillon et vous envoyer des commentaires.
Le processus après cela sera assez similaire à notre processus actuel : nous partagerons tout commentaire ou demande de mise à jour, vous ferez vos mises à jour et nous le ferez savoir par e-mail qu'elles sont terminées, et nous ferons notre révision finale et soit demanderons plus de modifications, soit nous publierons l'article.
Notez que l'interface /news restera la même – les lecteurs ne verront pas la différence. C'est juste l'interface back-end/éditeur/expérience d'écriture qui change un peu.
Mise en forme du texte dans l'éditeur Hashnode
Pour accéder aux options de mise en forme du texte, il suffit de taper une barre oblique et un menu assez complet apparaîtra :
Vous pouvez faire défiler vers le bas, cliquer sur les boutons en haut, ou simplement commencer à taper ce que vous cherchez (comme "table", "intégrer un lien" ou "citation" et ainsi de suite) et le menu filtrera les options en conséquence.
Il y a quelques points que nous aimerions souligner qui sont un peu différents de Ghost :
1. Comment ajouter une table des matières à vos articles dans Hashnode
Il y a deux façons d'ajouter une table des matières à votre article : en utilisant un générateur de ToC pratique créé par l'un de nos contributeurs, ou manuellement (que nous décrirons ci-dessous).
Comment utiliser le générateur de ToC
L'un de nos contributeurs a créé ce générateur de table des matières (TOC) freeCodeCamp (merci, Ashutosh !). Il est conçu pour simplifier votre processus d'écriture en générant automatiquement une ToC structurée basée sur les titres de votre brouillon.
Pour commencer, il suffit de coller l'URL de l'aperçu Hashnode de votre article freeCodeCamp dans le champ d'entrée. Vous pouvez obtenir cela en cliquant sur le bouton "Aperçu" dans la zone en haut à droite de votre brouillon, en cliquant sur "Ouvrir dans un nouvel onglet", et en copiant l'URL de l'aperçu de votre brouillon depuis le nouvel onglet.
Vous pouvez également ouvrir le menu des options de brouillon en cliquant sur le bouton de la flèche orientée vers le bas, puis cliquer sur "Copier l'URL de l'aperçu du brouillon" pour copier directement l'URL de l'aperçu dans votre presse-papiers :
Le générateur de ToC fonctionne avec des structures à un seul niveau (titres H2 uniquement) et à plusieurs niveaux (H2 et H3), vous pouvez donc choisir le niveau de détail que vous souhaitez pour votre ToC.
Une fois que vous avez sélectionné le type de ToC et entré le lien de votre article, cliquez sur le bouton "Générer la ToC". La ToC générée apparaîtra dans la boîte de sortie à droite, prête à être copiée et collée directement dans votre article. Les liens dans la ToC correspondront automatiquement aux titres de votre article, facilitant la navigation pour les lecteurs.
Si vous rencontrez des problèmes ou avez des questions, consultez ce guide détaillé pour des instructions supplémentaires sur l'utilisation efficace du générateur de ToC.
Comment ajouter votre ToC manuellement
Si vous préférez ajouter manuellement une ToC à votre brouillon Hashnode, vous devrez suivre un contour pour le moment.
Ce que vous devrez faire, c'est créer la ToC en markdown dans un autre éditeur de votre choix (c'est-à-dire, PAS dans Hashnode) et ensuite la coller dans votre brouillon dans Hashnode.
Ainsi, par exemple, cela ressemblera à ceci :
Voici donc les étapes pour créer la ToC en markdown dans l'éditeur de votre choix (pas Hashnode) avec les titres (et, si nécessaire, les sous-titres) que vous souhaitez inclure dans la ToC :
Ouvrez l'aperçu de l'article (dans Hashnode) en cliquant sur le bouton "Aperçu" dans le coin supérieur droit de la page
Cela vous amènera au mode Aperçu. Faites défiler vers le bas jusqu'à ce que vous voyiez votre premier titre que vous souhaitez inclure.
Ensuite, vous devrez obtenir les ID des titres pour créer les liens internes (comme vous l'avez probablement fait dans Ghost). Il suffit donc d'inspecter chaque titre et de récupérer le texte "ID du titre" dans les outils de développement :
Formatez-le comme ceci : Texte du titre
Donc, encore une fois, cela ressemblera à ceci dans votre autre éditeur de choix :
Ensuite, collez cela directement dans votre brouillon Hashnode là où vous souhaitez que la ToC soit (généralement juste après l'introduction). Cela devrait se formater correctement en texte enrichi dans Hashnode avec les liens internes de la ToC !
Gardez à l'esprit que le générateur automatique ne fonctionne pas pour notre publication – ne basculez donc pas cette option dans les paramètres. Cela ne fera rien.
2. Une note sur le Markdown dans l'éditeur de Hashnode
Pour le moment, vous ne devriez pas écrire directement en markdown dans l'éditeur de Hashnode, car il ne prend pas en charge toutes les fonctionnalités markdown.
Vous pouvez utiliser la mise en forme de base en markdown si vous avez l'habitude d'écrire de cette manière – comme utiliser ## pour les titres, * ou - pour les puces, et ainsi de suite – et l'éditeur les convertira en texte enrichi.
Mais pour l'instant, les liens et les images ne fonctionnent pas en markdown. Donc si vous allez ajouter un lien markdown, par exemple freecodecamp.org, il ne se rendra pas correctement comme un lien dans l'article publié. Il ressemblera simplement à ce que vous avez tapé.
Donc, pour l'instant, utilisez simplement des liens en ligne comme ceci (que vous pouvez faire en surlignant le texte que vous souhaitez lier et en choisissant ensuite le petit symbole de lien dans le menu qui apparaît).
Une note sur les images
En ce qui concerne les images, vous pouvez les glisser-déposer là où vous le souhaitez, ou utiliser le menu / dont nous avons parlé ci-dessus et rechercher "image". Ensuite, vous pouvez télécharger l'image que vous souhaitez utiliser.
Et si vous cherchez un moyen d'ajouter une légende, vous ne la trouverez pas pour le moment. Donc, à la place, ajoutez simplement du texte alternatif à vos images. Vous pouvez le faire en cliquant sur l'image, et vous verrez un menu apparaître. Il y a un "T" majuscule dans ce menu – cliquez dessus et vous pourrez ajouter votre texte alternatif :
Notez que si vous écrivez le markdown ailleurs (dans un autre éditeur de texte) et que vous le collez dans l'éditeur Hashnode, cela devrait fonctionner correctement (y compris les images et les liens). L'éditeur Hashnode convertira le markdown en texte enrichi.
Ajout de tableaux dans l'éditeur Hashnode
Si vous souhaitez inclure un tableau dans votre article, c'est assez facile à faire dans Hashnode. Le générateur de tableaux de l'éditeur est assez bon pour les tableaux simples, et vous pouvez simplement copier et coller des tableaux markdown simples directement dans l'éditeur.
Si vous avez besoin d'un tableau plus complexe – par exemple, un tableau qui nécessite des sauts de ligne ou une liste dans une cellule – il est préférable de mettre le tableau markdown dans un bloc de code. Cela garantira que toute la mise en forme s'affiche correctement.
3. Comment formater les équations mathématiques dans Hashnode
Hashnode utilise un outil appelé MathJax pour ajouter des équations correctement formatées aux articles (vous avez peut-être entendu parler d'outils similaires comme LaTeX ou KaTeX). Vous pouvez lire comment utiliser MathJax sur leur site web ici.
Donc, si vous utilisez des équations mathématiques dans vos tutoriels, veuillez les formater en utilisant MathJax. N'incluez pas de captures d'écran d'équations, car cela n'est pas accessible et ne sera pas lisible par les lecteurs d'écran.
Voici un outil d'aperçu utile pour vos équations MathJax afin que vous puissiez vous assurer qu'elles sont correctes.
Vous devrez également ajouter le tag "MathJax" comme l'un des tags de votre article (faites-en simplement le dernier). Cela permet à l'éditeur d'appliquer le formatage approprié.
Autres conseils d'écriture
Pour des conseils et directives d'écriture plus généraux, vous pouvez toujours vous référer à notre guide de style de publication ici.
Bon écriture !