Contribution - GitHub Web tutorial (beginner)

May 24, 2025

Before following this tutorial on adding a new tutorial, you need to have completed a few preliminary steps. If you haven't already done so, please take a look at this introductory tutorial first, then come back here:

Contribution - TutorialsHow do I submit new content to Plan ₿ Academy?

You already have:

Choose a theme for your tutorial;
Contacted the Plan ₿ Academy team via Telegram group or [email protected] ;
Choose your contribution tools.

In this tutorial, we'll look at how to add your tutorial to Plan ₿ Academy using the web version of GitHub. If you've already mastered Git, this very detailed tutorial may not be necessary for you. Instead, I recommend you check out one of these other 2 tutorials, where I detail the guidelines to follow and the steps for making changes from a local:

Experienced users:

Contribution - Git tutorial (advanced)Guide for advanced users to offer a tutorial on Plan ₿ Academy with Git

Intermediate (GitHub Desktop):

Contribution - Tutorial with GitHub Desktop (Intermediate)Complete guide to propose a tutorial on Plan ₿ Academy using GitHub Desktop

Prerequisites

Prerequisites before starting the tutorial:

Have a GitHub account;
Have a fork of the Plan ₿ Academy source repository;
Have a teacher profile on Plan ₿ Academy (only if you offer a full tutorial).

If you need help getting these prerequisites, my other tutorials will help:

GitHub AccountHow to create your own account on GitHub?

GitHub DesktopHow to set up your local work environment?

Professor Plan ₿ AcademyHow do I add or modify my teacher profile on Plan ₿ Academy?

Once everything is in place and you have your fork of the Plan ₿ Academy repository, you can start adding the tutorial.

1 - Create a new branch

Open your browser and navigate to your fork page in the Plan ₿ Academy repository. This is the fork you established on GitHub. The URL of your fork should look like this: https://github.com/[your-username]/bitcoin-educational-content:

Make sure you're on the main dev branch, then click on the "Sync fork" button. If your fork is not up to date, GitHub will ask you to update your branch. Proceed with this update:

Click on the dev branch, then name your working branch so that its title clearly reflects its purpose, using dashes to separate words. For example, if our aim is to write a tutorial on using Green Wallet, the branch could be called: tuto-green-wallet-loic. After entering a suitable name, click on "Create branch" to confirm the creation of your new branch based on dev:

You should now be on your new branch of work:

This means that any changes you make will be saved only on that specific branch.

For each new article you plan to publish, create a new branch from dev.

A branch in Git represents a parallel version of the project, allowing you to work on modifications without affecting the main branch, until your work is ready to be integrated.

2 - Add tutorial files

Now that the working branch has been created, it's time to integrate your new tutorial.

Within your branch files, you'll need to find the appropriate subfolder for the placement of your tutorial. The organization of the folders reflects the different sections of the Plan ₿ Academy website. In our example, since we're adding a tutorial on Green Wallet, head to the following path: bitcoin-educational-content\tutorials\wallet which corresponds to the WALLET section of the website:

In the wallet folder, create a new directory specifically dedicated to your tutorial. The name of this folder should clearly indicate the software covered in the tutorial, using hyphens to connect words. For my example, the folder will be named green-wallet. Click on "Add File" then on "Create new file":

Enter the folder name followed by a slash / to confirm its creation as a folder.

In this new subfolder dedicated to your tutorial, you need to add several items:

Create an assets folder to hold all the illustrations needed for your tutorial;
Within this assets folder, create a subfolder named according to the tutorial's original language code. For example, if the tutorial is written in English, this subfolder should be named en. Place all the tutorial's visuals (diagrams, images, screenshots, etc.) in this folder.
A tutorial.yml file must be created to record the details of your tutorial;
A markdown file must be created to write the actual content of your tutorial. This file must be named according to the code of the language in which it is written. For example, for a tutorial written in French, the file should be called fr.md.

