From d0de5799ae3a5aa472be537cd157c2c7a292eec9 Mon Sep 17 00:00:00 2001 From: fpasquet Date: Thu, 7 Nov 2024 09:27:58 +0100 Subject: [PATCH] feat: add docs no techs --- README.md | 283 +---------------------------- documentations/setup-for-dev.md | 281 ++++++++++++++++++++++++++++ documentations/setup-for-others.md | 118 ++++++++++++ 3 files changed, 402 insertions(+), 280 deletions(-) create mode 100644 documentations/setup-for-dev.md create mode 100644 documentations/setup-for-others.md diff --git a/README.md b/README.md index 17a2e1a16..cab30b065 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ Blog Eleven Labs =================== -Welcome to the [ElevenLabs] blog (https://blog.eleven-labs.com), this is a [Jamstack](https://jamstack.org/) website. +Welcome to the **Eleven Labs** [blog](https://blog.eleven-labs.com), this is a [Jamstack](https://jamstack.org/) website. ---------- @@ -19,282 +19,5 @@ It uses Eleven Labs [Design System](https://github.com/eleven-labs/design-system Setting up the blog ------------- -**Technical requirements** -- [TypeScript](https://www.typescriptlang.org/) -- [React](https://reactjs.org/) -- [React Router](https://reactrouter.com/en/main) -- [Vite](https://vitejs.dev/) -- [Storybook](https://storybook.js.org/) - -**Computer requirements** - -- [git](https://git-scm.com/download/linux) - -For local installation: -- [Node Version Manager](https://github.com/nvm-sh/nvm) - -For docker installation: -- [docker](https://docs.docker.com/install/) -- [docker-compose](https://docs.docker.com/compose/install/) - -**1 - Clone the project** -```bash -git clone git@github.com:eleven-labs/blog.eleven-labs.com.git -``` - -**2 - Run the project locally** -```bash -nvm install -npx concurrently "yarn start:storybook" "yarn ts-node bin/dev" -``` - -Urls: -- Storybook: http://localhost:6006 -- Website: http://localhost:5173 - -**3 - Run the project with docker** -```bash -docker-compose up -d -``` - -Url: http://localhost:5173 - - -**4 - Start Storybook** : -```bash -docker-compose exec app yarn start:storybook -``` - -Url: http://localhost:6006 - ----------- - -Create your author page -------------- - -**1 - Create the markdown file** - -In the `_authors` folder add a markdown file with your username. -```bash -cd _authors && touch myusername.md -``` - -**2 - Add content to the file** - -Here is the template of the file. - -```md ---- -contentType: author -username: myusername -name: Name Lastname -github: mygithub -linkedin: mylinkedin -twitter: mytwitter ---- - -Some description about me... -``` - -**3 - Add your avatar** - -Add your avatar to the `_assets/authors/myusername.jpg` folder. - -**4 -Then add your article** - -> You can't do a pull request just with your author markdown, because the deployment doesn't allow an author file without any associated articles - ----------- - -Create your article page -------------- - -**1 - Create the markdown file** - -In the folder `_articles` add a markdown file with the name of your article prefixed with the date. -```bash -cd _articles && touch YYYY-MM-DD-slug.md -``` - -**2 - Add content to the file** - -Here is the file's template. - -```md ---- -contentType: article -lang: en | fr -date: YYYY-MM-DD -slug: slug of the article (No space dashes instead) -title: Title of the article -excerpt: Description of the article (Visible on the list pages) -cover: - alt: Alt image - path: /imgs/articles/YYYY-MM-DD-slug/cover.jpg - position: top | right top | right | right bottom | bottom | left bottom | left | left top | center | north | northeast | east | southeast | south | southwest | west | northwest // Default value is center -categories: - - javascript | php | agile | architecture -keywords: -- keyword (limited to 10, must not be identical to the categories, used for SEO and search) -authors: - - author's username -seo: - title: title - description: description ---- -Content of your article in markdown -``` - -> If your title or excerpt contains `:`, `"` use the syntax `>` or add your content between quotes (`"`) - -> If you want to add 2 empty lines, you can use the syntax `\` ex: -``` -first paragraph. - -\ -second paragraph displayed after 2 empty lines. -``` - -**3 - Adding Cover** - -To maintain graphic consistency, cover visuals should be in a photorealistic style and preferably related to the topics of your articles. - -By "photorealistic style" we mean: no cartoons, no 3D visuals, no illustrations, no graphics, no logos, etc. - -To choose your image, you have several options: - -- Head to [La Boîte à Outils de l'Astronaute](https://drive.google.com/drive/folders/1SLZRiqHSel3AWNSVbrblfg3ON_XwR5RU?usp=drive_link) to access ready-to-use image banks -- If you can't find what you're looking for, you can access free and royalty-free image banks like [AdobeStock](https://stock.adobe.com/fr/), [Pexels](https://www.pexels.com/fr-fr/), [Unsplash](https://unsplash.com/fr) -- If you still can't find an image despite these different solutions, you can ask Thomas Péjout to generate an image for you with MidJourney - -In order to have a quality image, we ask you to integrate an image with a minimum width of 3000 px - -**4 - Write the content of the article** - -The content of the article has to be written in markdown. -You can use one of these markdown editors: -- [StackEdit](https://stackedit.io) -- [Dillinger](http://dillinger.io) - -To add images to your article, you will need to create the folder `_assets/articles/YYYY-MM-DD-slug/` and add your images there. -Then in the markdown content, insert the tag: -```md -![alt of image]({BASE_URL}/imgs/articles/YYYY-MM-DD-slug/image-name.png) -``` - -To add an image with a figure and a figcaption you just need to write this syntax: - -```md -![alt of image]({BASE_URL}/imgs/articles/YYYY-MM-DD-slug/image-name.png) -Figure: *Source Github* -``` - -And to specify a size on the image, you can add the arguments (`width`, `height`, `maxWidth`, `maxHeight`) after the url: -```md -![alt of image]({BASE_URL}/imgs/articles/YYYY-MM-DD-slug/image-name.png?width=500) -``` - -If you need to add internal anchor links from your article to other articles of our blog, use this syntax: -```md -[title of destination article]({BASE_URL}/fr/destination-article-slug) -``` - -> Warning: Don't add html in your markdown, you don't have to override the blog template in the markdown. - -This blog supports admonitions pannels `warning` ; `info` ; `tip` and `note` to generate colored panels. -When using `
` attribute `markdown="1"` text block is rendered as Markdown. The first line must be left empty, or the block will be rendered as html - -```md -

Your Panel Title

- -Your panel text. -
-``` - -**5 - Add your pull request** - -Create your branch and add your pull request. -```bash -git checkout -b feat/add-article-slug -``` - -Once your article is finished and you want it to be published, add the label `publication` to your pull request. - ----------- - -Create your tutorial page -------------- - -**1 - Create the markdown file** - -In the folder `_tutorials` pick the subfolder `fr` or `en` depending on the translation, then create a folder with the name of your tutorial, prefixed with the date (`YYYY-MM-DD-slug`). -```bash -cd _tutorials && mkdir YYYY-MM-DD-slug -``` - -**2 - Add content to the file** - -Inside the folder named `YYYY-MM-DD-slug` you created, add a file named `index.md`. Here is the template of the file. - -```md ---- -contentType: tutorial -lang: en | fr -date: YYYY-MM-DD -slug: Slug of the tutorial (No space dashes instead) -title: Title of the tutorial -excerpt: Description of the tutorial (Visible on the list pages) -categories: - - javascript | php | agile | architecture -keywords: -- keyword (limited to 10, must not be identical to the categories, used for SEO and search) -authors: - - author's username -steps: - - slug of your steps (No space dashes instead) -seo: - title: title - description: description ---- -``` - -> If your title or excerpt contains `:`, `"` use the syntax `>` or add your content between quotes (`"`) -> The steps should be in the order you want them displayed - -Then add a steps folder and add your steps there. Here is the template of the file. - -Always inside the folder named `YYYY-MM-DD-slug`, create another folder called `steps`. Then create one file for each step. - -Example: - -``` -YYYY-MM-DD-slug - ├── index.md - └── steps/ - ├──introduction.md - ├──installation-du-serveur-graphql.md - └── ... -``` - -Here is the template of the file: - -```md ---- -contentType: tutorial-step -tutorial: slug of the tutorial (previously added in your index.md file) -slug: Slug of the step (No space dashes instead and previously added in your index.md file) -title: Title of the step ---- -Content of your step in markdown -``` - -> The files need to keep the same name as the steps declared in `index.md`, using snake case. - -**3 - Add your pull request** - -Create your branch and add your pull request. -```bash -git checkout -b feat/add-tutorial-slug -``` - -Once your tutorial is finished and you want it to be published, add the label `publication` to your pull request. +- [For developers](documentations/setup-for-dev.md) +- [For others](documentations/setup-for-others.md) diff --git a/documentations/setup-for-dev.md b/documentations/setup-for-dev.md new file mode 100644 index 000000000..f828895d9 --- /dev/null +++ b/documentations/setup-for-dev.md @@ -0,0 +1,281 @@ +# Setting up the blog for developers + +**Technical requirements** +- [TypeScript](https://www.typescriptlang.org/) +- [React](https://reactjs.org/) +- [React Router](https://reactrouter.com/en/main) +- [Vite](https://vitejs.dev/) +- [Storybook](https://storybook.js.org/) + +**Computer requirements** + +- [git](https://git-scm.com/download/linux) + +For local installation: +- [Node Version Manager](https://github.com/nvm-sh/nvm) + +For docker installation: +- [docker](https://docs.docker.com/install/) +- [docker-compose](https://docs.docker.com/compose/install/) + +**1 - Clone the project** +```bash +git clone git@github.com:eleven-labs/blog.eleven-labs.com.git +``` + +**2 - Run the project locally** +```bash +nvm install +npx concurrently "yarn start:storybook" "yarn ts-node bin/dev" +``` + +Urls: +- Storybook: http://localhost:6006 +- Website: http://localhost:5173 + +**3 - Run the project with docker** +```bash +docker-compose up -d +``` + +Url: http://localhost:5173 + + +**4 - Start Storybook** : +```bash +docker-compose exec app yarn start:storybook +``` + +Url: http://localhost:6006 + +---------- + +Create your author page +------------- + +**1 - Create the markdown file** + +In the `_authors` folder add a markdown file with your username. +```bash +cd _authors && touch myusername.md +``` + +**2 - Add content to the file** + +Here is the template of the file. + +```md +--- +contentType: author +username: myusername +name: Name Lastname +github: mygithub +linkedin: mylinkedin +twitter: mytwitter +--- + +Some description about me... +``` + +**3 - Add your avatar** + +Add your avatar to the `_assets/authors/myusername.jpg` folder. + +**4 -Then add your article** + +> You can't do a pull request just with your author markdown, because the deployment doesn't allow an author file without any associated articles + +---------- + +Create your article page +------------- + +**1 - Create the markdown file** + +In the folder `_articles` add a markdown file with the name of your article prefixed with the date. +```bash +cd _articles && touch YYYY-MM-DD-slug.md +``` + +**2 - Add content to the file** + +Here is the file's template. + +```md +--- +contentType: article +lang: en | fr +date: YYYY-MM-DD +slug: slug of the article (No space dashes instead) +title: Title of the article +excerpt: Description of the article (Visible on the list pages) +cover: + alt: Alt image + path: /imgs/articles/YYYY-MM-DD-slug/cover.jpg + position: top | right top | right | right bottom | bottom | left bottom | left | left top | center | north | northeast | east | southeast | south | southwest | west | northwest // Default value is center +categories: + - javascript | php | agile | architecture +keywords: +- keyword (limited to 10, must not be identical to the categories, used for SEO and search) +authors: + - author's username +seo: + title: title + description: description +--- +Content of your article in markdown +``` + +> If your title or excerpt contains `:`, `"` use the syntax `>` or add your content between quotes (`"`) + +> If you want to add 2 empty lines, you can use the syntax `\` ex: +``` +first paragraph. + +\ +second paragraph displayed after 2 empty lines. +``` + +**3 - Adding Cover** + +To maintain graphic consistency, cover visuals should be in a photorealistic style and preferably related to the topics of your articles. + +By "photorealistic style" we mean: no cartoons, no 3D visuals, no illustrations, no graphics, no logos, etc. + +To choose your image, you have several options: + +- Head to [La Boîte à Outils de l'Astronaute](https://drive.google.com/drive/folders/1SLZRiqHSel3AWNSVbrblfg3ON_XwR5RU?usp=drive_link) to access ready-to-use image banks +- If you can't find what you're looking for, you can access free and royalty-free image banks like [AdobeStock](https://stock.adobe.com/fr/), [Pexels](https://www.pexels.com/fr-fr/), [Unsplash](https://unsplash.com/fr) +- If you still can't find an image despite these different solutions, you can ask Thomas Péjout to generate an image for you with MidJourney + +In order to have a quality image, we ask you to integrate an image with a minimum width of 3000 px + +**4 - Write the content of the article** + +The content of the article has to be written in markdown. +You can use one of these markdown editors: +- [StackEdit](https://stackedit.io) +- [Dillinger](http://dillinger.io) + +To add images to your article, you will need to create the folder `_assets/articles/YYYY-MM-DD-slug/` and add your images there. +Then in the markdown content, insert the tag: +```md +![alt of image]({BASE_URL}/imgs/articles/YYYY-MM-DD-slug/image-name.png) +``` + +To add an image with a figure and a figcaption you just need to write this syntax: + +```md +![alt of image]({BASE_URL}/imgs/articles/YYYY-MM-DD-slug/image-name.png) +Figure: *Source Github* +``` + +And to specify a size on the image, you can add the arguments (`width`, `height`, `maxWidth`, `maxHeight`) after the url: +```md +![alt of image]({BASE_URL}/imgs/articles/YYYY-MM-DD-slug/image-name.png?width=500) +``` + +If you need to add internal anchor links from your article to other articles of our blog, use this syntax: +```md +[title of destination article]({BASE_URL}/fr/destination-article-slug) +``` + +> Warning: Don't add html in your markdown, you don't have to override the blog template in the markdown. + +This blog supports admonitions pannels `warning` ; `info` ; `tip` and `note` to generate colored panels. +When using `
` attribute `markdown="1"` text block is rendered as Markdown. The first line must be left empty, or the block will be rendered as html + +```md +

Your Panel Title

+ +Your panel text. +
+``` + +**5 - Add your pull request** + +Create your branch and add your pull request. +```bash +git checkout -b feat/add-article-slug +``` + +Once your article is finished and you want it to be published, add the label `publication` to your pull request. + +---------- + +Create your tutorial page +------------- + +**1 - Create the markdown file** + +In the folder `_tutorials` pick the subfolder `fr` or `en` depending on the translation, then create a folder with the name of your tutorial, prefixed with the date (`YYYY-MM-DD-slug`). +```bash +cd _tutorials && mkdir YYYY-MM-DD-slug +``` + +**2 - Add content to the file** + +Inside the folder named `YYYY-MM-DD-slug` you created, add a file named `index.md`. Here is the template of the file. + +```md +--- +contentType: tutorial +lang: en | fr +date: YYYY-MM-DD +slug: Slug of the tutorial (No space dashes instead) +title: Title of the tutorial +excerpt: Description of the tutorial (Visible on the list pages) +categories: + - javascript | php | agile | architecture +keywords: +- keyword (limited to 10, must not be identical to the categories, used for SEO and search) +authors: + - author's username +steps: + - slug of your steps (No space dashes instead) +seo: + title: title + description: description +--- +``` + +> If your title or excerpt contains `:`, `"` use the syntax `>` or add your content between quotes (`"`) +> The steps should be in the order you want them displayed + +Then add a steps folder and add your steps there. Here is the template of the file. + +Always inside the folder named `YYYY-MM-DD-slug`, create another folder called `steps`. Then create one file for each step. + +Example: + +``` +YYYY-MM-DD-slug + ├── index.md + └── steps/ + ├──introduction.md + ├──installation-du-serveur-graphql.md + └── ... +``` + +Here is the template of the file: + +```md +--- +contentType: tutorial-step +tutorial: slug of the tutorial (previously added in your index.md file) +slug: Slug of the step (No space dashes instead and previously added in your index.md file) +title: Title of the step +--- +Content of your step in markdown +``` + +> The files need to keep the same name as the steps declared in `index.md`, using snake case. + +**3 - Add your pull request** + +Create your branch and add your pull request. +```bash +git checkout -b feat/add-tutorial-slug +``` + +Once your tutorial is finished and you want it to be published, add the label `publication` to your pull request. diff --git a/documentations/setup-for-others.md b/documentations/setup-for-others.md new file mode 100644 index 000000000..2eab80716 --- /dev/null +++ b/documentations/setup-for-others.md @@ -0,0 +1,118 @@ +# Mise en place du blog pour les non techs + +## 1. Rejoindre l'organisation Github + +Accepter l’invitation à rejoindre l'organisation Eleven Labs envoyée par mail. + +> **N.B.** : Cette invitation est envoyée dans la boîte mail liée à votre compte Github. + +## 2. Créer sa fiche auteur + +Une fois que vous avez accès à l'organisation Eleven Labs, rendez-vous **[ici](https://github.com/eleven-labs/blog.eleven-labs.com/tree/master/_authors)**. Cliquez sur **"Add file"**, puis séléctionnez **"Create New File"** dans le ménu déroulant. Complétez le champ `Name your file...` en écrivant la première lettre de votre prénom suivi de votre nom de famille suivi de **".md"**. Le nom du fichier doit donc ressembler à celui-ci : `pnom.md`. + +Dans le corps du fichier, collez le template ci-dessous, préalablement complété avec vos informations : + +``` +--- +contentType: author +username: votrepseudo +name: Nom Prénom +github: votrepseudogithub +linkedin: votrepseudolinkedin +twitter: votrepseudoytwitter +--- + +Quelques mots à propos de vous (optionnel) +``` + +> **N.B.** : Pour Linkedin et Twitter, renseignez uniquement votre nom d'utilisateur et non l'URL de votre profil. + +Une fois cela fait, appuyez sur **"Commit changes"** en haut à droite de votre écran, écrivez `feat/add-author-pnom` dans le champ **Create a new branch for this commit and start a pull request**, puis cliquez sur **"Propose changes"**. + +Sur la page suivante, écrivez **"Create author page pnom"** dans le champ **"Add a title"**, puis appuyez sur **"Create pull request"**. + +Votre Pull request a été créée ! Vous pouvez l'annoncer sur le channel Slack [#blog](https://eleven-labs.slack.com/archives/C025L32JY). + +Un astronaute se chargera de la relire et la validera si tout est bon. Si des choses sont à revoir, il reviendra vers vous. + +## 3. Créer le fichier de son article + +Rendez-vous maintenant sur cette [page](https://github.com/eleven-labs/blog.eleven-labs.com/tree/master/_articles). + +Puis séléctionnez le dossier **"fr"** ou **"en"**, selon que vous souhaitiez rédiger votre article en français ou en anglais. + +Une fois dans le dossier adéquat, cliquez en haut à droite sur le menu déroulant **"Add files"**, puis séléctionnez **"Create new file"**. + +## 4. Nommer son fichier + +Le nom du fichier de l'article doit respecter la nomenclature suivante `yyyy-mm-dd-titre-de-votre-article.md`. Saisissez ces informations dans le champ **"Name your file"**, en haut de votre écran. + +## 5. Créer l'en-tête + +Collez le template d'en-tête suivant au tout début du corps de votre article, puis complétez-le : + +``` +--- +contentType: article +lang: fr ou en +date: 'yyyy-mm-dd' +slug: titre-de-votre-article +title: Titre de votre article +excerpt: Rédigez ici une courte phrase descriptive de votre article +categories: + - Javascript ou PHP ou Agile ou Architecture +authors: + - votre pseudo d'auteur +cover: + alt: Description de l'image de couverture + path: /imgs/articles/nom-du-dossier-de-votre-cover/cover.jpg +keywords: + - symfony + - développement web +--- +``` + +## 6. Rédiger son article + +Copiez le corps de vote article à la suite de l'en-tête, ou rédigez directement. + +> **N.B.** : Notez que le format de votre article doit être en Markdown. + +Vous pouvez retrouver [les règles de syntaxe de ce format par ici](https://docs.framasoft.org/fr/grav/markdown.html). Vous pouvez également ["transformer" votre texte en Markdown via cet outil](https://www.pastetomarkdown.com/). + +## 7. Faire sa PR + +Une fois ces étapes réalisées, cliquez sur le bouton **"Commit changes"** en haut à droite de votre écran. Renseignez le titre de votre commit dans le champ **"Commit message"** au format suivant : `add-titre-de-votre-article`. + +Validez en appuyant sur le bouton **"Propose changes"**. + +Sur la page suivante, écrivez de nouveau `add-titre-de-votre-article` dans le champ **"Add a title"**, puis appuyez sur **"Create pull request"**. + +## 8. Rajouter une couverture + +Allez dans le repértoire : [\_assets/articles](https://github.com/eleven-labs/blog.eleven-labs.com/tree/master/_assets/articles). Cliquez sur **"Add file"** en haut à droite de vote écran, puis cliquez ensuite sur **"Create New File"** dans le menu déroulant. + +Dans le champ **"Name your file"**, saisissez le nom de votre dossier. + +> **N.B.** : Ce nom doit être le même que celui de votre article au caractère près. + +Une fois que ce nom est saisi, tapez sur **"/"**. Cela a pour effet de créer votre dossier. Tapez maintenant **"fichier"** en nom de fichier, puis appuyez sur "Commit changes" en haut à droite.Appuyez sur Propose changes. + +Dans votre branche, retournez maintenant dans [blog.eleven-labs.com/\_assets](http://blog.eleven-labs.com/_assets)/[articles](https://github.com/eleven-labs/blog.eleven-labs.com/tree/master/_assets/articles).Vous devriez y retrouver votre dossier nouvellement créé. + +Selectionnez-le, puis en haut à droite cliquez sur **"Add files"**, puis **"Upload files"**, puis selectionnez l'image de couverture que vous souhaitez mettre dans l'article. + +> Pour plus de simplicité, nommez cette image au préalable **"cover"**. Elle doit être au format jpg. +> +> Pour maintenir une cohérence graphique, les images de couvertures doivent toutes être dans un style photoréaliste en lien avec votre article. N'utilisez donc pas d'images "artoon", de visuels 3D, de logos, etc. + +Pour choisir cette image vous avez plusieurs options : + +- Rendez-vous dans [La Boîte à Outils de l'Astronaute](https://drive.google.com/drive/folders/1SLZRiqHSel3AWNSVbrblfg3ON_XwR5RU?usp=drive_link) pour accéder à une séléction d'images. + +- Vous pouvez aussi utiliser des images libres de droits dans les librairies [AdobeStock](https://stock.adobe.com/fr/), [Pexels](https://www.pexels.com/fr-fr/), ou encore [Unsplash](https://unsplash.com/fr). + +- Si aucune de ces solutions ne vous convient, vous pouvez demander à l'astronaute Thomas Péjout to generate an image for you with MidJourney + + +> **N.B.** : Assurez-vous que l'image séléctionnée dispose d'une largeur minimale de 3000px.