From a0a23a261c8078b3f3edd4b676e4f6e915baa0f7 Mon Sep 17 00:00:00 2001
From: Tom Ball <tball@microsoft.com>
Date: Tue, 14 Jun 2016 17:20:45 -0400
Subject: [PATCH] restructuring to separate language from API

---
 docs/blocks.md                                |  2 +-
 docs/{reference => blocks}/logic.md           |  0
 docs/blocks/logic/if.md                       | 28 +++++++++++++
 docs/{reference => blocks}/loops.md           |  0
 docs/{reference => blocks}/loops/for.md       |  2 +-
 docs/{reference => blocks}/loops/repeat.md    |  2 +-
 docs/{reference => blocks}/loops/while.md     |  2 +-
 docs/{reference => blocks}/math.md            |  0
 docs/{reference => blocks}/math/math.md       | 10 +----
 docs/{reference => blocks}/variables.md       |  4 +-
 .../{reference => blocks}/variables/assign.md |  4 +-
 docs/blocks/variables/change-var.md           | 40 +++++++++++++++++++
 docs/{reference => blocks}/variables/var.md   |  6 +--
 docs/device/usb.md                            |  3 +-
 docs/projects/banana-keyboard.md              |  2 +-
 docs/projects/compass.md                      |  6 ---
 docs/projects/flashing-heart.md               |  6 +--
 docs/projects/rock-paper-scissors.md          |  2 -
 docs/projects/smiley-buttons.md               |  2 +-
 docs/projects/telegraph-challenges.md         | 10 ++---
 docs/reference/basic/forever.md               |  2 +-
 docs/reference/basic/pause.md                 |  2 +-
 docs/reference/basic/show-number.md           |  4 +-
 docs/reference/control/in-background.md       |  2 +-
 docs/reference/game/game-library.md           | 20 +++++-----
 docs/reference/images/image.md                |  6 +--
 docs/reference/images/show-image.md           |  2 +-
 docs/reference/images/width.md                |  2 +-
 docs/reference/input/button-is-pressed.md     |  4 +-
 docs/reference/input/on-button-pressed.md     |  2 +-
 docs/reference/led/plot.md                    |  2 +-
 docs/reference/logic/if.md                    | 28 -------------
 docs/reference/types.md                       | 10 ++---
 docs/reference/types/boolean.md               |  4 +-
 docs/reference/types/string.md                | 25 +++++++-----
 docs/reference/variables/change-var.md        | 40 -------------------
 olddocs/js/assign.md                          |  4 +-
 olddocs/js/boolean.md                         |  2 +-
 olddocs/js/comment.md                         |  9 +----
 pxtarget.json                                 |  4 ++
 40 files changed, 141 insertions(+), 164 deletions(-)
 rename docs/{reference => blocks}/logic.md (100%)
 create mode 100644 docs/blocks/logic/if.md
 rename docs/{reference => blocks}/loops.md (100%)
 rename docs/{reference => blocks}/loops/for.md (67%)
 rename docs/{reference => blocks}/loops/repeat.md (50%)
 rename docs/{reference => blocks}/loops/while.md (90%)
 rename docs/{reference => blocks}/math.md (100%)
 rename docs/{reference => blocks}/math/math.md (79%)
 rename docs/{reference => blocks}/variables.md (50%)
 rename docs/{reference => blocks}/variables/assign.md (82%)
 create mode 100644 docs/blocks/variables/change-var.md
 rename docs/{reference => blocks}/variables/var.md (90%)
 delete mode 100644 docs/reference/logic/if.md
 delete mode 100644 docs/reference/variables/change-var.md

diff --git a/docs/blocks.md b/docs/blocks.md
index 1fe0d632..491483e0 100644
--- a/docs/blocks.md
+++ b/docs/blocks.md
@@ -1,6 +1,6 @@
 # Blocks language
 
-```namspaces
+```namespaces
 for (let i = 0;i<5;++i) {}
 if (true){}
 let x = 0;
