dojo
diff --git a/‎.dojorc
+8 b/‎.dojorc
+8
diff --git a/‎README.md
+48-14 b/‎README.md
+48-14
@@ -1,4 +1,12 @@
 {
+	"build-app": {
+		"build-time-render": {
+			"root": "app"
+		},
+		"features": {
+			"docs": false
+		}
+	},
 	"build-widget": {
 		"prefix": "dojo",
 		"widgets": [
 
@@ -179,7 +179,6 @@ Individual widgets also provide certain types of extension points where applicab
 - `getModifierClasses`: Modify the array of conditionally applied classes like `css.selected` or `css.disabled`.
 Not all widgets include these extension points, and some have additional overridable methods.
 
-
 ## How do I contribute?
 
 We appreciate your interest!  Please see the [Dojo Meta Repository](https://github.com/dojo/meta#readme) for the
@@ -207,26 +206,61 @@ To test against browsers with a local selenium server run:
 
 `npm run test:functional`
 
+### Widget Examples
+
+The Dojo widget examples application is located in `src/examples`.
+
+To add a new example, create a directory that matches the directory name of the widget e.g. `src/examples/src/widgets/text-input`. Each widget _must_ have an example called `Basic.tsx` and an entry in the `src/examples/src/config.ts` keyed by the name of the widget directory.
+
+```js
+{
+    'text-input: {
+        filename: 'index',
+        overview: {
+            example: {
+                module: BasicCheckbox,
+                filename: 'Basic'
+            }
+        },
+        examples: [
+            {
+                title: 'The example title',
+                description: 'Optional example description',
+                module: OtherCheckbox,
+                filename: 'Other'
+            }
+        ]
+    }
+}
+```
 
-### Viewing widget examples locally
+ * filename: The name of the widget module, defaults to `index`
+ * overview: The configuration for the basic example including the imported Basic module and the example filename (has to be `'Basic'`)
+ * examples: Additional examples for the widget, an array of configuration that specifies the title, description, module and example filename. 
 
-Each Dojo widget includes functioning example code so you can view the widget. To view individual widget example:
+ To view the examples locally run `npm run dev` and navigate to http://localhost:9999, this starts the examples in watch mode and should update widget module are changed.
 
-1. Run `npm run build:test` in your terminal
-2. Run `npm run examples`
-2. Open the newly built project at `http://localhost:5000/_build/common/example/` in your web browser
-3. By default, no widget is selected, open the dropdown to select a widget
-4. Observe the page reloads and the selected widget displays
+### Widget Documentation
 
-#### Watching widget example code
+The widget examples and documentation is automatically generated by the `examples` application when built with the `docs` feature flag set to `true`. The site relies on a few conventions in order to be able do this:
 
-Running `npm run build` each time you wish to view a small change can be tedious, instead to have your files watched run:
+1. A widgets properties interface must be the name of the widget with a suffix of `Properties`, e.g. for `text-input` the properties interface would be `TextInputProperties`
+2. All themeable styles must be added to the corresponding theme css module in `src/theme` and match the name of thw widget directory e.g. `text-input.m.css`
+3. For properties description docs must be included inline above each property, e.g.
 
-```
-tsc -w
-```
+```ts
+interface ExampleProperties {
+    /** This is the description for foo */
+    foo: string;
+    /** This is the description for bar */
+    bar: string;
+}
+
+To build the documentation run `npm run build:docs` and to build and serve the documentation in watch mode run `npm run build:docs:dev`
+
+### Running the examples on Codesandbox
 
-With that command, TypeScript watches for changes and recompiles when necessary.
+The examples also run on Codesanbox, to run the examples on the master branch go to https://codesandbox.io/s/github/dojo/widgets/tree/master/src/examples. To run the examples for a specific user/branch/tag adjust the url as required.
 
 ## Licensing information