Embed docs (#259)

* Generic instructions for embedding

* Wordpress instructions, update Markdown instructions

* Blogger instructions

* Squarespace instructions

* Google sites info

* Sway restrictions

* Correct order

docs/share.md

@@ -1,27 +1,85 @@
 # Sharing your project
 
-Once you have a cool project, it is possible to save it in the cloud and share it or embed it to your web site.
+Once you've made your project, you can save it the cloud, share it, or embed it on another website.
 
-### Instructions
+* Click **More...**, then **Embed Project**:
 
-* Click on **More...** then click **Embed Project...**
-* Click on the **Publish** button
+![Asks to embed](/static/embed/publish.png)
 
-The embed dialog will provide you with various options to embed your project in your web site.
+* Click **Publish project**. This will make the project publicly available
+* You will then see this information:
 
-### Project URL
+![Embedding information](/static/embed/embed-info.png)
 
-This URL will point to a web page that contains that project.
+## Sharing the URL
 
-* see the "happy" project: https://codethemicrobit.com/pyirlbpsei
+You can share the URL for the project ([https://codethemicrobit.com/httuftrbtg](https://codethemicrobit.com/httuftrbtg) above) with other people, and they will be able to visit that page to see your project, download it, or edit it:
 
-### Embedding into a blog or web site
+![Project page](/static/embed/project-page.png)
 
-* Copy the HTML and paste it into your HTML source.
+## Embedding into a blog or web site
 
+Rather than just sharing the link, you can also embed the project so that your visitors can use the simulator, edit blocks or code, or download the project without having to leave your site.
+
+### General instructions
+
+* Copy the HTML for embedding the page from the publish dialog. It will look like the following:
+
+```html
+<div class="ui card sim"><div class="ui content"><div style="position:relative;height:0;padding-bottom:70%;overflow:hidden;"><iframe style="position:absolute;top:0;left:0;width:100%;height:100%;" src="https://codethemicrobit.com/?sandbox=1#pub:httuftrbtg" allowfullscreen="allowfullscreen" frameborder="0"></iframe></div></div></div>
+```
+
+* Open the HTML editor for your blog or website and paste it with your content
+
+### Wordpress
+
+[wordpress.com][] blogs do not support embedding content from most websites, so you will need to link to your project instead. Alternatively, if you have a Wordpress VIP account you can follow [these instructions][wordpress-vip] to embed an `iframe` into your blog. The URL that you need to add is like `https://codethemicrobit.com/?sandbox=1#pub:httuftrbtg`, but replace `httuftrbtg` with your project's unique identifier.
+
+If you self host a Wordpress blog you can install the [iframe-plugin][] and then write the following in your blog-post (again, replacing the `httuftrbtg` with your project's identifier):
+
+```
+[iframe src="https://codethemicrobit.com/?sandbox=1#pub:httuftrbtg"]
+```
+
+### Blogger
+
+* Create a new post
+* Click the 'HTML' button next to 'Compose' and paste in the HTML
+
+![Blogger](/static/embed/blogger.png)
+
+### Squarespace
+
+[Squarespace][] allows you to embed HTML code inside a blog post or page. In the editor, click to add a new block:
+
+![Squarespace block insertion](/static/embed/squarespace-insert.png)
+
+Scroll to **More** and select **Code**. Paste the embed HTML and click **Apply**:
+
+![Squarespace code insertion](/static/embed/squarespace-code.png)
+
+### Google Sites
+
+Google Sites doesn't currently [support iframes in custom HTML][google-sites-iframes], so you'll have to insert a link to your project's URL instead.
+
+### Office Sway
+
+[Microsoft Office Sway][sway] only allows iframes from [certain websites][sway-restricted], so you'll need to insert a link to your project instead.
+### Embedding in Markdown documents
+
+[Markdown][] is a popular text format supported by many blog editors. As Markdown supports embedded HTML, you should be able to paste the HTML into the document, although some sites may prevent you from doing this.
 
 ### ~hint
 
 **Developers:** This page supports OEmbed as well 
 
 ### ~
+
+[wordpress.com]: https://wordpress.com
+[wordpress-vip]: https://vip.wordpress.com/documentation/embedding-rich-media-from-around-the-web-with-protected-embeds/#scripts-iframes-and-objects
+[iframe-plugin]: https://wordpress.org/plugins/iframe/
+[squarespace]: https://squarespace.com
+[google-sites-iframes]: https://support.google.com/sites/answer/2500646?hl=en
+[sway]: https://sway.com/my
+[sway-restricted]: https://support.office.com/en-us/article/Embed-content-in-your-Sway-1e1ab12a-f961-4a26-8afc-77a15f892b1d
+[Markdown]: https://daringfireball.net/projects/markdown/