jigsaw docs template

Jigsaw Docs Starter-Vorlage

Dies ist eine Einstiegsvorlage zum Erstellen einer schönen, anpassbaren Dokumentationsseite für Ihr Projekt mit minimalem Aufwand. Sie müssen nur ein paar Einstellungen ändern und schon kann es losgehen.

Sehen Sie sich eine Vorschau der Dokumentenvorlage an.

Installation

Führen Sie nach der Installation von Jigsaw den folgenden Befehl in Ihrem Projektverzeichnis aus:

./vendor/bin/jigsaw init docs

Diese Startervorlage enthält Beispiele gängiger Seitentypen und ist vorkonfiguriert mit:

• Eine vollständig responsive Navigationsleiste
• Ein Navigationsmenü in der Seitenleiste
• Tailwind CSS, ein nützliches CSS-Framework, mit dem Sie Ihr Design anpassen können, ohne eine Zeile CSS zu berühren
• Purgecss, um nicht verwendete Selektoren aus Ihrem CSS zu entfernen, was zu kleineren CSS-Dateien führt
• Syntaxhervorhebung mit highlights.js
• Ein Skript, das automatisch eine sitemap.xml Datei generiert
• Eine von Algolia DocSearch betriebene Suchleiste und Anweisungen zum Einstieg in den kostenlosen Indexierungsdienst
• Eine benutzerdefinierte 404-Seite

---

---

Konfigurieren Sie Ihre neue Site

Wie bei allen Jigsaw-Sites finden Sie die Konfigurationseinstellungen in config.php ; Sie können die Variablen in dieser Datei mit projektspezifischen Einstellungen aktualisieren. Sie können dort auch neue Konfigurationsvariablen hinzufügen, die Sie auf Ihrer gesamten Site verwenden können. Schauen Sie sich die Jigsaw-Dokumentation an, um mehr zu erfahren.

 // 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 ' ),
];

Tipp: In dieser Konfigurationsdatei definieren Sie auch alle „Sammlungen“ (z. B. eine Sammlung der Mitwirkenden Ihrer Website oder eine Sammlung von Blogbeiträgen). Weitere Informationen finden Sie in der offiziellen Jigsaw-Dokumentation.

---

Inhalte hinzufügen

Sie können Ihre Inhalte mit verschiedenen Dateitypen schreiben. Standardmäßig erwartet diese Startervorlage, dass sich Ihre Inhalte im Ordner source/docs befinden. Wenn Sie dies ändern, aktualisieren Sie unbedingt die URL-Referenzen in navigation.php .

Der erste Abschnitt jeder Inhaltsseite enthält einen YAML-Header, der angibt, wie er gerendert werden soll. Das title wird verwendet, um HTML- title und OpenGraph-Tags für jede Seite dynamisch zu generieren. Das Attribut „ extends “ definiert, mit welchem ​​übergeordneten Blade-Layout diese Inhaltsdatei gerendert wird (z. B. _layouts.documentation wird mit source/_layouts/documentation.blade.php gerendert), und das Attribut „ section “ definiert den Blade-„Abschnitt“, der die Platzierung dieses Inhalts erwartet hinein.

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

Lesen Sie mehr über Jigsaw-Layouts.

---

Assets hinzufügen

Alle Assets, die kompiliert werden müssen (z. B. JavaScript-, Less- oder Sass-Dateien), können zum Verzeichnis source/_assets/ hinzugefügt werden, und Laravel Mix verarbeitet sie, wenn npm run dev oder npm run prod ausgeführt wird. Die verarbeiteten Assets werden in /source/assets/build/ gespeichert (beachten Sie, dass in diesem zweiten assets -Verzeichnis kein Unterstrich vorhanden ist).

Wenn Jigsaw dann Ihre Site erstellt, wird das gesamte Verzeichnis /source/assets/ mit Ihren erstellten Dateien (und alle anderen Verzeichnisse mit statischen Assets wie Bildern oder Schriftarten, die Sie dort speichern möchten) in die Ziel-Build-Ordner kopiert ( build_local , auf Ihrem lokalen Computer).

Dateien, die keiner Bearbeitung bedürfen (z. B. Bilder und Schriftarten), können direkt zu /source/assets/ hinzugefügt werden.

Lesen Sie mehr über das Kompilieren von Assets in Jigsaw mit Laravel Mix.

---

Erstellen Sie Ihre Website

Nachdem Sie nun Ihre Konfigurationsvariablen bearbeitet haben und wissen, wie Sie Ihre Stile und Inhalte anpassen, beginnen wir mit der Erstellung der Site.

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

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