Bienvenue sur la page Github du site web Mes cours de maths ! Il s'agit d'un petit site web où je dépose tous mes cours de mathématiques ainsi que les ressources qui y sont liées.
Ce site est totalement open-source : vous pouvez tout à fait en exécuter une instance personnelle. Pour cela, suivez le guide ci-dessous.
Il est totalement possible pour vous de cloner le projet pour l'utiliser vous aussi ! Pour cela, suivez le guide ci-dessous. Attention, des connaissances en NodeJS (notamment) sont requises.
Sur Github, il va falloir créer une application OAUTH. Pour cela, rendez-vous sur ce lien.
- Dans
Application name
, mettez ce que vous souhaitez. - Dans
Homepage URL
, mettez l'URL de votre site web. - Dans
Authorization callback URL
, mettez l'URL de votre API hébergée sur Vercel. Se référer à [https://docs.github.com/en/developers/apps/building-oauth-apps/authorizing-oauth-apps#redirect-urls](ce lien) pour le dernier champ.
Par la suite, notez votre Client ID
quelque-part et générez un nouveau Client secret
. Copiez-le aussi
et ne le perdez surtout pas. Nous en aurons également besoin plus tard.
Il vous suffit de cliquer ici pour cloner le projet. Cela créera un nouveau dépôt sur Github où vous pourrez configurer votre nouveau site web.
Dans les paramètres de votre dépôt Github, il va falloir créer deux secrets :
CLIENT_SECRET
, qui doit contenir votreClient secret
.PERSONAL_ACCESS_TOKEN
, qui contient votrePersonal access token
créé précédemment. Cette étape est requise uniquement si vous utilisez un dépôt séparé pour héberger vos données.
Pour configurer le site web (nom, dépôt Github, répertoire des cours, etc.), il vous faut modifier le
fichier site/authentication.ts
. Indiquez votre Client ID
dans le champ clientId
(j'ai personnellement choisi de le laisser dans la variable d'environnement CLIENT_ID
, mais c'est à vous de voir).
Pour modifier le contenu de la page d'accueil, il faut éditer le fichier pages/index.vue
.
Une façon plus rapide (et intuitive...) de modifier les pages sera sûrement ajoutée à l'avenir.
Vous pouvez également modifier la plupart des paramètres dans le fichier site/content.js
. Ceci vous permettra
de personnaliser les fichiers à compiler en PDF, à transformer en markdown, où se situent les images, etc.
Le fichier site/levels.ts
contient les différents niveaux disponibles. Chacun d'eux doit posséder un sous-dossier
dans votre répertoire LaTeX.
Cette étape est optionnelle : vous pouvez parfaitement vous servir du même dépôt que le site web
pour y stocker vos données LaTeX. Pour cela, dans site/meta.js
, laissez dataRepository
à la même valeur que repository
.
Si vous souhaitez utiliser un dépôt séparé (par exemple, afin de garder les sources LaTeX privées ; ou tout
simplement pour séparer le contenu de sa présentation), créez-en un sur Github et indiquez sa valeur dans
dataRepository
. Celui-ci doit contenir le lessonsDirectory
.
Si votre dépôt est privé, nous allons devoir créer un Personal access token
. Pour cela rendez-vous sur
ce lien. Nommez-le comme vous souhaitez et cochez la case repo
.
Notez quelque-part le jeton que vous obtenez.
Vos fichiers LaTeX peuvent être structurés comme vous le souhaitez, du moment qu'ils sont interprétables par KaTeX. Ceux-ci doivent tout de même définir deux environnements :
doctitle
qui doit correspondre au titre de votre document.docnumber
qui peut correspondre à un numéro de chapitre par exemple.
Afin d'être compilables par Pandoc, vous pouvez créer un fichier pandoc.tex
,
à placer dans le lessonsDirectory
. Voici par exemple le contenu du mien :
% Ceci me permet de remplacer ma commande \cours dans mes fichiers LaTeX.
\providecommand{\cours}[3]{%
\begin{doctitle}%
#2%
\end{doctitle}%
}
% Et ceci me permet de remplacer ma commande \chapitrenumero dans mes fichiers LaTeX.
\providecommand{\chapitrenumero}[1]{%
\begin{docnumber}%
#1%
\end{docnumber}%
}
Afin que l'accès enseignant soit fonctionnel, nous avons encore besoin de créer un projet sur Vercel. Inscrivez-vous si ce n'est pas déjà fait et créez un nouveau projet à partir du dépôt Github cloné.
Une fois créé, nous allons devoir ajouter deux variables d'environnements (dans les paramètres du projet Vercel) :
GITHUB_CLIENT_SECRET
, qui contient votreClient secret
.ENCRYPTION_KEY
, qui contient 32 caractères générés de manière aléatoire (majuscules, minuscules et chiffres uniquement).
Dans les paramètres généraux, inscrivez npx nuxi dev ../
en commande de développement et vercel/
en répertoire racine.
Le domaine spécifié dans Domains doit correspondre avec l'apiUrl
du fichier site/meta.js
.
Enfin, pour éviter des builds inutiles, écrivez par exemple
if [[ "$VERCEL_GIT_COMMIT_REF" == "master" ]] ; then echo "✅ Ref is 'master'. The build can proceed !"; exit 1; else echo "🛑 Ref is not 'master'. Cancelling build..."; exit 0; fi
dans la section Ignored Build Step de l'onglet Git.
N'oubliez pas de modifier également le fichier vercel/index.html
.
Pour tester localement votre site web, une commande suffit : npm run vercel
. Il vous faut également
créer un fichier .env
contenant toutes variables d'environnement listées précédemment.
Si vous souhaitez tester le site en local avec toutes les fonctionnalités, il faudra également adapter les variables d'environnement ajoutées sur Vercel (en spécifiant bien lesquelles doivent être utilisées en production, et lesquelles doivent l'être en développement).
Il faut également ajouter une variable d'environnement de développement intitulée DEBUG_MODE
et contenant la valeur true
.
Voici un aperçu des mes variables d'environnement :