pxt-microbit Accessibility PR (#529)

* Accessibility changes

docs/device/crocodile-clips.md

@@ -1,16 +1,16 @@
-# crocodile clips
+# Crocodile clips
 
 The large holes at the bottom of the board are designed to attach alligator/crocodile clips 
 to create electrical circuit with other components.
 
 # ~hint
 
-**No crocodile clips!?!?!** Use wires or Aluminium foil! [Read more...](/device/foil-circuits)
+**No crocodile clips!?!?!** Use [wires or aluminium foil](/device/foil-circuits)!
 
 # ~
 
 
-## Connecting Crocodile Clips
+## Connecting crocodile clips
 
 The hole for ``P0`` and ``GND`` allow to grab the board on the side which makes for a great grip.
 

docs/device/error-codes.md

@@ -22,6 +22,6 @@ basic.showLeds(`
     `)
 ```
 
-### See also
+## See also
 
 [panic](/reference/control/panic), [assert](/reference/control/assert),

docs/device/foil-circuits.md

@@ -8,14 +8,14 @@ We will show you how to connect the @boardname@ to headphones using Alumunium fo
 
 https://youtu.be/mhXYyPuvpz0
 
-### Materials
+## Materials
 
 * @boardname@ and battery pack (you can also power it via USB)
 * a small piece of cardboard
 * Aluminium foil
 * tape
 
-### Assembly instructions
+## Assembly instructions
 
 Tape the @boardname@ and battery pack to the card board. Make sure to remove the batteries while you are building your circuit.
 

docs/device/pins.md

@@ -8,7 +8,7 @@ The micro:bit has 25 external connections on the edge connector of the board, wh
 
 There are five large pins, that are also connected to holes in the board labelled: 0, 1, 2, 3V, and GND. And along the same edge, there are 20 small pins that you can use when plugging the micro:bit into an edge connector.
 
-### Large pins
+## Large pins
 
 You can easily attach crocodile clips or 4mm banana plugs to the five large pins.
 
@@ -20,11 +20,11 @@ The first three, labelled 0, 1 and 2 are flexible and can be used for many diffe
 
 The other two large pins (3V and GND) are very different!/td/td
 
-### ~hint 
+## ~hint 
 
 Watch out! The pins labelled 3V and GND relate to the power supply of the board, and they should NEVER be connected together.
 
-### ~
+## ~
 
 *power input*: If the micro:bit is powered by USB or a battery, then you can use the 3V pin as a *power output* to power peripherals with.
 
@@ -33,7 +33,7 @@ Watch out! The pins labelled 3V and GND relate to the power supply of the board,
 
 If you hold the ‘GND’ pin with one hand, you can program the microbit to detect yourself touching the 0,1 or 2 pins with your other hand, giving you three more buttons to experiment with (you just used your body to complete an electrical circuit).
 
-### Small pins
+## Small pins
 
 There are 20 small pins numbered sequentially from 3-22 (these pins are not labeled on the micro:bit, however, they are labelled in the picture above).
 
@@ -57,7 +57,7 @@ Unlike the three large pins that are dedicated to being used for external connec
 * **pins 19 and 20**: implement the clock signal (SCL) and data line (SDA) of the I2C bus communication protocol. With I2C, several devices can be connected on the same bus and send/read messages to and from the CPU. Internally, the accelerometer and the compass are connected to i2c.
 * **pins 21 and 22**: these pins are wired to the GND pin and serve no other function
 
-### Connecting to the small pins
+## Connecting to the small pins
 
 It is recommended that an edge connector be acquired to connect to the small pins. More information on compatible edge connectors will be available later.
 

docs/device/reactive.md

@@ -1,18 +1,18 @@
 # The micro:bit - a reactive system
 
-### Computing systems
+## Computing systems
 
 What sort of a *computing system* is the micro:bit?
 
-### ~hint 
+## ~hint 
 
 There are different types of computing systems, to address different kinds of problems that arise in practice: *transaction processing systems* are used by banks to handle huge numbers of financial transactions by their customers; *distributed systems* make a set of networked computers appear as one big computer (like Google’s search engine); there are also *parallel systems*, such as graphic cards, which perform a huge number of primitive operations simultaneously, using a great number of small processing cores.
 
-### ~
+## ~
 
 The micro:bit is a *reactive system* – it reacts continuously to external events, such as a person pressing the A button of the micro:bit or shaking the device. The reaction to an event may be to perform a computation, update variables, and change the display.  After the device reacts to an event, it is ready to react to the next one. If this sounds like a computer game, that’s because most computer games are reactive systems too!
 
-### Responsiveness
+## Responsiveness
 
 We want reactive systems to be responsive, which means to react in a timely manner to events. For example, when you play a computer game, it’s frustrating if you press a button to make a character jump, but it doesn’t immediately jump.  A delay in reacting, or lack of responsiveness , can be the difference between life and death, both in the real and virtual worlds.
 
@@ -20,7 +20,7 @@ Let’s consider a simple example: you want to program your micro:bit to accurat
 
 Let’s say that the current count is 42 and the number 42 is scrolling across the LED screen. This means there is some code executing to perform the scroll.  So, what should happen if you press the A button during the scroll?  It would be a bad idea to ignore the button press, so some code should record the occurrence of the button press. But we just said there already is code running in order to scroll the number 42!  If we wait until the code scrolling the 42 has finished to look for a button press, we will miss the button press.  We want to avoid this sort of unresponsiveness.
 
-### Concurrency
+## Concurrency
 
 To be responsive, a reactive system needs to be able to do several things at the same time (concurrently), just like you can.  But the micro:bit only has one CPU for executing your program, which means it can only execute one program instruction at a time. On the other hand, it can execute millions of instructions in a single second.  This points the way to a solution.
 
@@ -42,7 +42,7 @@ TODO Diagram
 
 As we’ll soon see, there are other choices for how the sequences can be ordered to achieve the desired result.
 
-### The micro:bit scheduler and queuing up subprograms
+## The micro:bit scheduler and queuing up subprograms
 
 The micro:bit’s *scheduler* provides the capability to concurrently execute different code sequences, relieving us of a lot of low-level programming.   In fact, scheduling is so useful that it is a part of every *operating system*!
 
@@ -90,7 +90,7 @@ The function ends after the execution of these three statements, but this is not
 
 The second job of the scheduler is to periodically interrupt execution to read (poll) the various inputs to the micro:bit (the buttons, pins, etc.) and fire off events (such as “button A pressed”). Recall that the firing of an event causes the event handler subprogram associated with that event to be queued for later execution. The scheduler uses a timer built into the micro:bit hardware to interrupt execution every 6 milliseconds and poll the inputs, which is more than fast enough to catch the quickest press of a button.
 
-### Cooperative passing of control
+## Cooperative passing of control
 
 How does the forever loop get to start execution? Furthermore, once the forever loop is running, how does any other subprogram (like the event handler that increments the count) ever get a chance to execute?
 
@@ -117,7 +117,7 @@ The `forever` loop actually is a function that takes a subprogram (an *Action* i
 
 Though the `while true` loop will repeatedly execute the body subprogram, between each execution of the body it will permit the scheduler to execute other subprograms.  If the while loop did not contain the call to `pause`, then once control passed into the while loop, it would never pass back to the scheduler and no other subprogram would be able to execute (unless the body subprogram contained a call to `pause` itself).
 
-### Round-robin scheduling
+## Round-robin scheduling
 
 Now, we come to the third and final job of the scheduler, which is to determine which subprogram to pass control to next. The scheduler uses two queues to perform this task, the sleep queue and the run queue. The sleep queue contains the subprograms that have called the pause function and still have time left to sleep. The run queue contains all the non-sleeping subprograms, such as the event handlers queued by the firing of an event.
 
@@ -125,7 +125,7 @@ The scheduler  moves the subprogram that has just paused into the sleep queue an
 
 The property of such round-robin scheduling is that under the assumption that every subprogram periodically enters the sleep queue, then every subprogram will periodically get a chance to execute.
 
-### Putting it all together
+## Putting it all together
 
 Let’s go back to the `count button presses` function and revisit its execution based on what we have learned about the micro:bit scheduler. As detailed before, the function executes three steps to: (1) set up the event handler for each press of button A; (2) queue the forever loop to the run queue; (3) initialize the global variable `count` to zero.
 
@@ -135,7 +135,7 @@ The function then ends execution and control passes back to the scheduler.  Let
 
 While "Show 0" (the blue sequence) is running, periodic interrupts by the scheduler (every 6 milliseconds) poll for button presses and queue an event handler for each press of button A.  Let’s say that one button press takes place during this time, as shown above. This will cause an event handler (labelled “inc”) to be queued for later execution by the scheduler. Once the "Show 0" has completed, the loop then calls `basic -> pause(20)` to put the forever loop to sleep for 20 milliseconds and give the scheduler an opportunity to run any newly queued event handler. Control passes to the “inc” event handler which will increment the global variable `count` from 0 to 1 and then complete, returning control to the scheduler.  At some point, the `forever` loop moves from the sleep queue to the run queue; the `forever` loop then will resume and call `basic -> show number(1,150)`.
 
-### Final thoughts
+## Final thoughts
 
 Through this example, we have seen that the micro:bit scheduler enables you to create a program that is composed of concurrent subprograms. In essence, the programmer needs to only think about the concurrent subprograms cooperatively passing control back to the scheduler, making sure no subprogram hogs control (or “dribbles the ball without passing”) for too long. While a subprogram runs, the scheduler polls the buttons and other IO peripherals at a high frequency in order to fire off events and queue event handlers for later execution, but this is invisible to the programmer.
 

docs/device/screen.md

@@ -15,7 +15,7 @@ The micro:bit LED screen
 The micro:bit LED screen consists of 25 red LED lights arranged in a 5X5 grid (5 LEDs across by 5 LEDs down).
 In the screen above, we created a checkerboard pattern using the LEDs.
 
-### Which LED?
+## Which LED?
 
 You use `(x ,y)` coordinates to specify a particular LED in the grid; 
 where `x` is the horizontal position (0,1,2,3,4) and `y` is the vertical position 
@@ -37,17 +37,17 @@ Here are the x, y coordinates for the LEDs in the 5X5 grid:
 
 The x, y coordinates for the LED in the centre of the grid are `(2,2)`. Starting from `(0,0)` count over 2 columns and then down 2 rows.
 
-### Check your understanding
+## Check your understanding
 
 Which LEDs are turned on in the checkboard pattern above? 
 
-### Row, column - 1
+## Row, column - 1
 
 Since the row and column numbers start at 0, an easy way to figure out the (x,y) coordinates 
 is to subtract 1 from the row and column number (when counting from 1). 
 In other words, to specify the LED in the 4th column 5th row, subtract 1 from each number to get coordinates `(3,4)`.
 
-### Turn a LED on/off
+## Turn a LED on/off
 
 Use [plot](/reference/led/plot) and [unplot](/reference/led/unplot) to turn a LED on or off
 
@@ -60,7 +60,7 @@ basic.pause(1000);
 led.unplot(1,1);
 ```
 
-### Is a LED on/off?
+## Is a LED on/off?
 
 Use the [point](/reference/led/point) function to find out if a LED is on or off.
 
@@ -69,11 +69,11 @@ if(led.point(0,0)) {
 }
 ```
 
-### Display images, strings and numbers
+## Display images, strings and numbers
 
 Instead of turning individual LEDs on or off, as above, you can display an [image](/reference/images/image) directly to the screen or show text/numbers on screen using the [show number](/reference/basic/show-number)/[show string](/reference/basic/show-string) function.
 
-### The display buffer
+## The display buffer
 
 The micro:bit runtime keeps an in-memory representation of the state of all 25 LEDS. This state is known as the "display buffer" and controls which LEDS are on and which are off. The plot/unplot/point functions access the display buffer directly. On the other hand, the functions that show an image, number or string overwrite the buffer completely. To illustrate, first try running this code sequence
 
@@ -92,7 +92,7 @@ basic.showString("d", 150)
 You will not see the LED at position `0,0` lit up because the `show string` function overwrites the whole display buffer.
 
 
-### Pins: P3, P4, P6, P7, P9, P10
+## Pins: P3, P4, P6, P7, P9, P10
 
 These pins are coupled to the LED matrix display, and also it’s associated ambient light sensing mode.
 To disable the display driver feature (which will automatically disable the light sensing feature) use the function [led.enable](/reference/led/enable). 

docs/device/serial.md

@@ -24,7 +24,6 @@ basic.forever(() => {
 
 Unfortunately, using the serial library requires quite a bit of a setup.
 
-
 ### ~ hint
 
 **Windows earlier than 10**
@@ -34,7 +33,7 @@ If you are running a Windows version earlier than 10, you must install a device
 
 * Follow the instructions at https://docs.mbed.com/docs/mbed-os-handbook/en/latest/getting_started/what_need/ to install the device driver.
 
-### ~
+## ~
 
 ### Chrome Extension
 
@@ -73,7 +72,7 @@ If you prefer another terminal emulator (such as [PuTTY](http://www.putty.org/))
 
 ![](/static/mb/serial-library-1.png)
 
-### Linux
+## Linux
 
 * Install the program `screen` if it is not already installed.
 * Plug in the micro:bit.
@@ -86,7 +85,7 @@ If you prefer another terminal emulator (such as [PuTTY](http://www.putty.org/))
 
 Alternative programs include `minicom` and so on.
 
-### Mac OS
+## Mac OS
 
 * Plug in the micro:bit
 * Open a terminal

docs/device/servo.md

@@ -1,10 +1,10 @@
 # Equipping a microservo with Crocodile clips
 
-### ~ hint
+## ~ hint
 
 If you are running a class or activity, you should consider preparing all servos before hand.
 
-### ~
+## ~
 
 ## Using a microservo with the @boardname@
 
@@ -20,7 +20,7 @@ and a **Male jumper (pig tail)** on the other end. You can purchase bundles of s
 
 https://youtu.be/XtzsydSTXEg
 
-### Materials
+## Materials
 
   * 1 Crocodile clip cable
   * 1 male (pig tail) cable
@@ -29,13 +29,13 @@ https://youtu.be/XtzsydSTXEg
 
 Simple cut the cables, strip them, thread the cables together and cover with the shrink wrap.
 
-### ~ hint
+## ~ hint
 
 It is very **important** to ensure that there is a good connection between the 2 cables.
 If the connection is weak, the microservo will not receive enough current and it will not work.
 **If you have access to a soldering iron, we strongly recommend to solder this connection.**
 
-### ~
+## ~
 
 
 ## Direct connection
@@ -48,32 +48,32 @@ You can also connect your crocodile clips directly to the servo.
   * 3 crocodile clips, yellow, red and black.
   * 1 micro servo 9g (SG90)
 
-### Step 1: cutout the connector
+## Step 1: cutout the connector
 
 Using the cutting pliers, cut out the dark plastic connector.
 
 ![](/static/mb/projects/inchworm/servo1.jpg)
 
-### Step 2: strip out cables
+## Step 2: strip out cables
 
 Using the plier or a wire stripper, strip the plastic from the cables.
 
 ![](/static/mb/projects/inchworm/servotrim.jpg)
 
-### Step 3: threading the servo cablers
+## Step 3: threading the servo cablers
 
 Thread the servo cables.
 
 ![](/static/mb/projects/inchworm/servo3.jpg)
 
-### Step 4: crocobile clip
+## Step 4: crocobile clip
 
 Cut a crocodile cable in two and strip out the casing. 
 If possible try to use the same cable colors as the servo!
 
 ![](/static/mb/projects/inchworm/servo4.jpg)
 
-### Step 5: thread cables together
+## Step 5: thread cables together
 
 Place the cables next to each other
 
@@ -83,27 +83,27 @@ Place the cables next to each other
 
 ![](/static/mb/projects/inchworm/servo6.jpg)
 
-### ~ hint
+## ~ hint
 
 It is very **important** to ensure that there is a good connection between the 2 cables.
 If the connection is weak, the microservo will not receive enough current and it will not work.
 **If you have access to a soldering iron, we strongly recommend to solder this connection.**
 
-### ~
+## ~
 
-### Step 4: protect the connection
+## Step 4: protect the connection
 
 Protect the connection with shrinkwrap tubes, electrical or duct tape.
 
 ![](/static/mb/projects/inchworm/servo7.jpg)
 
-### Step 5: repeat for all cables
+## Step 5: repeat for all cables
 
 Repeat the same process until all cables are connected.
 
 ![](/static/mb/projects/inchworm/servo8.jpg)
 
-### Step 6: testing!
+## Step 6: testing!
 
 It's time to test that your connection are all proper and that the servo will function **when the @boardname@ is powered by battery**.
 
@@ -111,13 +111,13 @@ It's time to test that your connection are all proper and that the servo will fu
 
 ![](/static/mb/projects/inchworm/circuit1.jpg)
 
-### ~ hint
+## ~ hint
 
 When attaching the crocodile clips to the pins, don't hesitate to grab the side of the board with the jaws.
 
 ![](/static/mb/projects/inchworm/circuit2.jpg)
 
-### ~
+## ~
 
 * Download the following code to your @boardname@
 

docs/device/usb.md

@@ -16,21 +16,21 @@ The basic steps are:
 
 Here are instructions for different browsers on Windows and Mac computers. Choose the one you're using:
 
-#### Windows browsers
+### Windows browsers
 
 * [Microsoft Edge](/device/usb/windows-edge)
 * [Internet Explorer](/device/usb/windows-ie)
 * [Chrome](/device/usb/windows-chrome)
 * [Firefox](/device/usb/windows-firefox)
 
-#### Mac browsers
+### Mac browsers
 
 * [Safari](/device/usb/mac-safari)
 * [Chrome](/device/usb/mac-chrome)
 * [Firefox](/device/usb/mac-firefox)
 
-### ~hint
+## ~hint
 
 Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
 
-### ~
+## ~

docs/device/usb/mac-chrome.md

@@ -62,8 +62,8 @@ flash memory on the micro:bit, which means even after you unplug the micro:bit,
 your program will still run if the micro:bit is powered by battery.
 
 
-### ~hint
+## ~hint
 
 Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
 
-### ~
+## ~

docs/device/usb/mac-firefox.md

@@ -64,8 +64,8 @@ By copying the script onto the `MICROBIT` drive, you have programmed it into the
 flash memory on the micro:bit, which means even after you unplug the micro:bit,
 your program will still run if the micro:bit is powered by battery.
 
-### ~hint
+## ~hint
 
 Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
 
-### ~
+## ~

docs/device/usb/mac-safari.md

@@ -61,8 +61,8 @@ flash memory on the micro:bit, which means even after you unplug the micro:bit,
 your program will still run if the micro:bit is powered by battery.
 
 
-### ~hint
+## ~hint
 
 Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
 
-### ~
+## ~

docs/device/usb/windows-chrome.md

@@ -53,7 +53,7 @@ You only need to do this once.
 
 If the file was saved onto your computer, you will need to transfer it to the micro:bit.
 
-### Manual transfer
+## Manual transfer
 
 Your `.hex` file (created in Step 3 above) appears as a download at the bottom of the browser.
 Click on the arrow next to the name of the file and then click **Show in folder**.
@@ -66,7 +66,7 @@ Alternatively, right-click on the hex file, choose **Send to**, and then **MICRO
 
 ![](/static/mb/device/usb-windows-sendto.jpg)
 
-### micro:bit uploader
+## micro:bit uploader
 
 You can use the [micro:bit uploader](/uploader) to automatically deploy ``.hex`` files to your micro:bit!
 ![](/static/uploader/tooltip.png)
@@ -82,8 +82,8 @@ You can use the [micro:bit uploader](/uploader) to automatically deploy ``.hex``
    flash memory on the micro:bit, which means even after you unplug the micro:bit,
    your program will still run if the micro:bit is powered by battery.
 
-### ~hint
+## ~hint
 
 Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
 
-### ~
+## ~

docs/device/usb/windows-edge.md

@@ -60,8 +60,8 @@ By copying the script onto the `MICROBIT` drive, you have programmed it into the
 flash memory on the micro:bit, which means even after you unplug the micro:bit,
 your program will still run if the micro:bit is powered by battery.
 
-### ~hint
+## ~hint
 
 Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
 
-### ~
+## ~

docs/device/usb/windows-firefox.md

@@ -57,8 +57,8 @@ By copying the script onto the `MICROBIT` drive, you have programmed it into the
 flash memory on the micro:bit, which means even after you unplug the micro:bit,
 your program will still run if the micro:bit is powered by battery.
 
-### ~hint
+## ~hint
 
 Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
 
-### ~
+## ~

docs/device/usb/windows-ie.md

@@ -59,8 +59,8 @@ flash memory on the micro:bit, which means even after you unplug the micro:bit,
 your program will still run if the micro:bit is powered by battery.
 
 
-### ~hint
+## ~hint
 
 Transfer not working? See some [troubleshooting tips](/device/usb/troubleshooting).
 
-### ~
+## ~