diff --git a/docs/reference/logic.md b/docs/blocks/logic.md
similarity index 100%
rename from docs/reference/logic.md
rename to docs/blocks/logic.md
diff --git a/docs/blocks/logic/if.md b/docs/blocks/logic/if.md
new file mode 100644
index 00000000..82c7da3e
--- /dev/null
+++ b/docs/blocks/logic/if.md
@@ -0,0 +1,28 @@
+# If
+
+### @parent blocks/language
+ 
+
+Conditionally run code depending on whether a [Boolean](/reference/types/boolean) condition is true or false.
+
+```blocks
+if(true) {
+}
+```
+
+Click on the dark blue gear icon (see above) to add an *else* or *if* to the current block.
+
+### Example: adjusting screen brightness
+
+```blocks
+if(input.lightLevel()<100){
+    led.setBrightness(255);
+}
+```
+
+If the [light level](/reference/input/light-level) is `< 100`, this code sets the brightness to `255`:
+
+### See also
+
+[while loop](/blocks/loops/while), [for](/blocks/loops/for), [boolean](/reference/types/boolean)
+
diff --git a/docs/reference/loops.md b/docs/blocks/loops.md
similarity index 100%
rename from docs/reference/loops.md
rename to docs/blocks/loops.md
diff --git a/docs/reference/loops/for.md b/docs/blocks/loops/for.md
similarity index 67%
rename from docs/reference/loops/for.md
rename to docs/blocks/loops/for.md
index 9875ade3..67fb7c00 100644
--- a/docs/reference/loops/for.md
+++ b/docs/blocks/loops/for.md
@@ -16,5 +16,5 @@ basic.showNumber(i)
 
 ### See also
 
-[repeat](/reference/loops/repeat), [while](/reference/loops/while), [if](/reference/logic/if), [show number](/reference/basic/show-number)
+[repeat](/blocks/loops/repeat), [while](/blocks/loops/while), [if](/blocks/logic/if), [show number](/reference/basic/show-number)
 
diff --git a/docs/reference/loops/repeat.md b/docs/blocks/loops/repeat.md
similarity index 50%
rename from docs/reference/loops/repeat.md
rename to docs/blocks/loops/repeat.md
index 07bdc198..a76c052f 100644
--- a/docs/reference/loops/repeat.md
+++ b/docs/blocks/loops/repeat.md
@@ -8,5 +8,5 @@ Run part of the program the number of times you say.
 
 ### See also
 
-[for](/reference/loops/for), [while](/reference/loops/while), [if](/reference/logic/if), [show number](/reference/basic/show-number)
+[for](/blocks/loops/for), [while](/blocks/loops/while), [if](/blocks/logic/if), [show number](/reference/basic/show-number)
 
