Skip to content

Commit ba06432

Browse files
DamoM73DamoM73
committed
Add learning-intention callouts to docs
Adds a new amber 'learn' callout style and inserts learning-intention callouts across the main tutorial pages. It also updates the docs home page to explain the available callout types and code block conventions, improving clarity and consistency across the course materials.
1 parent 470906f commit ba06432

27 files changed

Lines changed: 202 additions & 10 deletions

‎docs/index.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,38 @@ Every component page follows the same layout:
2222
- **Code explanation** → click to open a line-by-line explanation of each example
2323
- **Exercises** → practice tasks, with solutions on the [Exercise Solutions](reference/solutions.md) page
2424

25+
## Callouts
26+
27+
Coloured boxes called **callouts** highlight different kinds of information. Each type of callout has its own colour and icon, so we can tell at a glance what it's for.
28+
29+
!!! learn "Learning intentions"
30+
This callout is at the top of every tutorial page. It lists what we will learn on that page.
31+
32+
!!! primm "PRIMM"
33+
This callout comes after each example program. It asks us to **predict** what the code will do, **run** it, and **investigate** how it works. Sometimes it asks us to **modify** the code.
34+
35+
!!! note "Code explanation"
36+
This callout comes after each PRIMM callout and gives a line-by-line explanation of the example program. On the tutorial pages it starts closed, so we can make our own prediction first. Click its title to open it.
37+
38+
!!! tip "Tip"
39+
This callout gives extra information, such as definitions, background facts, comparisons and hints.
40+
41+
!!! warning "Warning"
42+
This callout warns us about mistakes that are easy to make, or things that will stop our program or micro:bit working.
43+
44+
## Code blocks
45+
46+
Programs are shown in **code blocks** like this one:
47+
48+
```python linenums="1"
49+
from microbit import *
50+
51+
display.scroll("Hello")
52+
```
53+
54+
- The **line numbers** on the left match the line numbers used in the Code explanation.
55+
- The **copy** button in the top-right corner of a code block copies the code, so we can paste it into Thonny.
56+
2557
## Tutorial files
2658

2759
Download all the examples and exercise starter files: [microbit_tutorials.zip](downloads/microbit_tutorials.zip). See [Setting up Thonny](micropython/thonny.md#tutorial-files) for how to use them.

‎docs/microbit/accelerometer.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Accelerometer
22

3+
!!! learn "On this page we will learn"
4+
- how to measure movement and tilt in three directions
5+
- how to read all three values at once
6+
- how to recognise gestures such as shaking or turning face up
7+
38
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/UT35ODxvmS0" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
49

510
The accelerometer measures movement and tilt in three directions and recognises gestures such as shaking or turning face up.

‎docs/microbit/buttons.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Buttons
22

3+
!!! learn "On this page we will learn"
4+
- how to check whether button A or B is being pressed
5+
- how to check whether a button was pressed earlier
6+
- how to count how many times a button was pressed
7+
38
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/hnT0qHM3_hQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
49

510
The micro:bit has two push buttons, **A** and **B**, that detect when they are pressed.

‎docs/microbit/compass.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Compass
22

3+
!!! learn "On this page we will learn"
4+
- how to calibrate the compass
5+
- how to find which direction the micro:bit is pointing
6+
- how to measure magnetic field strength
7+
38
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/a3P6LWwPBqM" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
49

510
The compass (a **magnetometer**) measures magnetic fields, so it can find which direction the micro:bit is pointing and detect nearby magnets.

‎docs/microbit/display.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Display
22

3+
!!! learn "On this page we will learn"
4+
- how to scroll and show text and numbers
5+
- how to show built-in and custom images
6+
- how to turn individual pixels on and off
7+
- how to clear the display and turn it off and on
8+
39
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/eRhlaXqT-0w" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
410

511
The micro:bit display is a 5 × 5 grid of red LEDs that can show text, numbers, images and individual pixels at 10 brightness levels.

‎docs/microbit/light.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Light Sensor
22

3+
!!! learn "On this page we will learn"
4+
- how the micro:bit measures light with its display
5+
- how to read the light level
6+
37
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/ii0U_FMr-Z4" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
48

59
The micro:bit uses the LEDs on its display to measure how much light is shining on it.

‎docs/microbit/module.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# microbit Module
22

3+
!!! learn "On this page we will learn"
4+
- how to pause a program with `sleep()`
5+
- how to measure how long a program has been running
6+
- how to run code on a schedule with `run_every()`
7+
38
The `microbit` module contains general functions for pausing a program, measuring time and running code on a schedule.
49

510
Possible uses:

‎docs/microbit/radio.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,10 @@
11
# Radio
22

3+
!!! learn "On this page we will learn"
4+
- how the micro:bit radio works
5+
- how to turn the radio on and choose a group
6+
- how to send and receive messages between micro:bits
7+
38
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/rvymAr6WqrQ" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
49

510
The radio sends and receives short wireless messages between micro:bits.

‎docs/microbit/sound.md‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,11 @@
11
# Sound
22

3+
!!! learn "On this page we will learn"
4+
- how to write notes for tunes
5+
- how to play built-in and custom tunes and tones
6+
- how to make the micro:bit speak and sing
7+
- how to measure sound with the microphone
8+
39
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/r53PjFwyAhw" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
410

511
The micro:bit v2 has a built-in speaker that plays tunes, tones and robotic speech, and a microphone that measures how loud it is.

‎docs/microbit/temperature.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Temperature
22

3+
!!! learn "On this page we will learn"
4+
- how to read the temperature
5+
- why the reading is only approximate
6+
37
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/mrHn8eZ9eqg" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" allowfullscreen></iframe>
48

59
The temperature sensor inside the micro:bit's processor gives an approximate reading of the air temperature in degrees Celsius.

0 commit comments

Comments
 (0)