cortexjs.io

Dieses Repo enthält die Quelldateien für die Website "Cortexjs.io".

Tl; dr

Zum ersten Mal nach dem Klonen des Projekts oder nach Änderungen der Quelle

git submodule init

git submodule update

# Setup, make a dev build and start a server
npm start

So aktualisieren Sie die Dokumentation nach einer neuen Version

 # Pick-up changes in the dependent modules
npm run update

# Generate .md files for API and launch local server
npm start

Ein Update zu inszenieren und bereitzustellen

npm run stage
# Make a clean production build.
# Output goes inside submodules/cortex-js.github.io

npm run restart
# Validate that everything works well in the browser then...

npm run deploy
# submodules/cortex-js.github.io (a git submodule) gets pushed to cortex-js.github.io

Architektur

Die Website wird mit Github -Seiten veröffentlicht. Der Hauptvorteil bei der Verwendung von GH -Seiten ist die Workflow -Integration (Pubshing zu GH löst eine automatische Aktualisierung der zu servierten Site aus)

Der Inhalt der Websites wird hauptsächlich als Markdown -Dateien verfasst, die mit eleventy verarbeitet werden, um sie in HTML/CSS zu verwandeln.

Die Hauptkonfiguration in der eleventy befindet sich in der Datei config/eleventy.js , einschließlich der Definition des zu verwendenden Markas.

Die Markdown-Engine ist markdown-it die Commonmark implementiert.

Das mardown-it-attrs -Plugin ermöglicht das Styling von Absätzen, z. B.

Dies ist eine Mitteilung. {.notice-Info}

Das markdown-it-deflist Plugin unterstützt die Definition von PANDC-Stillisten:

 Term 1
:   Definition 1
:   Second definition

Der Ausgang befindet sich im Verzeichnis submodules/cortex-js.github.io . Dieses Verzeichnis ist ein Git- Submodul , das mit dem cortex-js.github.io Repo verknüpft ist. Dass Repo das von GH -Seiten veröffentlicht ist (für die Organisation kann nur ein ganzes Repo veröffentlicht werden. Für Projekte kann der Inhalt im A /docs -Verzeichnis enthalten sein).

Siehe auch Submodules.

Das Repo cortex-js.github.io muss auch zwei zusätzliche Dateien enthalten:

• .nojekyll , was GitHub angibt, dass es den Inhalt dieses Repo nicht mit Jekyll verarbeiten sollte (da dies bereits die Ausgabe von Jekyll ist)
• CNAME mit einem Inhalt von cortexjs.io

Diese Dateien werden beim Ausführen npm run stage erstellt.

Verwenden Sie die Registerkarte Einstellungen im Repo cortex-js.github.io , um die Verwendung einer benutzerdefinierten Domäne anzugeben.

Darüber hinaus müssen die DNS -Einträge für cortexjs.io Folgendes enthalten:

• Ein CNAME-Datensatz, der auf www.cortex-js.io auf cortex-js.io hinweist
• Vier A -Aufzeichnungen, auf die hingewiesen wird
  • 185.199.108.153
  • 185.199.109.153
  • 185.199.110.153
  • 185.199.111.153

Inhalt

Der Befehl npm run build generiert die dokumentation für die apis aus der typecript .d.ts -Datei in das build/ Verzeichnis.

Der Build -Prozess verwendet das typedoc -Tool, um die API -Header -Dateien zu analysieren und eine json -Dateien im build/ Verzeichnis auszugeben.

Hinweis: Verwenden Sie den VSCODE -Debugger, um den Konverter zu debuggen. Wählen Sie Debugg> Debugging aus, um eine Debugging -Sitzung direkt in VSCODE zu starten.

Das Skript build-guides wandelt dann die json Datei im Verzeichnis ./src/build in Markdown um, das dann mit elf ELTY mit npm run build oder npm start verarbeitet werden kann.

Die CSS -Styling -Informationen sind in src/_sass/ definiert.

Die API-Dokumentation sollte dem Google-Dokumentationsstil-Handbuch (https://developers.google.com/style/api-Reference-comments) und https://developers.google.com/style folgen

Darüber hinaus sollte der TypeScript -Code dem Google -Style -Handbuch folgen: https://google.github.io/styleguide/jsguide.html#naming

Setup und Skripte

Das Projekt folgt dem GitHub -Standard für die Benennung von Projektskripten.

Einen lokalen Build durchführen:

npm start

Um einen Build durchzuführen, um inszeniert zu werden:

npm run stage

Prüfen

Das "Testen" der generierten Site besteht aus der Überprüfung von Links und dass das generierte HTML gültig ist.