diff --git a/docs/reference/loops/while.md b/docs/blocks/loops/while.md
similarity index 90%
rename from docs/reference/loops/while.md
rename to docs/blocks/loops/while.md
index 4b0854e0..1b1c6867 100644
--- a/docs/reference/loops/while.md
+++ b/docs/blocks/loops/while.md
@@ -28,5 +28,5 @@ while(index >= 0) {
 
 ### See also
 
-[on button pressed](/reference/input/on-button-pressed), [for](/reference/loops/for), [if](/reference/logic/if), [forever](/reference/basic/forever)
+[on button pressed](/reference/input/on-button-pressed), [for](/blocks/loops/for), [if](/blocks/logic/if), [forever](/reference/basic/forever)
 
diff --git a/docs/reference/math.md b/docs/blocks/math.md
similarity index 100%
rename from docs/reference/math.md
rename to docs/blocks/math.md
diff --git a/docs/reference/math/math.md b/docs/blocks/math/math.md
similarity index 79%
rename from docs/reference/math/math.md
rename to docs/blocks/math/math.md
index 26219a82..c159830b 100644
--- a/docs/reference/math/math.md
+++ b/docs/blocks/math/math.md
@@ -1,15 +1,9 @@
-# Math Library
-
-Functions in the math library.
+# Math functions
 
 ### @parent blocks/language
 
 The math library includes math related functions that you can use with [Numbers](/reference/types/number).
 
-* In the [Block editor](/blocks/editor), click **maths** on the left to see the available blocks
-
-The functions available in Block Editor are:
-
 ### abs
 
 math `->` abs (x : [Number](/reference/types/number)) *returns* [Number](/reference/types/number)
@@ -44,5 +38,5 @@ returns a random [Number](/reference/types/number) between 0 and the parameter *
 
 ### See also
 
-[Block Editor documentation](/blocks/contents), [Number](/reference/types/number)
+[Number](/reference/types/number)
 
diff --git a/docs/reference/variables.md b/docs/blocks/variables.md
similarity index 50%
rename from docs/reference/variables.md
rename to docs/blocks/variables.md
index 2a404ba0..e4b5c0ed 100644
--- a/docs/reference/variables.md
+++ b/docs/blocks/variables.md
@@ -1,6 +1,6 @@
 ## Variables
 
-[Assign](/reference/variables/assign) (set) a variable's value
+[Assign](/blocks/variables/assign) (set) a variable's value
 
 ```blocks
 let x = 0;
@@ -13,7 +13,7 @@ let x = 0;
 x;
 ```
 
-[Change](/reference/variables/change-var) a variable's value
+[Change](/blocks/variables/change-var) a variable's value
 
 ```blocks
 let x = 0;
diff --git a/docs/reference/variables/assign.md b/docs/blocks/variables/assign.md
similarity index 82%
rename from docs/reference/variables/assign.md
rename to docs/blocks/variables/assign.md
index dc97c693..11375c09 100644
--- a/docs/reference/variables/assign.md
+++ b/docs/blocks/variables/assign.md
@@ -1,6 +1,6 @@
 # Assignment Operator
 
-Use an equals sign to make a [variable](/reference/variables/var) store the [number](/reference/types/number) 
+Use an equals sign to make a [variable](/blocks/variables/var) store the [number](/reference/types/number) 
 or [string](/reference/types/string) you say.
 
 When you use the equals sign to store something in a variable, the equals sign is called
@@ -32,5 +32,5 @@ a variable can store, like a number or string.
 
 ### See also
 
-[variable](/reference/variables/var), [types](/reference/types)
+[variable](/blocks/variables/var), [types](/reference/types)
 
diff --git a/docs/blocks/variables/change-var.md b/docs/blocks/variables/change-var.md
new file mode 100644
index 00000000..8b79b4cd
--- /dev/null
+++ b/docs/blocks/variables/change-var.md
@@ -0,0 +1,40 @@
+# Change Value
+
+Set the value for local and global variables.
+
+### @parent blocks/change-value
+
+Change the value of a variable
+
+```blocks
+let x = 0
+x += 1
+```
+
+### Declare a variable
+
+Use the assignment operator to set the value of a [variable](/blocks/variables/var). Change the value of a variable from 0 to 1 using the change item block. Like this:
+
+```blocks
+let x = 0
+x += 1
+```
+
+### Example
+
+Use the assignment operator to set the value of a [variable](/blocks/variables/var). Change the value of a variable from 0 to 1 using the change item block. Then display the new value of the variable on the LED screen. Like this:
+
+```blocks
+let x = 0;
+x += 1;
+basic.showNumber(x);
+```
+
+### Notes
+
+* You can use the assignment operator with variables of each of the supported [types](/reference/types).
+
+### See also
+
+[variable](/blocks/variables/var), [types](/reference/types)
+
diff --git a/docs/reference/variables/var.md b/docs/blocks/variables/var.md
similarity index 90%
rename from docs/reference/variables/var.md
rename to docs/blocks/variables/var.md
index cb0fcfc2..f12a81b5 100644
--- a/docs/reference/variables/var.md
+++ b/docs/blocks/variables/var.md
@@ -13,7 +13,7 @@ A variable is a place where you can store and retrieve data. Variables have a na
 ### Var statement
 
 Use the Block Editor variable statement to create a variable 
-and the [assignment operator](/reference/variables/assign) 
+and the [assignment operator](/blocks/variables/assign) 
 to store something in the variable.
 
 For example, this code stores the number `2` in the `x` variable:
@@ -27,7 +27,7 @@ Here's how to define a variable in the Block Editor:
 
 2. Change the default variable name if you like.
 
-3. Drag a block type on the right-side of the [assignment operator](/reference/variables/assign) and click the down arrow to change the variable name.
+3. Drag a block type on the right-side of the [assignment operator](/blocks/variables/assign) and click the down arrow to change the variable name.
 
 A variable is created for the number returned by the [brightness](/reference/led/brightness) function.
 
@@ -83,5 +83,5 @@ if (led.brightness() > 128) {
 
 ### See also
 
-[types](/reference/types), [assignment operator](/reference/variables/assign)
+[types](/reference/types), [assignment operator](/blocks/variables/assign)
 
diff --git a/docs/device/usb.md b/docs/device/usb.md
index 889e28fb..4cf1b877 100644
--- a/docs/device/usb.md
+++ b/docs/device/usb.md
@@ -2,7 +2,8 @@
 
 How to compile, transfer, and run a script on your micro:bit.
 
-While you're writing and testing your Block Editor or Touch Develop scripts, you'll mostly be running scripts in your browser by clicking the `Run` button (see [run code in your browser](/device/simulator) for info about this).
+While you're writing and testing your scripts, you'll mostly be running scripts in your browser by clicking the `PLay` button 
+(see [run code in your browser](/device/simulator) for info about this).
 
 Once your masterpiece is complete, you can compile your script and run it on your micro:bit.
 
diff --git a/docs/projects/banana-keyboard.md b/docs/projects/banana-keyboard.md
index 0710629c..3685f347 100644
--- a/docs/projects/banana-keyboard.md
+++ b/docs/projects/banana-keyboard.md
@@ -95,6 +95,6 @@ Tap your banana instrument to play sound against... the fruit!
 
 ### ~avatar boothing
 
-Excellent, you're ready to continue with the [challenges](/banana-keyboard-challenges)!
+Excellent, you're ready to continue with the [challenges](/projects/banana-keyboard-challenges)!
 
 ### ~
diff --git a/docs/projects/compass.md b/docs/projects/compass.md
index bb565db1..b8135280 100644
--- a/docs/projects/compass.md
+++ b/docs/projects/compass.md
@@ -104,9 +104,3 @@ basic.forever(() => {
 });
 ```
 
-### ~avatar avatar
-
-Excellent, you're ready to continue with the [challenges](/lessons/compass/challenges)!
-
-### ~
-
diff --git a/docs/projects/flashing-heart.md b/docs/projects/flashing-heart.md
index d4c54f50..7ab3d99f 100644
--- a/docs/projects/flashing-heart.md
+++ b/docs/projects/flashing-heart.md
@@ -21,13 +21,11 @@ basic.pause(500);
 Use the LEDs to display a flashing heart, and then create
 an animation of a broken heart. :(
 
-## [START PROJECT](/#follow:/projects/flashing-heart)
-
 ### ~
 
 ## Step 1
 
-Use [show leds](/reference/basic/showLeds) and make your code look like this:
+Use [show leds](/reference/basic/show-leds) and make your code look like this:
 
 ```blocks
 basic.showLeds(`
@@ -40,7 +38,7 @@ basic.showLeds(`
 
 ## Step 2
 
-Add a [pause](/reference/basic/pause) to wait and [clear screen](/reference/basic/clearScreen) to turn off the LEDs.
+Add a [pause](/reference/basic/pause) to wait and [clear screen](/reference/basic/clear-screen) to turn off the LEDs.
 
 ```blocks
 basic.showLeds(`
diff --git a/docs/projects/rock-paper-scissors.md b/docs/projects/rock-paper-scissors.md
index 15ae7f51..758a95f6 100644
--- a/docs/projects/rock-paper-scissors.md
+++ b/docs/projects/rock-paper-scissors.md
@@ -39,8 +39,6 @@ In this project, you will build a Rock Paper Scissors game with the BBC micro:bi
 You can play the game with a friend who has it on a micro:bit.
 You can also play it with friends who are just using their hands.
 
-## [START PROJECT](/#follow:/projects/rock-paper-scissors)
-
 ### ~
 
 
diff --git a/docs/projects/smiley-buttons.md b/docs/projects/smiley-buttons.md
index a6a795a9..537e82fa 100644
--- a/docs/projects/smiley-buttons.md
+++ b/docs/projects/smiley-buttons.md
@@ -6,7 +6,7 @@ Use buttons to show a smiley or frowny face.
 
 ## Step 1
 
-Use [show leds](/reference/basic/showLeds) to make a smiley face:
+Use [show leds](/reference/basic/show-leds) to make a smiley face:
 
 ```blocks
 basic.showLeds(`
diff --git a/docs/projects/telegraph-challenges.md b/docs/projects/telegraph-challenges.md
index 85c9e418..cf5a22fb 100644
--- a/docs/projects/telegraph-challenges.md
+++ b/docs/projects/telegraph-challenges.md
@@ -4,13 +4,9 @@ Build a telgraph.
 
 # micro:bit telegraph
 
-
-
-
 Have you ever tried to communicate through a telegraph? Let's try coding a "Telegraph" on two BBC micro:bits !
 
-
-Complete the following [guided tutorial](/lessons/telegraph/activity), your hack should look like this:
+Complete the following [guided tutorial](/projects/telegraph), your hack should look like this:
 
 ![](/static/mb/lessons/telegraph-0.png)
 
@@ -109,6 +105,6 @@ Your telegraph is ready!
 
 ### Step 7
 
-* Connect the first micro:bit to your computer using your USB cable and run the [telegraph](/nnudbr) script on it.
-* Connect the second micro:bit to your computer using your USB cable and run the [telegraph](/nnudbr) script on it.
+* Connect the first micro:bit to your computer using your USB cable and put the telegraph script on it.
+* Connect the second micro:bit to your computer using your USB cable and run the telegraph script on it.
 * The first person and second person take turns pressing button A to play the telegraph game!
diff --git a/docs/reference/basic/forever.md b/docs/reference/basic/forever.md
index 3cf9bbe2..b961e426 100644
--- a/docs/reference/basic/forever.md
+++ b/docs/reference/basic/forever.md
@@ -65,5 +65,5 @@ input.onButtonPressed(Button.A, () => {
 
 ### See also
 
-[while](/reference/loops/while), [on button pressed](/reference/input/on-button-pressed), [in background](/reference/control/in-background)
+[while](/blocks/loops/while), [on button pressed](/reference/input/on-button-pressed), [in background](/reference/control/in-background)
 
diff --git a/docs/reference/basic/pause.md b/docs/reference/basic/pause.md
index 50d500a4..887df9cb 100644
--- a/docs/reference/basic/pause.md
+++ b/docs/reference/basic/pause.md
@@ -26,5 +26,5 @@ for (let i = 0; i < 5; i++) {
 
 ### See also
 
-[while](/reference/loops/while), [running time](/reference/input/running-time), [for](/reference/loops/for)
+[while](/blocks/loops/while), [running time](/reference/input/running-time), [for](/blocks/loops/for)
 
diff --git a/docs/reference/basic/show-number.md b/docs/reference/basic/show-number.md
index 068cb285..ef741701 100644
--- a/docs/reference/basic/show-number.md
+++ b/docs/reference/basic/show-number.md
@@ -28,7 +28,7 @@ basic.showNumber(x)
 
 ### Example: count to 5
 
-This example uses a [for](/reference/loops/for) loop to show numbers ``0`` through ``5`` on the screen:
+This example uses a [for](/blocks/loops/for) loop to show numbers ``0`` through ``5`` on the screen:
 
 ~~~~blocks
 for (let i = 0; i < 6; i++) {
@@ -44,5 +44,5 @@ for (let i = 0; i < 6; i++) {
 
 ### See also
 
-[show string](/reference/basic/show-string), [show animation](/reference/basic/show-animation), [Number](/reference/types/number), [math library](/reference/math)
+[show string](/reference/basic/show-string), [show animation](/reference/basic/show-animation), [Number](/reference/types/number), [math](/blocks/math)
 
diff --git a/docs/reference/control/in-background.md b/docs/reference/control/in-background.md
index f7b93be5..24aa8a9b 100644
--- a/docs/reference/control/in-background.md
+++ b/docs/reference/control/in-background.md
@@ -51,5 +51,5 @@ input.onButtonPressed(Button.A, () => {
 
 ### See also
 
-[while](/reference/loops/while), [forever](/reference/basic/forever), [on button pressed](/reference/input/on-button-pressed)
+[while](/blocks/loops/while), [forever](/reference/basic/forever), [on button pressed](/reference/input/on-button-pressed)
 
diff --git a/docs/reference/game/game-library.md b/docs/reference/game/game-library.md
index b4787937..fa818638 100644
--- a/docs/reference/game/game-library.md
+++ b/docs/reference/game/game-library.md
@@ -11,7 +11,7 @@ input.onButtonPressed(Button.A, () => {
 game.startCountdown(10000)
 ```
 
-### [Create sprite](/functions/game-library/create-sprite)
+### [Create sprite](/reference/game/create-sprite)
 
 Create sprite with x, y coordinates and returns a LED Sprite. Create a new LED sprite.
 
@@ -21,7 +21,7 @@ Create sprite with x, y coordinates and returns a LED Sprite. Create a new LED s
 export function createSprite(x: number, y: number) : micro_bitSprites.LedSprite
 ```
 
-### [Move](/functions/game-library/move)
+### [Move](/reference/game/move)
 
 Sprite move by a certain number
 
@@ -31,7 +31,7 @@ Sprite move by a certain number
 export function move(_this: micro_bitSprites.LedSprite, leds: number)
 ```
 
-### [Turn](/functions/game-library/turn)
+### [Turn](/reference/game/turn)
 
 Rotates a sprite to the right by a certain number of degrees
 
@@ -47,7 +47,7 @@ Rotates a sprite to the left by a certain number of degrees
 export function turnLeft(_this: micro_bitSprites.LedSprite, degrees: number)
 ```
 
-### [Change](/functions/game-library/change)
+### [Change](/reference/game/change)
 
 Sprite will change the x position by this number
 
@@ -63,7 +63,7 @@ Sprite will change the y position by this number
 export function changeYBy(_this: micro_bitSprites.LedSprite, y: number)
 ```
 
-### [Set](/functions/game-library/set)
+### [Set](/reference/game/set)
 
 Sprite will change the x position by this number
 
@@ -79,7 +79,7 @@ Sprite will change the y position by this number
 export function changeYBy(_this: micro_bitSprites.LedSprite, y: number)
 ```
 
-### [If on edge, bounce](/functions/game-library/if-on-edge-bounce)
+### [If on edge, bounce](/reference/game/if-on-edge-bounce)
 
 Sprite - If the sprite is on the edge, the sprite will bounce
 
@@ -89,7 +89,7 @@ Sprite - If the sprite is on the edge, the sprite will bounce
 export function ifOnEdge_Bounce(_this: micro_bitSprites.LedSprite)
 ```
 
-### [Change score by](/functions/game-library/change-score-by)
+### [Change score by](/reference/game/change-score-by)
 
 When a player achieves a goal, you can increase the game score
 
@@ -101,7 +101,7 @@ When a player achieves a goal, you can increase the game score
 export function addScore(points: number)
 ```
 
-### [Score](/functions/game-library/score)
+### [Score](/reference/game/score)
 
 * set the current score to a particular value.
 
@@ -117,7 +117,7 @@ export function setScore(value: number)
 export function score() : number
 ```
 
-### [Countdown](/functions/game-library/start-countdown)
+### [Countdown](/reference/game/start-countdown)
 
 If your game has a time limit, you can start a countdown in which case `game->current time` returns the remaining time.
 
@@ -129,7 +129,7 @@ If your game has a time limit, you can start a countdown in which case `game->cu
 export function startCountdown(ms: number)
 ```
 
-### [Game over](/functions/game-library/game-over)
+### [Game over](/reference/game/game-over)
 
 If the `life` reaches zero or the time expires (see countdown), the game enters the **game over** mode. When the game is over, `game->is running` returns false
 
diff --git a/docs/reference/images/image.md b/docs/reference/images/image.md
index 625603f8..580032c5 100644
--- a/docs/reference/images/image.md
+++ b/docs/reference/images/image.md
@@ -8,7 +8,7 @@ An *Image* is a matrix of pixels to show on the [LED screen](/device/screen)
 
 ### Block Editor: Show LEDs
 
-To display an image using the [Block Editor](/blocks/editor):
+To display an image:
 
 * click `Basic` , `Show LEDs`, and tap on the LEDs`
 * when you're done, return to your code
@@ -21,10 +21,6 @@ You should see code similar to this:
 
 To create an image that you can later modify, see the [create image](/reference/images/create-image) function.
 
-### Block editor: create and show images
-
-To create images using the [Block editor](/blocks/editor):
-
 1. Click the **Images** category on the left.
 
 2. Drag and drop the **show image** block into your code.
diff --git a/docs/reference/images/show-image.md b/docs/reference/images/show-image.md
index d125613f..753db150 100644
--- a/docs/reference/images/show-image.md
+++ b/docs/reference/images/show-image.md
@@ -29,7 +29,7 @@ img.showImage(0)
 
 ### Example: display numbers 1-5
 
-The following example creates an image with 5 frames and then uses a [for loop](/reference/loops/for) to show each frame on the screen:
+The following example creates an image with 5 frames and then uses a [for loop](/blocks/loops/for) to show each frame on the screen:
 
 ```
 let img2 = images.createImage(`
diff --git a/docs/reference/images/width.md b/docs/reference/images/width.md
index 2acf76d9..ed980fe3 100644
--- a/docs/reference/images/width.md
+++ b/docs/reference/images/width.md
@@ -38,7 +38,7 @@ let w = img.width()
 
 ### Example: show each frame
 
-The following example uses the `width` function with a [for](/reference/loops/for) loop to show each image frame on the screen:
+The following example uses the `width` function with a [for](/blocks/loops/for) loop to show each image frame on the screen:
 
 ```
 let img2 = images.createImage(`
diff --git a/docs/reference/input/button-is-pressed.md b/docs/reference/input/button-is-pressed.md
index 4a099155..bdd3a5a7 100644
--- a/docs/reference/input/button-is-pressed.md
+++ b/docs/reference/input/button-is-pressed.md
@@ -16,7 +16,7 @@ input.buttonIsPressed(Button.A);
 
 ### Example
 
-This program uses an [if](/reference/logic/if) to run 
+This program uses an [if](/blocks/logic/if) to run 
 one part of the program if the `A` button is pressed, and 
 another part if it is not pressed.
 
@@ -35,5 +35,5 @@ basic.forever(() => {
 
 ### See also
 
-[on button pressed](/reference/input/on-button-pressed), [if](/reference/logic/if), [forever](/reference/basic/forever)
+[on button pressed](/reference/input/on-button-pressed), [if](/blocks/logic/if), [forever](/reference/basic/forever)
 
diff --git a/docs/reference/input/on-button-pressed.md b/docs/reference/input/on-button-pressed.md
index 34df5f8f..0d2608c9 100644
--- a/docs/reference/input/on-button-pressed.md
+++ b/docs/reference/input/on-button-pressed.md
@@ -43,5 +43,5 @@ Otherwise, sometimes they would show a `0`.
 
 ### See also
 
-[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/reference/math/math)
+[button is pressed](/reference/input/button-is-pressed), [forever](/reference/basic/forever), [random](/blocks/math)
 
diff --git a/docs/reference/led/plot.md b/docs/reference/led/plot.md
index 0907d246..57bdf894 100644
--- a/docs/reference/led/plot.md
+++ b/docs/reference/led/plot.md
@@ -39,7 +39,7 @@ led.plot(4, 4)
 
 ### Example: Square
 
-This program uses a [for loop](/reference/loops/for)
+This program uses a [for loop](/blocks/loops/for)
 and the `plot` function
 to make a square around the edges of the LED screen.
 
diff --git a/docs/reference/logic/if.md b/docs/reference/logic/if.md
deleted file mode 100644
index 9d42e96f..00000000
--- a/docs/reference/logic/if.md
+++ /dev/null
@@ -1,28 +0,0 @@
-# If
-
-### @parent blocks/language
- 
-
-Conditionally run code depending on whether a [Boolean](/reference/types/boolean) condition is true or false.
-
-```blocks
-if(true) {
-}
-```
-
-In the Block Editor, click on the dark blue gear icon (see above) to add an *else* or *if* to the current block.
-
-### Example: adjusting screen brightness
-
-```blocks
-if(input.lightLevel()<100){
-    led.setBrightness(255);
-}
-```
-
-If the [light level](/input/light-level) is `< 100`, this code sets the brightness to `255`:
-
-### See also
-
-[while loop](/reference/loops/while), [for](/reference/loops/for), [boolean](/reference/types/boolean)
-
diff --git a/docs/reference/types.md b/docs/reference/types.md
index 54d3827c..25f7a711 100644
--- a/docs/reference/types.md
+++ b/docs/reference/types.md
@@ -1,17 +1,13 @@
 # types
 
-Touch Develop types.
-
-### @parent language
-
-A *type* refers to a class of data and the operations permitted on that data. The following types are supported by Block Editor for the BBC micro:bit:
+A *type* refers to a class of data and the operations permitted on that class of data. 
+The following built-in types are supported for the BBC micro:bit:
 
 * **[String](/reference/types/string)**: a sequence of characters
 * **[Number](/reference/types/number)**: an integer number (32-bit signed)
 * **[Boolean](/reference/types/boolean)**: true or false
 * **[Image](/blocks/image)**: a collection of [micro:bit LED states](/device/screen) (on/off)
 
-### see also
+TypeScript allows you to create user-defined classes of data. 
 
-[local variables](/reference/variables/var), [assignment operator](/reference/variables/assign)
 
diff --git a/docs/reference/types/boolean.md b/docs/reference/types/boolean.md
index be956513..ba708e23 100644
--- a/docs/reference/types/boolean.md
+++ b/docs/reference/types/boolean.md
@@ -32,7 +32,7 @@ The next six blocks represent comparison operators that yield a Boolean value. M
 42 >= 0;
 ```
 
-Boolean values and operators are often used with an [if](/reference/logic/if) or [while](/reference/loops/while) statement to determine which code will execute next. For example:
+Boolean values and operators are often used with an [if](/blocks/logic/if) or [while](/blocks/loops/while) statement to determine which code will execute next. For example:
 
 ### Functions that return a Boolean
 
@@ -100,5 +100,5 @@ See the documentation on [Numbers](/reference/types/number) for more information
 
 ### See also
 
-[if](/reference/logic/if), [while](/reference/loops/while), [number](/reference/types/number)
+[if](/blocks/logic/if), [while](/blocks/loops/while), [number](/reference/types/number)
 
diff --git a/docs/reference/types/string.md b/docs/reference/types/string.md
index 050b04af..783aac54 100644
--- a/docs/reference/types/string.md
+++ b/docs/reference/types/string.md
@@ -6,13 +6,13 @@ a piece of text.
 
 A *String* is a sequence of characters. For the BBC micro:bit, ASCII character codes 32 to 126 are supported; letters, digits, punctuation marks, and a few symbols. All other character codes appear as a ? on the [LED screen](/device/screen).
 
-### Declare a string
+### Create a string variable
 
-Use the [var statement](/reference/variables/var) and the [assignment operator](/reference/variables/assign) to declare a new *local* string variable. Like this:
+```block
+salutation = "Hello";
+```
 
-![](/static/mb/blocks/string-0.png)
-
-To declare a string using the [Block Editor](/blocks/editor):
+To create a variable that holds a string:
 
 1. Click `Variables` (as the Block drawer).
 
@@ -24,17 +24,22 @@ To declare a string using the [Block Editor](/blocks/editor):
 
 Your code should look something like this:
 
-![](/static/mb/blocks/string-1.png)
+```block
+salutation = "Hello";
+```
 
 ### The function `show string`
 
-Use [show string](/reference/basic/show-string) to display a string on the [LED screen](/device/screen). If the string is multiple characters, the string scrolls right to left. The following example displays `Hello world!` on the micro:bit screen:
+Use [show string](/reference/basic/show-string) to display a string on the [LED screen](/device/screen). 
+If the string is multiple characters, the string scrolls right to left. The following example displays `Hello world!` on the micro:bit screen:
 
-![](/static/mb/blocks/string-2.png)
+```block
+basic.showString("Hello world!");
+```
 
 The  parameter of `show string` specifies the string
 
 ### See also
-
-[variables](/reference/variables/var), [string functions](/reference/types/string-functions), [Number](/reference/types/number), [show string](/reference/basic/show-string)
+ 
+[string functions](/reference/types/string-functions), [Number](/reference/types/number), [show string](/reference/basic/show-string)
 
diff --git a/docs/reference/variables/change-var.md b/docs/reference/variables/change-var.md
deleted file mode 100644
index 1f454c42..00000000
--- a/docs/reference/variables/change-var.md
+++ /dev/null
@@ -1,40 +0,0 @@
-# Change Value
-
-Set the value for local and global variables.
-
-### @parent blocks/change-value
-
-Change the value of a variable
-
-```blocks
-let x = 0
-x += 1
-```
-
-### Declare a variable
-
-Use the assignment operator to set the value of a [variable](/reference/variables/var). Change the value of a variable from 0 to 1 using the change item block. Like this:
-
-```blocks
-let x = 0
-x += 1
-```
-
-### Example
-
-Use the assignment operator to set the value of a [variable](/reference/variables/var). Change the value of a variable from 0 to 1 using the change item block. Then display the new value of the variable on the LED screen. Like this:
-
-```blocks
-let x = 0;
-x += 1;
-basic.showNumber(x);
-```
-
-### Notes
-
-* You can use the assignment operator with variables of each of the supported [types](/reference/types).
-
-### See also
-
-[variable](/reference/variables/var), [types](/reference/types)
-
diff --git a/olddocs/js/assign.md b/olddocs/js/assign.md
index 1466690d..bdb44fcd 100644
--- a/olddocs/js/assign.md
+++ b/olddocs/js/assign.md
@@ -13,11 +13,11 @@ Set or change the value of a variable
 
 ### Touch Develop
 
-Use the assignment operator (:=) to set or change the value of a [local variable](/reference/variables/var) or a [global variable](/js/data).
+Use the assignment operator (:=) to set or change the value of a [local variable](/blocks/variables/var) or a [global variable](/js/data).
 
 ### Declare a variable
 
-Declare a new *local* variable using the [var](/reference/variables/var) statement and the assignment operator (`:=`). Like this:
+Declare a new *local* variable using the [var](/blocks/variables/var) statement and the assignment operator (`:=`). Like this:
 
 ```blocks
 let num1 = 7
diff --git a/olddocs/js/boolean.md b/olddocs/js/boolean.md
index c7900ca1..c237308b 100644
--- a/olddocs/js/boolean.md
+++ b/olddocs/js/boolean.md
@@ -31,7 +31,7 @@ let condition2 = true
 
 ### ~
 
-Boolean values and operators are often used with an [if](/reference/logic/if) or [while](/js/while) statement to determine which code will execute next. For example:
+Boolean values and operators are often used with an [if](/blocks/logic/if) or [while](/js/while) statement to determine which code will execute next. For example:
 
 ```
 if (condition && condition2) {
diff --git a/olddocs/js/comment.md b/olddocs/js/comment.md
index cc851c18..19f1afe3 100644
--- a/olddocs/js/comment.md
+++ b/olddocs/js/comment.md
@@ -21,11 +21,6 @@ To insert a comment in a Touch Develop script:
 
 3. Click `// comment` and then type some text (your comment).
 
-### ~hint 
-
-To find out how to insert comments using the Blocks editor, see [the Blocks editor](/blocks/editor).
-
-### ~
 
 ### Sample function with comments
 
@@ -52,7 +47,7 @@ To comment out a block of code:
 
 2. Press and hold the Shift key, and then press the Down arrow key to select a block of code.
 
-3. In the block editing window, scroll down to **surround with** and click `comment out`. This adds an [if](/reference/logic/if) statement around your code, like this:
+3. In the block editing window, scroll down to **surround with** and click `comment out`. This adds an [if](/blocks/logic/if) statement around your code, like this:
 
 ```
 if (false) {
@@ -69,5 +64,5 @@ When you want to uncomment your code, click the `if false then` statement in you
 
 ### See also
 
-[markdown syntax](/js/markdown), [Touch Develop editor](/js/editor), [Block editor](/blocks/editor)
+[markdown syntax](/js/markdown), [Touch Develop editor](/js/editor)
 
diff --git a/pxtarget.json b/pxtarget.json
index a9ddf068..0dbcd157 100644
--- a/pxtarget.json
+++ b/pxtarget.json
@@ -112,6 +112,10 @@
             {
                 "name": "Micro:bit Device",
                 "path": "/device"
+            },
+            {
+                "name": "Blocks Language",
+                "path": "/blocks"
             }
         ],
         "sideDoc": "getting-started"