Blocks embedding

MakeCode provides a lightweight blocks rendering engine that renders code snippets as SVG images.

The Curse of screenshots

Unlike text based programming languages, block-based snippets aren’t easily rendered in a documentation page. A quick solution is take screenshots of the snippets but things can quickly become unsustainable:

• screenshots can’t be compiled - so it’s hard to maintain them
• screenshots are not localizable - non-English speaking users won’t be able to read the blocks
• screenshots aren’t easily reloaded into the editor
• screenshots don’t play well with source control systems - you cannot diff changes efficiently

Rendering blocks on the spot

The MakeCode approach in solving this problem is to render the JavaScript code snippets on a client using the same block rendering engine as the editor. Under the hood, an IFrame from the MakeCode editor will render the blocks for you.

GitHub pages

You can use GitHub pages to render your README.md file as a web site.

• enable GitHub pages on your repository
• add the url of the editor in _config.yml (including trailing /)

  makecode:
    home_url: https://makecode.com/

• copy the following text at the bottom of your README.md file

  <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 are some sample integrations for various documentation/blogging engines.

• React component
• HTML only
• MkDocs plugin

Manual Implementation

You can find example of custom blocks embedding in the documentation of your favorite editor.