diff --git a/examples/embedding/README b/examples/embedding/README.md
similarity index 58%
rename from examples/embedding/README
rename to examples/embedding/README.md
index 0475e8739a53fc500dd5d391d2c2bf77b80c7996..989ce1fc8f459caaea0ca305fcd5e3055063e8e0 100644
--- a/examples/embedding/README
+++ b/examples/embedding/README.md
@@ -11,7 +11,7 @@ Python statement which prints to the standard output.
 Building the example
 --------------------
 
-Build the example is as simple as running:
+Building the example is as simple as running:
 
     make
 
@@ -20,37 +20,38 @@ It's worth to trace what's happening behind the scenes though:
 1. As a first step, a MicroPython library is built. This is handled by a
 seperate makefile, Makefile.upylib. It is more or less complex, but the
 good news is that you won't need to change anything in it, just use it
-as is, the main Makefile shows how. What may need editing though is
-MicroPython configuration file. MicroPython is highly configurable, so
+as is, the main Makefile shows how. What may require editing though is
+a MicroPython configuration file. MicroPython is highly configurable, so
 you would need to build a library suiting your application well, while
 not bloating its size. Check the options in the file "mpconfigport.h".
-Included is a copy of "minimal" Unix port, which should be good start
-for minimal embedding. For list of all available options, see py/mpconfig.h.
+Included is a copy of the "minimal" Unix port, which should be a good start
+for minimal embedding. For the list of all available options, see
+py/mpconfig.h.
 
-2. Once the library is built, your application is compiled and linked with
-the MicroPython library produced in the previous step. The main Makefile
-is very simple and shows that changes you would need to do to your
-application's Makefile (or other build configuration) are also simple:
+2. Once the MicroPython library is built, your application is compiled
+and linked it. The main Makefile is very simple and shows that the changes
+you would need to do to your application's Makefile (or other build
+configuration) are also simple:
 
-a) You would need to use C99 standard (you're using 15+ years old standard
-already, not a 25+ years old one, right?).
+a) You would need to use C99 standard (you're using this 15+ years old
+standard already, not a 25+ years old one, right?).
 
-b) You need to provide path to MicroPython's top-level dir, for includes.
+b) You need to provide a path to MicroPython's top-level dir, for includes.
 
 c) You need to include -DNO_QSTR compile-time flag.
 
-d) Otherwise, just link with micropython library produced in step 1.
+d) Otherwise, just link with the MicroPython library produced in step 1.
 
 
 Out of tree build
 -----------------
 
-This example set up to work out of the box, being part of the MicroPython
+This example is set up to work out of the box, being part of the MicroPython
 tree. Your application of course will be outside of its tree, but the
 only thing you need to do is to pass MPTOP variable pointing to
 MicroPython directory to both Makefiles (in this example, the main Makefile
-automatically pass it to Makefile.upylib; in your own Makefile, don't forget
-to use suitable value).
+automatically passes it to Makefile.upylib; in your own Makefile, don't forget
+to use a suitable value).
 
 A practical way to embed MicroPython in your application is to include it
 as a git submodule. Suppose you included it as libs/micropython. Then in