Créer un site web de documentation

la documentation se présente sous de nombreuses formes vous avez peut être déjà des ressources ou devez commencer à zéro voyons comment ajouter du contenu avec archbee é crivez dans archbee une fois que vous avez créé un nouveau document, vous pouvez commencer à ajouter du contenu en utilisant soit des raccourcis markdown ou l'un des 30+ blocs personnalisés les blocs personnalisés vous aident à formater le contenu comme vous le souhaitez pour les ouvrir, tapez une barre oblique / dans l'éditeur et parcourez les options les blocs sont regroupés sous de base , média , développeur , intégrer , et réutilisation de contenu par exemple, si vous souhaitez lier dynamiquement d'autres documents, tapez @ et le titre du document cela se connectera à l'identifiant du document si vous changez le titre ou la position du document, le lien pointera toujours vers celui ci un autre exemple consiste à appeler le nom du bloc appuyez sur / et tapez le nom du bloc, par exemple, /verticalsplit , ce qui filtrera le bloc que vous souhaitez utiliser la troisième option consiste à utiliser des parenthèses, et le nom du bloc par exemple, (api) ajoutera le bloc de point de terminaison api copier coller les frères du copier coller à l'ancienne mais pourquoi couvrir celui ci ? puisque l'éditeur d'archbee prend en charge markdown, si vous souhaitez coller dans ce format, vous pourriez recevoir le message suivant nous avons détecté du contenu markdown dans votre presse papiers essayez vous de coller du markdown ? si vous cliquez sur le bouton annuler, le contenu ne sera pas rendu, et si vous cliquez sur ok dans la boîte de dialogue, nous convertirons le markdown en blocs d'archbee donc, vous avez un exemple de code qui sera rendu comme un bloc d'éditeur de code dans archbee importer des fichiers markdown ou word le copier coller fonctionne très bien, mais si vous avez des fichiers markdown ou word, pourquoi ne pas les importer dans un espace ? avant d'importer du contenu, assurez vous de cliquer sur l'espace où vous souhaitez importer les fichiers vous venez de cliquer sur le type de fichier que vous avez et économisé des minutes de copier coller depuis d'autres sources importer des fichiers openapi/swagger ou des collections postman lorsqu'il s'agit de documenter des api, vous avez plusieurs options disons que vous utilisez la norme openapi (anciennement swagger) cela permet une importation et une synchronisation faciles des fichiers une fois importé dans archbee, le contenu sera rendu dans une mise en page à 3 colonnes qui permet une documentation facile à gérer synchroniser un dépôt github il se trouve que la documentation est écrite dans un dépôt github, et vous pouvez continuer à écrire dans github et synchroniser le dépôt avec un espace archbee l'avantage est que vous pouvez publier cet espace sur votre domaine personnalisé et ajouter d'autres espaces avec des informations supplémentaires comme des références api configurer le domaine personnalisé et le contrôle d'accès avant de commencer avec le contenu, faites un petit pas qui fera une différence plus tard configurez votre sous domaine pour avoir accès aux environnements de prévisualisation et de production allez à la https //docs archbee com/hosting spaces on a custom domain et suivez les étapes pour ajouter votre domaine personnalisé plusieurs options sont disponibles sous l' général onglet vous pouvez désactiver le indexable par les moteurs de recherche (si public) depuis les mêmes paramètres de l'espace vous souhaitez souvent que cela soit activé afin que les utilisateurs trouvent votre site sur la page de résultats des moteurs de recherche vous pouvez aller à l'option de contrôle d'accès public et choisir l'une des cinq options pour plus de contrôle aucun fait exactement ce que le nom dit, garde vos paramètres concernant l'espace public mot de passe définir un mot de passe pour l'espace tout le monde avec le lien et le mot de passe pourra lire le contenu comptes invités créer des comptes invités tout le monde avec le lien et un compte invité peut lire le contenu les comptes invités ne sont pas facturés comme des sièges dans archbee lien magique vous entrez des e mails spécifiques ou autorisez des noms de domaine entiers, et les utilisateurs s'authentifient en utilisant un lien que nous envoyons à leur adresse e mail ; authentification jwt consultez le https //docs archbee io/authentication options? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 pour savoir comment le configurer c'est une option parfaite si vous ne voulez pas que les utilisateurs se connectent à chaque fois commencez à créer des pages avant d'écrire toute documentation, considérez les principaux sujets que vous allez aborder cette fois, un stylo et du papier pourraient vous aider à dessiner la structure ensuite, créez un document, convertissez le en une catégorie et donnez lui un nom une fois que vous avez cela, vous êtes prêt à ajouter des documents sous chaque catégorie commencez par un document présentant les principales choses qu'un utilisateur trouvera sur le site de documentation cela n'a pas besoin d'être compliqué ; voici comment nous l'avons fait dans notre guide de l'utilisateur et du développeur commencer éditeur documents espaces espaces hébergés organisations importer & exporter intégrations guides api public divers lorsque vous commencez à ajouter du contenu, il est essentiel d'avoir un flux de travail voici un potentiel, mais vous voudrez peut être l'adapter commencez le brouillon dans documents personnels cela vous aidera à écrire tout ce que vous ne souhaitez pas encore partager avec l'équipe lorsque vous êtes prêt, déplacez le document vers l' espace prévenez un coéquipier que le document est prêt et doit être examiné si nécessaire, ajoutez des commentaires en ligne où l'avis d'autres utilisateurs est requis après que vous soyez à l'aise avec les modifications, publiez pour prévisualiser pour voir le site de staging si tout semble bon, cliquez sur publier en production et annoncez que tout est en ligne travailler avec des modèles facilite le travail des contributeurs pour commencer à rédiger du contenu vous pouvez enregistrer un ensemble de modèles pour vous aider à démarrer la production de contenu si vous avez besoin d'inspiration, lorsque vous créez un nouveau document, vous verrez un bouton appelé commencer avec un modèle en bas de la page pour créer vos propres modèles, allez dans la navigation sur le côté gauche, modèles, et commencez à créer des documents avec la structure dont vos documents ont besoin vous pouvez également introduire les blocs personnalisés que l'auteur utilisera ou ajouter des exemples d'autres sources liens permanents et paramètres seo ces options sont au niveau du document donc, vous devez cliquer sur les trois points ⋮ en haut à droite et choisir contrôles meta seo ajoutez un titre , changez l' url , écrivez une description meta ou téléchargez une image pour les aperçus personnalisez et marquez votre site de documentation dans l' apparence onglet, vous trouverez les options de mise en forme comme couleur d'accent , logo , et favicon , ainsi que d'autres options pour le modèle créez un menu de navigation avec des versions multiproduits ou produit selon le type de produits ou de services, vous pourriez vouloir avoir différents chemins d'url d'espace vous pouvez avoir un espace comme documentation principale et créer différents espaces pour d'autres produits ou même leurs versions il y a un raccourci ! vous pouvez créer un clone de n'importe quel espace si les changements sont incrémentaux cela vous aidera à garder la structure et à faire les modifications pour la nouvelle version donc, si la gestion des versions et le multiproduit sont quelque chose dont vous avez besoin, utilisez des espaces différents et ajoutez le avec le chemin pertinent ou un domaine personnalisé allez à https //docs archbee com/space links et commencez à construire votre navigation créer une page d'atterrissage l'objectif principal de la page d'accueil est d'aider le visiteur à aller à la page suivante construire une page d'atterrissage pour votre site de documentation ne doit pas suivre les mêmes pratiques qu'un site de présentation la première page du document est importante pour présenter votre produit ou service aux utilisateurs, donc la garder courte et définir les attentes est essentiel vous pouvez utiliser la https //docs archbee io/custom landing page? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 fonctionnalité et ajoutez votre html pour plus de contrôle sur la première page il existe de nombreuses options pour s'inspirer, et si vous souhaitez changer l'apparence de la première page, c'est votre option voici comment l'un de nos clients a construit sa page de démarrage pour sa page d'aide ajouter du code personnalisé utilisez https //docs archbee io/custom css? hstc=59513074 901e138137246d5bde4ccdbd22c4c426 1657529807386 1664186053341 1664199496535 118& hssc=59513074 7 1664199496535& hsfp=13091307 si vous souhaitez ajouter votre propre style style au site de documentation si vous êtes familier avec les classes css, vous trouverez quelques ab de départ et vous pourrez les cibler