To summarize, here is the file hierarchy (we'll continue creating them in the next section):

bitcoin-educational-content/
└── tutorials/
└── wallet/ (à modifier avec la bonne catégorie)
└── green-wallet/ (à modifier avec le nom du tuto)
├── assets/
│   ├── fr/ (à modifier selon le code de langue approprié)
├── tutorial.yml
└── fr.md (à modifier selon le code de langue approprié)

3 - Fill in the YAML file

Let's start with the YAML file. In the box for creating a new file, enter tutorial.yml:

Fill in the tutorial.yml file by copying the following template:

id: 

project_id: 

tags:
  - 
  - 
  - 

category: 

level: 

professor_id:

# Proofreading metadata

original_language:
proofreading:
  - language: 
    last_contribution_date:
    urgency:
    contributor_names:
      - 
    reward:

Here are the required fields:

id: A UUID (Universally Unique Identifier) that uniquely identifies the tutorial. You can generate it using an online tool. The only requirement is that this UUID is random to avoid conflicts with another UUID on the platform;
project_id: The UUID of the company or organization behind the tool presented in the tutorial from the project list. For example, if you are creating a tutorial about the Green Wallet software, you can find this project_id in the following file: bitcoin-educational-content/resources/projects/blockstream/project.yml. This information is added to your tutorial's YAML file because Plan ₿ Academy maintains a database of all companies and organizations operating on Bitcoin or related projects. By adding the project_id of the entity linked to your tutorial, you create a link between the two elements;
tags: 2 or 3 relevant keywords related to the tutorial content, exclusively chosen from the Plan ₿ Academy tag list;
category: The sub-category corresponding to the tutorial content, according to the Plan ₿ Academy website structure (for example, for wallets: desktop, hardware, mobile, backup);
level: The difficulty level of the tutorial, chosen from:
- beginner
- intermediate
- advanced
- expert
professor_id: Your professor_id (UUID) as displayed on your professor profile;
original_language: The original language of the tutorial (e.g., fr, en, etc.);
proofreading: Information about the proofreading process. Complete the first part, as proofreading your own tutorial counts as a first validation:
- language: Language code of the proofreading (e.g., fr, en, etc.).
- last_contribution_date: Date of the day.
- urgency: 1
- contributor_names: Your GitHub ID.
- reward: 0

For more details on your teacher ID, please refer to the corresponding tutorial:

Professor Plan ₿ AcademyHow do I add or modify my teacher profile on Plan ₿ Academy?

id: e84edaa9-fb65-48c1-a357-8a5f27996143

project_id: 3b2f45e6-d612-412c-95ba-cf65b49aa5b8

tags:
  - wallets
  - software
  - keys

category: mobile

level: beginner

professor_id: 6516474c-c190-41f2-b2ab-3d452ce7bdf0

# Proofreading metadata

original_language: fr
proofreading:
  - language: fr
    last_contribution_date: 2024-11-20
    urgency: 1
    contributor_names:
      - LoicPandul
    reward: 0

Once you have finished modifying your tutorial.yml file, save your document by clicking on the "Commit changes..." button:

Add a title and description, and make sure the commit is made to the branch you created at the start of this tutorial. Then confirm by clicking on "Commit changes".

4 - Creating subfolders for images

Click on "Add File" again and then on "Create new file":

Enter assets followed by a slash / to create the folder:

Repeat this step in the /assets folder to create the language subfolder, for example fr if your tutorial is in French:

In this folder, create a dummy file to force GitHub to keep your folder (which would otherwise be empty). Name this file .gitkeep. Then click on "Commit changes...".

Check again that you are on the correct branch, then click on "Commit changes".

5 - Creating the Markdown file

Now we're going to create the file that will host your tutorial, named according to your language code, for example fr.md if we're writing in French. Go to your tutorial folder:

Click on "Add file*", then on "Create new file*".

Name the file using your language code. In my case, as the tutorial is written in French, I name my file fr.md. The extension .md indicates that the file is in Markdown format.

We start by filling in the Properties section at the top of the document. Manually add and fill in the following block of code (the name: and description: keys must be kept in English, but their values must be written in the language used for your tutorial):

---
name: [Titre]
description: [Description]
---

Fill in the name of your tutorial and a short description:

Then add the path to the cover image at the beginning of your tutorial. To do this, note:

![cover-green](assets/cover.webp)

This syntax will come in handy whenever you need to add an image to your tutorial. The exclamation mark indicates an image, whose alternative text (alt) is specified between the square brackets. The path to the image is indicated between the brackets:

Click on the "Commit changes..." button to save this file.

Check that you're on the right branch, then confirm the commit.

Your tutorial folder should now look like this, according to your language code:

6 - Add logo and cover

Within the assets folder, you need to add a file named logo.webp, which will serve as the thumbnail for your article. This image must be in .webp format, and must be square in size to match the user interface.

You're free to choose the software logo used in the tutorial, or any other relevant image, as long as it's royalty-free. In addition, add an image entitled cover.webp in the same place. This will be displayed at the top of your tutorial. Make sure that this image, like the logo, respects the rights of use and is appropriate to the context of your tutorial.

To add images to the /assets folder, you can drag and drop them from your local files. Make sure you're in the /assets folder and on the right branch, then click on "Commit changes".

You should now see the images appear in the folder.

7 - Writing the tutorial

Continue writing your tutorial by noting your content in the Markdown file with the language code (in my example, in French, it's the fr.md file). Go to the file and click on the pencil icon:

Start writing your tutorial. When adding a subtitle, use the appropriate Markdown formatting by prefixing the text with ##:

Alternate between "Edit" and "Preview" views to better visualize the rendering.

To save your work, click on "Commit Changes...", make sure you're on the right branch, then confirm by clicking on "Commit Changes" again.

8 - Add visuals

The language subfolder in the /assets folder (in my example: /assets/en) is used to store the diagrams and visuals that will accompany your tutorial. As far as possible, avoid including text in your images to make your content accessible to an international audience. Of course, the software presented will contain text, but if you add schematics or additional indications on the software screenshots, do so without text or, if essential, use English.

To name your images, simply use numbers corresponding to their order of appearance in the tutorial, formatted as two digits (or three digits if your tutorial contains more than 99 images). For example, name your first image 01.webp, your second 02.webp, and so on.

Your images must be in .webp format only. If necessary, you can use my image conversion software.

Now that you've added your images to the subfolder, you can delete the dummy file .gitkeep. Open this file, click on the three small dots in the top right-hand corner, then on "Delete file".

Save your changes by clicking on "Commit changes...".

To insert a diagram from your subfolder into your editorial document, use the following Markdown command, taking care to specify the appropriate alternative text and the correct image path for your language:

![green](assets/fr/01.webp)

The exclamation mark at the beginning indicates an image. The alternative text, which helps with accessibility and referencing, is placed between the square brackets. Finally, the path to the image is indicated between brackets.

If you wish to create your own schematics, be sure to follow the Plan ₿ Academy graphic guidelines to ensure visual consistency:

Font: Use IBM Plex Sans;
Colours:
Orange: #FF5C00
Black: #000000
White: #FFFFFF

It is imperative that all visuals integrated into your tutorials are free of copyright or respect the source file license. Therefore, all diagrams published on Plan ₿ Academy are made available under a CC-BY-SA license, in the same way as the text.

-> Tip: When sharing files in public, such as images, it's important to remove superfluous metadata. This can contain sensitive information, such as location data, creation dates and author details. To protect your privacy, it's a good idea to remove this metadata. To simplify this operation, you can use specialized tools such as Exif Cleaner, which enables you to clean up a document's metadata with a simple drag-and-drop.

9 - Propose the tutorial

Once you've finished writing your tutorial in the language of your choice, the next step is to submit a Pull Request. The administrator will then add the missing translations to your tutorial, using our automated translation method with human proofreading.

To proceed with the Pull Request, after saving all your changes, click on the "Contribute" button, then on "Open pull request":

A Pull Request is a request made to integrate changes from your branch into the main branch of the Plan ₿ Academy repository, which allows review and discussion of changes before they are merged.

Before continuing, check carefully at the bottom of the interface that these changes are what you expected:

Make sure, at the top of the interface, that your working branch is merged onto the dev branch of the Plan ₿ Academy repository (which is the main branch).

Enter a title that briefly summarizes the changes you wish to merge with the source repository. Add a brief comment describing these changes (if you have an issue number associated with the creation of your tutorial, remember to note Closes #{issue number} as a comment), then click on the green "Create pull request" button to confirm the merge request:

Your PR will then be visible in the "Pull Request" tab of the main Plan ₿ Academy repository. All you have to do now is wait until an administrator contacts you to confirm that your contribution has been merged, or to request any further modifications.

After merging your PR with the main branch, we recommend deleting your working branch (in my example: tuto-green-wallet) to maintain a clean history of your fork. GitHub will automatically offer you this option on your PR page:

If you wish to make changes to your contribution after you have already submitted your PR, the steps to follow depend on the current status of your PR:

If your PR is still open and has not yet been merged, make the changes on the same workbranch. The commit changes will be added to your still open PR;
In the event that your PR has already been merged with the main branch, you'll need to redo the process from the beginning by creating a new branch, then submitting a new PR. Make sure your fork is synchronized with the Plan ₿ Academy source repository on the dev branch before proceeding.

If you're having technical difficulties submitting your tutorial, please don't hesitate to ask for help on our dedicated Telegram group for contributions. Thank you very much!

Did this work well for you?

Author

This tutorial has been written by Loïc Morel

You can say thanks by tipping the professor.

Loïc Morel

7Courses

104Tutorials

I write educational content about Bitcoin.

guidesuser-friendlyhigh-level

Credits

This tutorial has not been proofread yet

0/3Proofreading status

The original content has been translated by AI, but human review is necessary to ensure its accuracy.

3 786 sats1 893 sats947 sats

*Rewards may vary based on the $ exchange rate

Every content on the platform is the result of a collaborative effort: each lesson, translation, and revision is made possible by the work of contributors. For this reason, we are always looking for proofreaders who can review our content in many languages. If you want to participate in the proofreading process, please reach out in our Telegram group and read our tutorial. We remind you that this content is open-source - licensed under CC BY-SA - so it can be freely shared and used, as long as the original source is credited.