Find the English version below (click here)
MuseumXTD est une plateforme de ressources évolutive. Plus d’information sur https://www.museumxtd.ch/
Vous trouverez ci-dessous la procédure pour modifier ses contenus.
La procédure que nous recommandons nécessite l'installation de deux logiciels (voir la section 1. Pour commencer):
- Le logiciel de prise de note Obsidian pour éditer le contenu
- L'application desktop GitHub pour héberger les pages
Après l'installation des logiciels, vous pourrez modifier les contenus en trois étapes (voir la section 2. Modifier les contenus du site internet):
- Récupérer la dernière version du site web (et éviter de travailler sur une version obsolète) grâce l'application desktop GitHub
- Ajouter et modifier les fichiers grâce au logiciel Obsidian
- Mettre le site web à jour avec les changements que vous avez effectués grâce à l'application desktop GitHub
Vous n'êtes pas familiers avec ces outils? Voir notre page Les outils utilisés par MuseumXTD.
- 1. Pour commencer
- 2. Modifier les contenus du site internet
- 3. Configuration avancée avec Obsidian Git
- 4. Développement et design
Ce dont vous allez avoir besoin:
- Un compte GitHub
- L'autorisation d'accéder au dépôt museumXTD (en envoyant votre login GitHub à [email protected])
- Le logiciel Obsidian et l'application Desktop GitHub (voir les étapes d'installation ci-dessous)
Cette application vous permettra de télécharger et d'envoyer le contenu du site Web entre GitHub et votre ordinateur. Allez sur la page GitHub Desktop, téléchargez et installez l'application sur votre ordinateur.
Ouvrez GitHub Desktop et connectez-vous avec votre compte GitHub.
- Windows : menu Fichier > Options. Dans la fenêtre des options, cliquez sur Comptes et suivez les étapes pour vous connecter.
- MacOS : menu GitHub Desktop > Préférences. Dans la fenêtre des préférences, cliquez sur Comptes et suivez les étapes pour vous connecter.
- Allez sur la page GitHub de MuseumXTD
- Cliquez sur le bouton Code (capture d'écran ci-dessous)
- Copiez l'URL à partir du menu déroulant
- Ouvrez l'application GitHub Desktop (connectez-vous si vous ne l'avez pas déjà fait)
- Allez dans le menu File > Clone repository. Cliquez sur l'onglet URL et collez dans le champ nommé Repository URL or GitHub username and repository (capture d'écran ci-dessous)
- Cliquez sur le bouton Clone
GitHub Desktop va créer un nouveau dossier appelé museumXTD à l'intérieur de votre dossier Documents > GitHub qui contient tous les fichiers du projet.
Obsidian est un logiciel de prise de notes, grâce auquel vous pouvez créer des pages (notes) et les lier entre elles. Des instructions sur la façon d'installer cet outil se trouvent sur le Obsidian-website.
Ouvrez Obsidian, et allez dans le menu File > Open vault... puis dans la fenêtre cliquez sur Open folder as vault et sélectionnez le dossier museumXTD que vous avez créé dans les étapes ci-dessus (par défaut dans documents > GitHub).
Avant d'effectuer des modifications, assurez-vous que vous disposez de la dernière version du contenu.
- Dans le bureau GitHub, vérifiez que la branche actuelle est
main. - Cliquez sur Fetch Origin.
Une fois que la mise à jour est assurée, vous pouvez modifier les fichiers directement depuis le logiciel Obsidian. Attention: seuls les fichiers enregistrés dans le dossier Notes dans Obsidian seront publiés sur le site web. Par défaut, les notes créées se placent directement dans le dossier Notes.
Pour que votre note soit publiée sur le site, vous devez ajouter une section spéciale en haut: les métadonnées. Cela ajoutera le menu, la mise en page et les couleurs au contenu.
Pour les ajouter, deux solutions se présentent:
- Ajouter les métadonnées à la main, entre deux lignes de tirets ('---')
- Ajouter les via un modèle prédéfini: Menu de gauche > Insérer le modèle > Métadonnées Notes(seulement les métadonnées) OU Note ressource (pour créer une note ressource) OU Note question (pour créer une note question)
Les champs des métadonnées:
- title Le texte qui sera affiché dans l'onglet du navigateur.
- layout Une option pour changer le style de la page web, par défaut, utilisez
layouts/post.njk. - tags Permet de rassembler des ressources similaires. Voir la liste dans la page [[Tags]].
- alias Permet d'associer un titre différent à la note (cette balise est utile pour ajouter des caractères spéciaux, non permis par Obsidian, dans le titre).
- eleventyNavigation Permet de définir le fil d'Ariane associé à la note et qui s'affichera sur le site
- key Identifiant de la note
- title Titre visible dans le fil d'Ariane sur le site
- parent Identifiant de la note qui précédente la note actuelle dans le fil d'Ariane
Ci-dessous un exemple d'en-tête.
---
title: MuseumXTD
layout: layouts/post.njk
tags: question
alias: [Quels sont les opportunités et les freins?]
eleventyNavigation:
key: opportunités
title: Quels sont les opportunités et les freins?
parent: comprendre
---
-
Pour ajouter et/ou modifier du contenu dans l'onglet Ressources, lisez cette page Notes question et ressource
-
Pour ajouter et/ou modifier du contenu dans l'onglet Répertoire :
Veuillez modifier directement la page tables si vous voulez modifier les textes de la page
Veuillez suivre le tutoriel Tableau Acteurs et Projets si vous souhaitez ajouter des références dans la base de données
Toutes les images doivent être stockées dans le dossier racine images. Pour ajouter une image dans un fichier MD, veuillez écrire , avec:
[légende de l'image]la légende que vous voulez associé(/images/nameFile.png)l'adresse où se trouve l'image
Ouvrez l'application GitHub Desktop:
- Rédigez un résumé de vos modifications
- Cliquez sur le bouton Commit
- Cliquez sur Push origin
Cette dernière étape permet de télécharger vos modifications sur GitHub. Une fois en ligne, vos notes seront transformées en pages web (de .md à .html). Il y aura un délai de quelques minutes avant qu'elles ne soient visibles en ligne Museumxtd.ch
Tout d'abord, nous devons cloner le dépôt sur notre machine Windows locale depuis GitHub. Pour ce faire, nous installons 'git'. Rendez-vous sur le site git-for-windows et suivez les instructions simples d'installation. Vous devrez avoir votre compte GitHub ajouté au dépôt par l'administrateur pour pouvoir déposer de nouveaux commits.
- Définissez votre adresse e-mail et votre nom d'utilisateur git
git config --global user.email "[email protected]" git config --global user.name "YOUR USER NAME"
- Ouvrez un terminal en appuyant sur la touche windows et en tapant terminal ou commande. Sélectionnez l'application terminal dans la liste des programmes. Le terminal s'ouvre à l'emplacement par défaut : C:/Utilisateurs/XXXXX
- Enregistrez le dossier à l'endroit où vous voulez stocker le projet. Par exemple enregistrez-le dans vos Documents et clonez le projet. Exemple ci-dessous:
cd .\Documents\ git clone https://github.com/MediaComem/museumXTD.git
Vous verrez un nouveau dossier appelé museumXTD à l'intérieur de votre dossier Documents qui contient tous les fichiers du projet.
Si vous souhaitez visualiser les fichiers Markdown des projets et apporter des modifications ou ajouter du nouveau contenu, vous pouvez le faire via Obsidian. Il y a des instructions sur le Obsidian-website sur la façon d'installer cet outil. Une fois cela fait, vous pouvez sélectionner Ouvrir le dossier en tant que coffre-fort et sélectionner le projet récemment cloné museumXTD qui a été créé dans votre dossier de documents dans les étapes ci-dessus.
3.4. Configurer Obsidian pour qu'il se synchronise automatiquement avec GitHub afin de récupérer les dernières modifications et de pousser le nouveau contenu
Ouvrez l'onglet paramètres sur Obsidian et sélectionnez Plugins communautaires. Ensuite, désactivez le mode sans échec et recherchez et installez le plugin Obsidian Git. Comme vous avez cloné le projet museumXTD depuis GitHub, Obsidian Git le verra automatiquement comme un projet git, vous donnant accès à ses commandes natives pour tirer ou pousser des changements. Veuillez lire le guide pour comprendre les différents paramètres qui vous sont proposés.
Actuellement, l'un des éléments de menu sur Obsidian est Ouvrir la palette de commande. Ici, vous pouvez entrer les commandes Git d'Obsidian pour enregistrer les changements et les télécharger vers le dépôt GitHub.
- Pull Cette commande est automatiquement déclenchée lorsque vous ouvrez le projet avec Obsidian. Cependant, c'est une bonne pratique de tirer du dépôt juste avant de commettre des changements au cas où il y aurait d'autres changements récents que vous auriez manqués.
- Liste des fichiers modifiés** Avant de livrer vos changements, vous pouvez voir une liste de tous les fichiers qui ont été modifiés pour vérifier et ne pas pousser des changements non désirés par erreur.
- Open source control view Si vous voulez inspecter chaque changement de fichier ligne par ligne, vous pouvez utiliser cette commande pour comparer avant (rouge) et après (vert).
- Commit all changes Cette commande ajoutera vos modifications à la zone de transit git et effectuera ensuite un commit. Il y a un message standard par défaut attaché à la livraison. Habituellement quelque chose comme vault backup : YYYY-MM-DD hh:mm:ss Cependant Je conseille de le changer pour inclure votre nom afin que votre équipe puisse suivre dans l'historique des logs qui fait quels changements. Sous
Obsidian settings, Community plugins, Obsidian Git, options, ici il y a le champ Commit message on manual backup/commit. Vous pouvez entrer votre message personnalisé ici qui apparaîtra sur chaque commit par la suite. - Push Enfin, une fois que vous avez fait votre commit, vous pouvez pousser vos changements vers le dépôt GitHub. Cela devrait déclencher une construction pour publier la nouvelle version sur GitHub-pages. Notez que les changements peuvent prendre quelques instants pour prendre effet sur le serveur en direct et que vous devrez peut-être vider le cache de votre navigateur si la page est déjà chargée. Vous pouvez également afficher le site web en mode incognito chrome ou fenêtre privée Edge afin de ne pas utiliser d'anciens cookies ou cache.
- installation de Node Le site officiel Node-website donne des instructions sur la façon d'installer Node.
Vous pouvez exécuter le projet localement en téléchargeant d'abord les paquets requis npm ci à partir du package-lock.json et en exécutant ensuite npm run start. Cela va construire les fichiers du projet et les stocker dans le dossier docs. Ensuite, Eleventy va servir ce dossier docs sur votre hôte local pour le visualiser sur votre navigateur Local : http://localhost:8080.
4.2. Mise à jour manuelle des modifications sur le serveur d'hébergement en direct sur les pages GitHub
Lorsque vous avez validé vos changements locaux avec git add et git commit -m "enter message here" et poussé vers la branche main de GitHub git push origin main, qui contient le fichier eleventy_build.yml, cela va déclencher une construction du projet sur GitHub et pousser les fichiers créés vers le dossier docs. Ensuite, ce dossier, qui contiendra le build Eleventy, est poussé vers la branche gh-pages. Cette branche sera automatiquement mise à jour sur l'hôte live dans quelques instants.
Si vous souhaitez appliquer une autre mise en page à votre fichier MD (layout), vous pouvez faire référence à son nom de fichier. Veillez à enregistrer votre nouveau fichier de mise en page dans le bon dossier layouts et à utiliser la bonne syntaxe. Le contenu de votre fichier MD sera rendu à l'endroit où vous avez ajouté la ligne suivante {{ content | safe }} dans votre nouveau fichier .njk
MuseumXTD is an evolving resource platform for understanding the digital transition for small and medium-sized museums through reflections, examples and freely accessible Swiss and international tools. More information on https://www.museumxtd.ch/
Below you will find the process for modifying its contents.
To follow this process, the installation of two softwares (see part 1. Getting started) is required:
- Obsidian, a note-taking software that will allow you to edit the content
- The desktop app GitHub, that will host the web pages
Once the softwares have been installed, you will need to follow three steps to modify the content (see part 2. Editing the content):
- Fetch the latest version of the website with the GitHub Desktop app (and avoid to work with an obsolete version)
- Edit and change the files in the Obsidian app
- Push the changes to update the website with the GitHub Desktop app
Not familiar with these tools? Let's discover how we have used them here.
- 1. Getting started
- 2. Editing the content
- 3. Advanced setup with Obsidian Git (alternative)
- 4. Developpement and design
What you will need
- A GitHub account
- Permission to access the repository (send your GitHub user name to [email protected])
- Obsidian and GitHub Desktop app. See install steps bellow.
This app will let you download and upload the website's content between GitHub and your computer. Go to the GitHub Desktop page, download and install the app on your computer.
Open GitHub Desktop and sign-in with your GitHub account.
- Windows: menu File > Options. In the options window, click Accounts and follow the steps to sign in.
- MacOS: menu GitHub Desktop > Preferences. In the preference window, click Accounts and follow the steps to sign in.
- Go to the MuseumXTD GitHub page.
- Click the Code button (screenshot bellow)
- Copy the URL from the pop-up menu.
- Open the GitHub Desktop app (Sign-in if you didn't already)
- Go to menu File > Clone repository. Click on the URL tab and paste in the field named Repository URL or GitHub username and repository. (screenshot bellow)
- Click the Clone button
GitHub Desktop will create a new folder called museumXTD inside of your Documents > GitHub folder which contains all the project files.
Obsidian is where you can create pages (notes) and link between them. There are instructions on the Obsidian-website on how to install this tool.
Open Obsidian, and go to menu File > Open vault... then in the window click Open folder as vault and select the museumXTD folder you created in the steps above (by default in documents > GitHub).
[
Before making changes, make sure you have the latest version of the content.
- In GitHub Desktop check that under Current Branch is
main - Click Fetch Origin
Please also read our editing guidelines in "Comment participer sur la plateforme" folder.
Once you have fetched the latest version of the website, you can modify and edit the files thanks to Obsidian. Be aware that only the files saved to the Notes folder will be published on the website. By default, the new notes are created directly in the Notes folder.
In order for your note to be published on the site, you need to add a special section at the top: the metadata. This will add the menu, layout and colours to the content.
There are two ways to add them:
- Add the metadata by hand, between two lines of dashes ('---')
- Add them thanks to a template: Left menu > Insert template > Métadonnées Notes (only metadata) OR Note ressource (to create a resource note) OR Note question (to create a question note)
Metadata fields:
- title The text that will be displayed in browser tab.
- layout An option to change the style of the webpage, by default use
layouts/post.njk - tags For organising your work in Obsidian and for the website Search function. See the list in the [[Tags]] page.
- alias Allows you to associate a different title to the note (this tag is useful for adding special characters, not allowed by Obsidian, in the title).
- eleventyNavigation Allows you to define the breadcrumb trail associated with the note and which will be displayed on the site
- key Note identifier
- title Title visible in the breadcrumb trail on the site
- parent Identifier of the note that precedes the current note in the breadcrumb trail
Below is an example of the standard header to start a page with.
---
title: MuseumXTD
layout: layouts/post.njk
tags: question
alias: [Quels sont les opportunités et les freins?]
eleventyNavigation:
key: opportunités
title: Quels sont les opportunités et les freins?
parent: comprendre
---
-
To add and/or edit content in the Ressources tab, read this note Notes question et ressource (written in French)
-
To add and/or edit content in the Répertoire tab:
Please go to tables (written in French) if you want to modify the texts on the page
Please follow the tutorial Tableau Acteurs et Projets (written in French) if you want to add references to the database
All images are to be stored in the root images folder. To add an image to an MD file, write , with:
[image description]the description you want associated(/images/nameFile.png)the address where the image is located
Open the GitHub Desktop app:
- Write a summary about your changes
- Click on the Commit button
- Click on Push origin
This last step will upload your changes to GitHub. Once online, your notes will be processed into web pages (from .md to .html). There will be a delay of a few minutes before they are visible online Museumxtd.ch
First we need to clone the repository to our local windows machine from GitHub. We do that by installing 'git'. Please go to the git-for-windows website and follow the simple instructions to install. You will need to have your GitHub account added to the repository by the admin to be able to pust new commits.
- Set your git email address and username
git config --global user.email "[email protected]" git config --global user.name "YOUR USER NAME"
- Open a terminal by pressing the windows key and start typing terminal. Select the terminal app from the programs list. The Terminal will open under the default location: C:/Users/XXXXX
- Change directory to where you want to store the project. For example under your main documents folder and clone the project. Example below:
cd .\Documents\ git clone https://github.com/MediaComem/museumXTD.git
You will see a new folder called museumXTD inside of your Documents folder which contains all the project files.
If you wish to view the projects Markdown files and make changes or add new content you can do this via Obsidian. There are instructions on the Obsidian-website on how to install this tool. Once done you can select Open folder as vault and select the recently cloned project museumXTD which was created in your documents folder in the steps above.
3.4. Configuring Obsidian to automatically sync with GitHub to pull latest changes and to push new content
Open the settings tab on Obsidian and select Community plugins. Next turn off safe mode and search for and install the plugin Obsidian Git. As you cloned the museumXTD project from GitHub, Obsidian Git will automatically see it as a git project giving you access to its native commands to pull or push changes. Please read the guide material to understand the different settings available to you.
Currently one of the menu items on Obsidian is Open command palette. Here you can enter the Obsidian Git commands to save changes and upload them to the GitHub repository.
- Pull This command is automatically triggered when you open the project with Obsidian. However it is good practice to pull from the repository just before you commit any changes in case there are some other recent changes which you are missing.
- List changed files Before you commit your changes you can view a list of all the files that have been changed to verify and not to push unwanted changes by mistake.
- Open source control view If you want to inspect each file change line by line you can use this command to compare before (red) and after (green).
- commit all changes This command will add your changes to the git staging area and then perform a commit. There is a standard default message attached to the commit. Usually something like vault backup: YYYY-MM-DD hh:mm:ss However I advise to change this to include your name so your team can track in the logs history who is doing what changes. Under
Obsidian settings, Community plugins, Obsidian Git, options, here there is the field Commit message on manual backup/commit. You can enter your custom message here that will appear on every commit thereafter. - Push Finally once you made your commit you can push your changes to the GitHub repository. This should trigger a build to publish the new version to GitHub-pages. Note it can take a few moments for the changes to take effect on the live server and you may need to clear cache on your browser if the page is already loaded. You can also view the website in incognito mode chrome or InPrivate window Edge so not to use any old cookies or cache.
- install Node The official Node-website give instructions on how to install node.
You can run the project locally by first downloading the required packages npm ci from the package-lock.json and then running npm run start. This will build the project files and store them on the docs folder. Next Eleventy will serve this docs folder on your local host to view on your browser Local: http://localhost:8080
When you have committed your local changes with git add and git commit -m "enter message here" and pushed to the GitHub branch main git push origin main, which has the eleventy_build.yml file, this will trigger a build of the project on GitHub and push the created files to the docs folder. Next this folder, which will contain the Eleventy build, is pushed to the gh-pages branch. This branch will automatically update on the live host in a few moments.
If you wish to apply another layout to your MD file you can reference it's file name instead. Be sure to save your new layout file in the right folder layouts and have the correct syntax. Your MD file content will be rendered where you have added the following line {{ content | safe }} on your new .njk file.