Skip to content

[EmioLabs] create your own lab: adds solution and include documentation #67

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
HanaeRateau wants to merge 3 commits into
base: main
Choose a base branch
from
+132 −73
Open

[EmioLabs] create your own lab: adds solution and include documentation #67

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
58745a3
Reorders extended commands in alphabetical order
HanaeRateau May 29, 2026
f13a068
Adds include command
HanaeRateau May 29, 2026
8709628
Adds solution commands
HanaeRateau May 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
205 changes: 132 additions & 73 deletions docs/Users/EmioLabs/create-your-lab.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -95,7 +95,7 @@ We also added extensions to the original Markdown to ease the making of labs.

These elements extend the basic syntax by adding additional features. It will only be understood by this application.

We use nested fenced block principle to define our custom blocks. A block fence is a sequence of at least three consecutive `:`. The content of the fenced block consists of all subsequent lines, until a closing block fence with at least as many `:` as the opening block fence.
We use *nested fenced block* principle to define our custom blocks. A block fence is a sequence of at least three consecutive `:`. The content of the fenced block consists of all subsequent lines, until a closing block fence with at least as many `:` as the opening block fence.

If you want to nest multiple fenced blocks, the parent block fence should have more `:` than the children. For example :

Expand All @@ -107,6 +107,86 @@ MY_CONTENT
:::: <-- end of parent
```

#### Buttons

There are three types of buttons available :

1. The __runsofa-button__ will launch a SOFA simulation with the specified scene file `MY_SCENE.py`. You can pass as many arguments as you want to the scene file:
```markdown
#runsofa-button(file="assets/labs/<LAB_NAME>/MY_SCENE.py", 
pyargs=["MY_ARGUMENT_1", "MY_ARGUMENT_2"])
```
2. The __python-button__ will run a python script `MY_SCRIPT.py`. You can optionally provide a path to additional python modules that will be added to the `PYTHONPATH` before running the script.
```markdown
#python-button(file="assets/labs/<LAB_NAME>/MY_SCRIPT.py",
pyargs=["arg1", "example/path/as/arg2"], 
extrapythonpath=["OPTIONAL_PATH_TO_PYTHON_MODULES"])
```
You can use this button to install extra Python packages for your lab with:
```markdown
#python-button(pyargs=["-m", "pip", "install", "--target", "assets/labs/<LAB_NAME>/modules/site-packages", "-r", "assets/labs/<LAB_NAME>/requirements.txt"])
```
3. The __open-button__ will open a file `MY_FILE` with the default application associated with the file type on your system.
```markdown
#open-button(file="assets/labs/<LAB_NAME>/MY_FILE")
```

An argument can be a value of a [`select block`](#select-block) or an [`input`](#text-input) field, by using its unique name that you defined. For example:

```markdown
#runsofa-button(file="MY_SCENE.py",
pyargs=["MY_UNIQUE_SELECT_OR_INPUT_NAME", "MY_ARGUMENT_2"])
```

#### Collapsible Block

Create collapsible section with the following block fence with the keyword `collapse` :

```markdown
::: collapse MY_TITLE
MY_CONTENT
:::
```

#### Exercise Block

You can highlight your exercises by using the following block fence with the keyword `exercise` :

```markdown
::: exercise
MY_EXERCISE_CONTENT
:::
```

#### Highlighted block

You can highlight some text by using the following block fence with the keyword `highlight` :

```markdown
::: highlight
MY_CONTENT
:::
```

#### Icons
We use the icon library [font awesome](https://fontawesome.com/icons). You can browse and copy the name of a free icon to put into the Markdown command:

```markdown
#icon("ICON_NAME")
```

For example:
```markdown
#icon("warning") <-- will display a warning icon
```

#### Include
You can include the content of another markdown file with the following syntax:

```markdown
#include("assets/labs/<LAB_NAME>/MY_MARKDOWN_FILE.md")
```

#### Quiz

You can create a quiz with **open answer** or a **multiple choice question**. For an open answer, create a block fence with the keyword `quiz`. Inside the quiz fence block, create another block fence with the keyword `question`, followed by your question (on the same line) and the answer on the next line, inside the block fence. For example :
Expand Down Expand Up @@ -150,62 +230,74 @@ This will give the following :
<img className="centered" src={emio_labs_qcm02} width="70%" alt="Example of a multiple choice question after submission. The correct answers are highlighted in green, the wrong one in red."/>
<figcaption>After submitting the answer.</figcaption>

#### Video

You can add videos by using the following container :
#### Select Block

Create select content with the following block fence with the keyword `select`.
Inside the select block, you can define options with the keyword `option` followed by the value for the option. Each option should have a unique value.
You can optionally add a label to the option by using the syntax `[MY_LABEL]`For example:

```markdown
#main-video("PATH_OR_URL_TO_MY_VIDEO")
#video("PATH_OR_URL_TO_MY_VIDEO")
:::: select MY_UNIQUE_SELECT_NAME
::: option MY_OPTION_VALUE_1 [MY_LABEL_1]
::: option MY_OPTION_VALUE_2
::: option MY_OPTION_VALUE_3 [MY_LABEL_3]
::::
```

The `main-video` will move to the bottom right corner of the application when scrolling down. Only one `main-video` should be used in a lab (including main and other markdown files).
You may have as many options as you want.

#### Highlighted block
#### Solutions
You can hide solutions in a collapsible block with the keyword `solution`. A solution command will display a "Solution" collapse. When clicking on it, the content of the solution will be displayed.
Don't forget to enable the solution mode in Emio Labs to see the solutions in the app. You can toggle it in **Labs>Enable/Disable Solutions** in the top menu bar of the app.

You can highlight some text by using the following block fence with the keyword `highlight` :
It exists two ways to include solutions in your lab:
- <a href="#inline-solution">the inline</a>
- <a href="#solution-block">the solution block</a>

```markdown
::: highlight
MY_CONTENT
:::info
The labs that come with Emio Labs will look for the solution files in the solutions directory `path/to/home/emio-labs/VERSION/assets/solutions/LAB_NAME/`. Make sure to put the solution files in this directory.
Comment thread
EulalieCoevoet marked this conversation as resolved.
:::
```

#### Exercise Block
##### Inline Solution
The content of the solution is given by the markdown file `MY_SOLUTION.md` and the solution block with the id `MY_SOLUTION_ID` in this markdown file. For example, if the solution file contains
Copy link
Copy Markdown
Contributor

@EulalieCoevoet EulalieCoevoet Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The code block could come before the explanation.

`#solution(file="assets/solutions/<LAB_NAME>/MY_SOLUTION.md", id="MY_SOLUTION_ID")`, it will display the content of the solution block with the id `MY_SOLUTION_ID` in the file `MY_SOLUTION.md`.
Copy link
Copy Markdown
Contributor

