just the docs

Nur die Dokumente

Ein modernes, hochgradig anpassbares und reaktionsfähiges Jekyll-Theme für die Dokumentation mit integrierter Suche.
Einfaches Hosten auf GitHub-Seiten mit wenigen Abhängigkeiten.

Sehen Sie es in Aktion!

Eine Video-Komplettlösung verschiedener Just the Docs-Funktionen

just-the-docs-features-walkthrough.mp4

Installation

Verwenden Sie die Vorlage

Die Just the Docs-Vorlage bietet die einfachste, schnellste und einfachste Möglichkeit, eine neue Website zu erstellen, die das Just the Docs-Design verwendet. Um mit der Erstellung einer Website zu beginnen, klicken Sie einfach auf „Vorlage verwenden“!

Hinweis: Um das Theme zu verwenden, müssen Sie das Just the Docs-Repository nicht klonen oder forken! Sie sollten dies nur tun, wenn Sie beabsichtigen, die Theme-Dokumente lokal zu durchsuchen, zur Entwicklung des Themes beizutragen oder ein neues Theme basierend auf Just the Docs zu entwickeln.

Sie können die mit der Vorlage erstellte Website ganz einfach so einstellen, dass sie auf GitHub Pages veröffentlicht wird. In der README-Datei der Vorlage wird die Vorgehensweise sowie weitere Details erläutert.

Wenn Jekyll auf Ihrem Computer installiert ist, können Sie die erstellte Site auch lokal erstellen und in der Vorschau anzeigen. Auf diese Weise können Sie Änderungen testen, bevor Sie sie festschreiben, und müssen nicht auf GitHub-Seiten warten. ¹ Und Sie können Ihren lokalen Build auf einer anderen Plattform als GitHub Pages bereitstellen.

Genauer gesagt, die erstellte Website:

• verwendet einen Gem-basierten Ansatz, dh verwendet eine Gemfile und lädt den just-the-docs -Gem
• verwendet den GitHub Pages/Aktionen-Workflow, um die Site auf GitHub Pages zu erstellen und zu veröffentlichen

Darüber hinaus steht es Ihnen frei, Websites, die Sie mit der Vorlage erstellen, nach Ihren Wünschen anzupassen. Sie können die Versionen von just-the-docs und Jekyll, die es verwendet, problemlos ändern sowie weitere Plugins hinzufügen.

Verwenden Sie RubyGems

Alternativ können Sie das Theme als Ruby Gem installieren, ohne eine neue Site zu erstellen.

Fügen Sie diese Zeile zur Gemfile Ihrer Jekyll-Site hinzu:

 gem "just-the-docs"

Und fügen Sie diese Zeile zur _config.yml Ihrer Jekyll-Site hinzu:

 theme : just-the-docs

Und dann ausführen:

 $ bundle

Oder installieren Sie es selbst als:

 $ gem install just-the-docs

Alternativ können Sie es während der Entwicklung Ihrer Site in Docker ausführen

 $ docker-compose up

Verwendung

Informationen zur Verwendung finden Sie in der Dokumentation.

Mitwirken

Fehlerberichte, Vorschläge für neue Funktionen und Pull-Requests sind auf GitHub unter https://github.com/just-the-docs/just-the-docs willkommen. Dieses Projekt soll ein sicherer, einladender Raum für die Zusammenarbeit sein, und von den Mitwirkenden wird erwartet, dass sie sich an den Verhaltenskodex der Mitwirkendenvereinbarung halten.

Codeänderungen einreichen:

• Reichen Sie ein Problem ein, das die Änderungen motiviert, und verwenden Sie dabei die entsprechende Vorlage
• Besprechen Sie die vorgeschlagenen Änderungen mit anderen Benutzern und den Betreuern
• Öffnen Sie eine Pull-Anfrage
• Stellen Sie sicher, dass alle CI-Tests bestanden werden
• Geben Sie Anweisungen, um die Auswirkungen der Änderungen zu überprüfen
• Warten Sie auf die Codeüberprüfung

Design- und Entwicklungsprinzipien dieses Themas:

1. Möglichst wenige Abhängigkeiten
2. Kein Build-Skript erforderlich
3. Erstklassiges mobiles Erlebnis
4. Bringen Sie den Inhalt zum Leuchten

Entwicklung

So richten Sie Ihre Umgebung für die Entwicklung dieses Themas ein: Verzweigen Sie dieses Repo und führen Sie die bundle install aus dem Stammverzeichnis aus.

Eine moderne Devcontainer-Konfiguration für VSCode ist enthalten.

Ihr Theme wird genau wie eine normale Jekyll-Site eingerichtet! Um Ihr Theme zu testen, führen Sie bundle exec jekyll serve aus und öffnen Sie Ihren Browser unter http://localhost:4000 . Dadurch wird ein Jekyll-Server gestartet, der Ihr Theme verwendet. Fügen Sie wie gewohnt Seiten, Dokumente, Daten usw. hinzu, um den Inhalt Ihres Themes zu testen. Wenn Sie Änderungen an Ihrem Design und Ihren Inhalten vornehmen, wird Ihre Website neu generiert und Sie sollten die Änderungen nach einer Aktualisierung wie gewohnt im Browser sehen.

Wenn dieses Thema veröffentlicht wird, werden nur die mit Git verfolgten Dateien in _layouts , _includes und _sass in das Gem aufgenommen.

Lizenz

Das Thema ist als Open Source unter den Bedingungen der MIT-Lizenz verfügbar.

Fußnoten

1. Es kann bis zu 10 Minuten dauern, bis Änderungen an Ihrer Website veröffentlicht werden, nachdem Sie die Änderungen an GitHub übertragen haben. ↩