Add your own tutorial

Caution

The following content is a copy of the EDITO Tutorial content README.

How to add new content

For now, it is only possible to add new content by creating a pull request on this public gitlab repository.

This section explains in more detail how to create a new tutorial, how to structure it, how to reference it in tutorials.json, and how to submit it for review.

Add a new tutorial entry

All tutorials displayed in the “tutorials” interface are defined in the root list of the tutorials.json file located at the root of this repository.

To create a new tutorial: 1. Open the tutorials.json file. 2. Add a new object to the root list, following the structure documented below. 3. Fill all mandatory fields, including translations, category, and tags. 4. Commit your changes.

Create an article

An article corresponds to a tile on the tutorials page. When clicking Read, the user is redirected to the URL in the articleUrl field.

A tile can also include a Run button if the tutorial launches a preconfigured EDITO service. This is controlled by the deploymentUrl field.

JSON structure

Below is the JSON structure you must use:

{
    "name": {
        "fr": "Le nom de votre article en français",
        "it": "Il nome del tuo articolo in italiano",
        "en": "The name of your article in english"
    },
    "abstract": {
        "fr": "Une description courte de votre article",
        "it": "Una breve descrizione del tuo articolo",
        "en": "A short description of your article"
    },
    "authors": [
        "The authors's names"
    ],
    "types": [
        "types": [
          {
            "fr": "Tutoriel",
            "it": "Tutorial",
            "en": "Tutorial"
          }
    ],
    "tags": [
        "explore", // If your tutorial does not require user authentication
        "create", // If your tutorial allow the user to create content on EDITO
        "contribute" // If your tutorial allow the user to build and publish content on EDITO
    ],
    "category": "discover EDITO",  // For now, you'll only be able to choose between:  "Ocean modelling", "Ocean data quality", "Data visualization", "What-If applications", "Focus applications", "discover EDITO", "training courses in data science", "training courses with python", "training courses with R" and "best practices",
    "imageUrl": "https://www.edito.eu/wp-content/uploads/2023/09/favicon.png",
    "articleUrl": {
        "fr": "https://my/tutorial/fr/page.html", // the url of your tutorial
        "it": "https://my/tutorial/it/page.html",
        "en": "https://my/tutorial/en/page.html",
    }
    "deploymentUrl": "https://datalab.dive.edito.eu/launcher/"// the url of your pre-configured service
    // parts: []
},

Hosting your tutorial

You can : - Host your HTML page externally (recommended), then reference it directly in articleUrl. - Or include a Markdown article inside this repository, under the articles/ directory, using this URL prefix in articleUrl:

https://gitlab.mercator-ocean.fr/pub/edito-infra/edito-tutorials-content/-/blob/main/articles/myNewArticle.md

Creating a “Run” button (optional)

If your tutorial requires a preconfigured Datalab service: 1. Go to My Services on EDITO. 2. Configure the service. 3. Save the configuration. 4. Copy the URL generated by the platform. 5. Paste it in the deploymentUrl field.

This enables the user to start the service directly from the tutorial tile.

Organizing tutorials into sections

You can create sections and sub-sections instead of providing direct article URLs.

To do this: - Remove articleUrl and/or deploymentUrl. - Replace them with a parts field containing a list of tutorials.

Each entry inside parts can also contain its own parts, allowing nested structures.

Example :

{
  "name": { ... },
  "abstract": { ... },
  "parts": [
      {
          "name": { ... },
          "articleUrl": { ... }
      },
      {
          "name": { ... },
          "parts": [
              { "articleUrl": { ... } }
          ]
      }
  ]
}

Create a Merge Requests

Once your tutorial and JSON entry are ready: 1. Push your branch to the repository. 2. Create a Merge Requests against branch main branch. 3. Ping @pub/edito-infra/codeowners to request code owners to review your proposal.