@EulalieCoevoet EulalieCoevoet May 30, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe we should start by explaining the solution block.


You can highlight your exercises by using the following block fence with the keyword `exercise` :

```markdown
::: exercise
MY_EXERCISE_CONTENT
:::
```
The content of the file `MY_SOLUTION.md` should be a list of <a href="#solution-block">`solution blocks`</a> with IDs with `MY_SOLUTION_ID` among them.

#### Collapsible Block
`MY_SOLUTION.md` example:

Create collapsible section with the following block fence with the keyword `collapse` :

```markdown
::: collapse MY_TITLE
MY_CONTENT
## A title that won't be in the solution.

::: solution MY_SOLUTION_ID
MY_SOLUTION_CONTENT_IN_MARKDOWN
:::

Some text that won't be in the solution.

::: solution exercise-1
MY_SOLUTION_CONTENT_IN_MARKDOWN_FOR_EXERCISE_1
:::
```

#### Select Block

Create select content with the following block fence with the keyword `select`.
Inside the select block, you can define options with the keyword `option` followed by the value for the option. Each option should have a unique value.
You can optionally add a label to the option by using the syntax `[MY_LABEL]`For example:
##### Solution Block
The content of the solution is directly written in the markdown file, inside a block fence with the keyword `solution`. For example:
Copy link
Copy Markdown
Contributor

@EulalieCoevoet EulalieCoevoet Jun 1, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The content of the solution is directly written in the markdown file, inside a block fence with the keyword `solution`. For example:
The content of the solution is inside a block fence with the keyword `solution`. For example:


```markdown
:::: select MY_UNIQUE_SELECT_NAME
::: option MY_OPTION_VALUE_1 [MY_LABEL_1]
::: option MY_OPTION_VALUE_2
::: option MY_OPTION_VALUE_3 [MY_LABEL_3]
::::
```
```markdown
:::: solution MY-UNIQUE-ID
MY_SOLUTION_CONTENT_IN_MARKDOWN
::::
```

You may have as many options as you want.
```markdown
:::: solution MY-UNIQUE-ID
#include("assets/solutions/<LAB_NAME>/MY_SOLUTION.md")
::::
```

#### Text Input
You can add an text input field with:
Expand All @@ -226,49 +318,16 @@ For example:
<img className="centered" src={emio_labs_input} width="40%" alt="Example of an input field with the placeholder and a value."/>
<figcaption>Input example. (left) Placeholder. (right) Value.</figcaption>

#### Buttons

There are three types of buttons available :

1. The __runsofa-button__ will launch a SOFA simulation with the specified scene file `MY_SCENE.py`. You can pass as many arguments as you want to the scene file:
```markdown
#runsofa-button(file="assets/labs/<LAB_NAME>/MY_SCENE.py", 
pyargs=["MY_ARGUMENT_1", "MY_ARGUMENT_2"])
```
2. The __python-button__ will run a python script `MY_SCRIPT.py`. You can optionally provide a path to additional python modules that will be added to the `PYTHONPATH` before running the script.
```markdown
#python-button(file="assets/labs/<LAB_NAME>/MY_SCRIPT.py",
pyargs=["arg1", "example/path/as/arg2"], 
extrapythonpath=["OPTIONAL_PATH_TO_PYTHON_MODULES"])
```
You can use this button to install extra Python packages for your lab with:
```markdown
#python-button(pyargs=["-m", "pip", "install", "--target", "assets/labs/<LAB_NAME>/modules/site-packages", "-r", "assets/labs/<LAB_NAME>/requirements.txt"])
```
3. The __open-button__ will open a file `MY_FILE` with the default application associated with the file type on your system.
```markdown
#open-button(file="assets/labs/<LAB_NAME>/MY_FILE")
```

An argument can be a value of a [`select block`](#select-block) or an [`input`](#text-input) field, by using its unique name that you defined. For example:

```markdown
#runsofa-button(file="MY_SCENE.py",
pyargs=["MY_UNIQUE_SELECT_OR_INPUT_NAME", "MY_ARGUMENT_2"])
```

#### Icons
We use the icon library [font awesome](https://fontawesome.com/icons). You can browse and copy the name of a free icon to put into the Markdown command:
#### Video

```markdown
#icon("ICON_NAME")
```
You can add videos by using the following container :

For example:
```markdown
#icon("warning") <-- will display a warning icon
#main-video("PATH_OR_URL_TO_MY_VIDEO")
#video("PATH_OR_URL_TO_MY_VIDEO")
```

The `main-video` will move to the bottom right corner of the application when scrolling down. Only one `main-video` should be used in a lab (including main and other markdown files).

## Share Your Labs

Expand Down
Loading