Update 'blocks-embed' topic to describe use with extensions

common-docs/blocks-embed.md

@@ -18,24 +18,25 @@ The MakeCode approach to solving this issue is to render the **JavaScript** code
 
 ## GitHub pages #githubpages
 
-You can use [GitHub pages](https://help.github.com/en/github/working-with-github-pages) to render your README.md file as a web site.
+You can use [GitHub pages](https://help.github.com/en/github/working-with-github-pages) to render your README.md file as a web site. Within the README.md you can enable rendering of blocks.
 
 * enable [GitHub pages](https://help.github.com/en/github/working-with-github-pages/creating-a-github-pages-site#creating-your-site) on your repository
 * add the following entry in the ``_config.yml``
 
-```
+```yml
   makecode:
     home_url: @homeurl@
 ```
 
 * copy the following text at the bottom of your ``README.md`` file
-```
+
+```html
 <script src="https://makecode.com/gh-pages-embed.js"></script><script>makeCodeRender("{{ site.makecode.home_url }}", "{{ site.github.owner_name }}/{{ site.github.repository_name }}");</script>
 ```
 
 ## Other Plugins
 
-Here is an integration sample:
+Here are some other integration samples:
 
 * [React component](https://github.com/microsoft/pxt-react-extension-template/blob/master/src/components/snippet.tsx)
 * [HTML only](https://jsfiddle.net/L8msdjpu/2/)
@@ -47,7 +48,9 @@ To render blocks in your own HTML documents or to make plugins for a document pl
 
 ### ~ hint
 
-Try this [fiddle](https://jsfiddle.net/nq0hyz97/) to see an embedded blocks rendering example.
+#### Try it out
+
+Try this [fiddle](https://jsfiddle.net/nq0hyz97/) to see an embedded blocks rendering example in action.
 
 ### ~
 
@@ -134,7 +137,7 @@ The ``renderblocks`` message is received as a response to a previous ``renderblo
 
 As an example, let's say that a document has all of its code snippets contained in ``pre`` elements:
 
-```
+```html
 <pre>
 basic.showString("Hello World")
 </pre>
@@ -340,20 +343,46 @@ $(function () {
 </html>
 ```
 
+## Rendering blocks from extensions
+
+If you also want to render blocks from an extension, include the path for the extension in the `options.package` data field. For example, if you want to show a block from the `neopixel` extension, like the block for `setPixelColor`:
+
+```html
+<pre>
+strip.setPixelColor(0, NeoPixelColors.White)
+</pre>
+```
+
+Add the `options.package` field and set it to the extension path specifier such as `neopixel=github:microsoft/pxt-neopixel` for the `neopixel` extension ([`neopixel`](https://github.com/microsoft/pxt-neopixel/blob/master/pxt.json) is the name of the extension and `github:microsoft/pxt-neopixel` is the GitHub path, see [package specs](https://makecode.com/writing-docs/snippets#package)): 
+
+```typescript-ignore
+function makeCodeRenderPre(pre) {
+    var f = document.getElementById("makecoderenderer");
+    f.contentWindow.postMessage({
+        type: "renderblocks",
+        id: pre.id,
+        code: pre.innerText,
+        options: {
+            package: "neopixel=github:microsoft/pxt-neopixel"
+        }
+    }, "@homeurl@");
+}
+```
+
 ## Rendering shared projects
 
 Rendering a shared project is accomplished in almost the same manner as the embedded blocks method. In this case though,
 leave the ``code`` attribute empty and pass the shared project id in a ``options.packageId`` data field.
 
 In the HTML, you can store the shared project id in a ``pre`` element as a data attribute.
 
-```
+```html
 <pre data-packageid="_HjWJo9eHjXwP"></pre>
 ```
 
 Then, read the ``data-packageid`` attribute and pass it along as the ``packageId`` field in the ``options`` of the ``renderblocks`` message.
 
-```
+```typescript-ignore
 f.contentWindow.postMessage({
     type: "renderblocks",
     id: pre.id,
@@ -364,7 +393,7 @@ f.contentWindow.postMessage({
 }, "@homeurl@");
 ```
 
-* [HTML only](https://jsfiddle.net/L8msdjpu/3/)
+See this [HTML](https://jsfiddle.net/L8msdjpu/3/) example.
 
 ## Lazy loading