cortexjs.io

Ce dépôt contient les fichiers source du site Web "Cortexjs.io".

Tl; dr

Première fois après le clonage du projet ou après avoir apporté des modifications à la source

git submodule init

git submodule update

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

Pour mettre à jour la documentation après une nouvelle version

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

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

Pour mettre en scène et déployer une mise à jour

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

Architecture

Le site est publié à l'aide de pages GitHub. Le principal avantage de l'utilisation des pages GH est l'intégration du workflow (Pubshing to GH déclenche une mise à jour automatique du site servi)

Le contenu des sites est rédigé principalement sous forme de fichiers de démarque, traités avec eleventy pour les transformer en HTML / CSS.

La principale configuration eleventy est dans le fichier config/eleventy.js , y compris la définition de la marque à utiliser.

Le moteur Markdown est markdown-it qui implémente Commonmark.

Le plugin mardown-it-attrs permet le style des paragraphes, par exemple

Ceci est un avis. {.NOTICE - INFO}

Le plugin markdown-it-deflist prend en charge les listes de définition de style PANDC:

 Term 1
:   Definition 1
:   Second definition

La sortie est dans le répertoire submodules/cortex-js.github.io . Ce répertoire est un sous-module GIT qui est lié au repo cortex-js.github.io . Ce repo est celui publié par GH Pages (pour l'organisation, seul un repo entier peut être publié, pour les projets, le contenu peut être contenu dans le répertoire A /docs ).

Voir aussi sous-modules.

Le repo cortex-js.github.io doit également inclure deux fichiers supplémentaires:

• .nojekyll qui indique à GitHub qu'il ne devrait pas traiter le contenu de ce dépôt avec Jekyll (car c'est déjà la sortie de Jekyll)
• CNAME avec un contenu de cortexjs.io

Ces fichiers sont créés lors de l'exécution npm run stage .

Utilisez l'onglet Paramètres dans le repo cortex-js.github.io pour indiquer l'utilisation d'un domaine personnalisé.

De plus, les entrées DNS pour cortexjs.io doivent inclure les éléments suivants:

• Un enregistrement CNAME qui pointe vers www.cortex-js.io à cortex-js.io
• Quatre un enregistrement qui pointe vers
  • 185.199.108.153
  • 185.199.109.153
  • 185.199.110.153
  • 185.199.111.153

Contenu

La commande npm run build génère la documentation des API à partir du fichier TypeScript .d.ts dans le répertoire build/ .

Le processus de construction utilise l'outil typedoc pour analyser les fichiers d'en-tête API et sortir un fichier json dans le répertoire build/ .

Remarque: Pour déboguer le convertisseur, utilisez le débogueur VScode. Sélectionnez Debug> Démarrer le débogage pour démarrer une session de débogage directement dans VSCODE.

Le script build-guides convertit ensuite le fichier json en Markdown dans le répertoire ./src/build , qui peut ensuite être traité par Eleventy avec npm run build ou npm start .

Les informations de style CSS sont définies dans src/_sass/ .

La documentation de l'API doit suivre le guide de style de documentation Google (https://developers.google.com/style/api-reference-comments) et https://developers.google.com/style

De plus, le code TypeScript doit suivre le guide de style Google: https://google.github.io/styleguide/jsguide.html#naming

Configuration et scripts

Le projet suit la norme GitHub pour la dénomination des scripts du projet.

Pour faire une construction locale:

npm start

Pour faire une construction prête à être mise en scène:

npm run stage

Test

Le "test" du site généré consiste à vérifier les liens et que le HTML généré est valide.