jigsaw docs template

Modèle de démarrage de Jigsaw Docs

Il s'agit d'un modèle de démarrage permettant de créer un site de documentation magnifique et personnalisable pour votre projet avec un minimum d'effort. Vous n'aurez qu'à modifier quelques paramètres et vous êtes prêt à partir.

Afficher un aperçu du modèle de documents.

Installation

Après avoir installé Jigsaw, exécutez la commande suivante depuis le répertoire de votre projet :

./vendor/bin/jigsaw init docs

Ce modèle de démarrage comprend des exemples de types de pages courants et est préconfiguré avec :

• Une barre de navigation entièrement réactive
• Un menu de navigation dans la barre latérale
• Tailwind CSS, un framework CSS utilitaire qui vous permet de personnaliser votre design sans toucher à une ligne de CSS
• Purgecss pour supprimer les sélecteurs inutilisés de votre CSS, ce qui entraîne des fichiers CSS plus petits
• Mise en évidence de la syntaxe à l'aide de highlight.js
• Un script qui génère automatiquement un fichier sitemap.xml
• Une barre de recherche optimisée par Algolia DocSearch et des instructions pour démarrer avec leur service d'indexation gratuit
• Une page 404 personnalisée

---

---

Configuration de votre nouveau site

Comme pour tous les sites Jigsaw, les paramètres de configuration peuvent être trouvés dans config.php ; vous pouvez mettre à jour les variables de ce fichier avec des paramètres spécifiques à votre projet. Vous pouvez également y ajouter de nouvelles variables de configuration à utiliser sur votre site ; jetez un œil à la documentation de Jigsaw pour en savoir plus.

 // config.php
return [
    ' baseUrl ' => ' https://my-awesome-jigsaw-site.com/ ' ,
    ' production ' => false ,
    ' siteName ' => ' My Site ' ,
    ' siteDescription ' => ' Give your documentation a boost with Jigsaw. ' ,
    ' docsearchApiKey ' => '' ,
    ' docsearchIndexName ' => '' ,
    ' navigation ' => require_once ( ' navigation.php ' ),
];

Astuce : Ce fichier de configuration est également l'endroit où vous définirez les "collections" (par exemple, une collection de contributeurs à votre site ou une collection d'articles de blog). Consultez la documentation officielle de Jigsaw pour en savoir plus.

---

Ajout de contenu

Vous pouvez écrire votre contenu en utilisant différents types de fichiers. Par défaut, ce modèle de démarrage s'attend à ce que votre contenu se trouve dans le dossier source/docs . Si vous modifiez cela, assurez-vous de mettre à jour les références URL dans navigation.php .

La première section de chaque page de contenu contient un en-tête YAML qui spécifie comment elle doit être restituée. L'attribut title est utilisé pour générer dynamiquement title HTML et des balises OpenGraph pour chaque page. L'attribut extends définit la disposition parent Blade avec laquelle ce fichier de contenu sera rendu (par exemple, _layouts.documentation sera rendu avec source/_layouts/documentation.blade.php ), et l'attribut section définit la "section" Blade qui attend que ce contenu soit placé. dedans.

---
title : Navigation
description : Building a navigation menu for your site
extends : _layouts.documentation
section : content
---

En savoir plus sur les mises en page de puzzle.

---

Ajout d'actifs

Tous les actifs qui doivent être compilés (tels que les fichiers JavaScript, Less ou Sass) peuvent être ajoutés au répertoire source/_assets/ , et Laravel Mix les traitera lors de l'exécution npm run dev ou npm run prod . Les actifs traités seront stockés dans /source/assets/build/ (notez qu'il n'y a pas de trait de soulignement sur ce deuxième répertoire assets ).

Ensuite, lorsque Jigsaw créera votre site, l'intégralité du répertoire /source/assets/ contenant vos fichiers créés (et tout autre répertoire contenant des ressources statiques, telles que des images ou des polices, que vous choisissez d'y stocker) sera copié dans les dossiers de construction de destination. ( build_local , sur votre machine locale).

Les fichiers qui ne nécessitent pas de traitement (tels que les images et les polices) peuvent être ajoutés directement à /source/assets/ .

En savoir plus sur la compilation d'actifs dans Jigsaw à l'aide de Laravel Mix.

---

Construire votre site

Maintenant que vous avez modifié vos variables de configuration et que vous savez comment personnaliser vos styles et votre contenu, construisons le site.

 # build static files with Jigsaw
./vendor/bin/jigsaw build

# compile assets with Laravel Mix
# options: dev, prod
npm run dev