From e5fe406111f97269b8a552e9fc5ee285e05941fa Mon Sep 17 00:00:00 2001
From: Bruno Dias <dias.h.bruno@gmail.com>
Date: Mon, 9 Dec 2019 20:50:44 -0300
Subject: [PATCH] [chore] moving documentation to mkdocs.

---
 Makefile                                      |  40 ++--
 docs/README.md                                | 184 -----------------
 docs/SUMMARY.md                               |  31 ---
 docs/accessibility/{README.md => index.md}    |  12 +-
 docs/contributing/development.md              |  18 +-
 docs/contributing/{README.md => index.md}     |   2 -
 docs/examples/css_classes.md                  |   2 +-
 docs/examples/global_overrides.md             |   2 +-
 docs/examples/{README.md => index.md}         |  11 +-
 docs/examples/inline_styles.md                |   2 +-
 docs/examples/minimal.md                      |   2 +-
 docs/examples/on_request_close.md             |   4 +-
 docs/examples/set_app_element.md              |   2 +-
 .../examples/should_close_on_overlay_click.md |   1 +
 docs/index.md                                 | 185 ++++++++++++++++++
 docs/styles/classes.md                        |   2 -
 docs/styles/{README.md => index.md}           |   2 -
 docs/styles/transitions.md                    |   2 -
 docs/testing/{README.md => index.md}          |   0
 mkdocs.yml                                    |  26 +++
 20 files changed, 255 insertions(+), 275 deletions(-)
 delete mode 100644 docs/README.md
 delete mode 100644 docs/SUMMARY.md
 rename docs/accessibility/{README.md => index.md} (96%)
 rename docs/contributing/{README.md => index.md} (98%)
 rename docs/examples/{README.md => index.md} (85%)
 create mode 100644 docs/index.md
 rename docs/styles/{README.md => index.md} (98%)
 rename docs/testing/{README.md => index.md} (100%)
 create mode 100644 mkdocs.yml

diff --git a/Makefile b/Makefile
index 4a2f1921..b293eca9 100644
--- a/Makefile
+++ b/Makefile
@@ -11,6 +11,11 @@ REMOTE="git@github.com:reactjs/react-modal"
 CURRENT_VERSION:=$(shell jq ".version" package.json)
 COVERAGE?=true
 
+BRANCH=$(shell git rev-parse --abbrev-ref HEAD)
+CURRENT_VERSION:=$(shell jq ".version" package.json)
+
+VERSION:=$(if $(RELEASE),$(shell read -p "Release $(CURRENT_VERSION) -> " V && echo $$V),$(subst /,-,$(BRANCH)))
+
 help: info
 	@echo
 	@echo "Current version: $(CURRENT_VERSION)"
@@ -38,10 +43,10 @@ info:
 deps: deps-project deps-docs
 
 deps-project:
-	@[[ ! -z "$(YARN)" ]] && $(YARN) install || $(NPM) install
+	@$(PKM) install
 
 deps-docs:
-	@gitbook install
+	@pip install --user mkdocs mkdocs-material jsx-lexer
 
 # Rules for development
 
@@ -64,27 +69,20 @@ lint:
 	@npm run lint
 
 docs: build-docs
-	gitbook serve
+	mkdocs serve
 
 # Rules for build and publish
 
 check-working-tree:
-	@sh ./scripts/repo_status
-
-version:
-	@echo "[Updating react-modal version]"
-	@sh ./scripts/version $(CURRENT_VERSION)
-	@$(JQ) '.version' package.json | cut -d\" -f2 > .version
-
-branch:
-	@echo "[Release from branch]"
-	@git branch | grep '^*' | awk '{ print $$2 }' > .branch
-	@[[ "`cat .branch`" != "master\n" ]] && echo "Current branch: `cat .branch`" || (echo "Fail. Current branch is not master." && exit 1)
+	@[[ ! -z "`git status -s`" ]] && \
+	echo "Stopping publish. There are change to commit or discard." && \
+	exit 1
 
 changelog:
-	@echo "[Updating CHANGELOG.md $(CURRENT_VERSION) > `cat .version`]"
-	@python3 ./scripts/changelog.py v$(CURRENT_VERSION) v`cat .version` > .changelog_update
+	@echo "[Updating CHANGELOG.md $(CURRENT_VERSION)]"
+	@python3 ./scripts/changelog.py v$(CURRENT_VERSION) v$(VERSION) > .changelog_update
 	@cat .changelog_update CHANGELOG.md > tmp && mv tmp CHANGELOG.md
+	@rm .changelog_update
 
 compile:
 	@echo "[Compiling source]"
@@ -92,19 +90,19 @@ compile:
 
 build: compile
 	@echo "[Building dists]"
-	@./node_modules/.bin/webpack --config ./scripts/webpack.dist.config.js
+	@npx webpack --config ./scripts/webpack.dist.config.js
 
 release-commit:
-	git commit --allow-empty -m "Release v`cat .version`."
+	git commit --allow-empty -m "Release v$(VERSION)."
 	@git add .
 	@git commit --amend -m "`git log -1 --format=%s`"
 
 release-tag:
-	git tag "v`cat .version`"
+	git tag "v$(VERSION)"
 
 publish-version: release-commit release-tag
 	@echo "[Publishing]"
-	git push $(REMOTE) "`cat .branch`" "v`cat .version`"
+	git push $(REMOTE) "$(BRANCH)" "v$(VERSION)"
 	npm publish
 
 pre-publish: clean branch version changelog
@@ -122,7 +120,7 @@ init-docs-repo:
 build-docs:
 	@echo "[Building documentation]"
 	@rm -rf _book
-	@gitbook build -g reactjs/react-modal
+	@mkdocs build 
 
 pre-publish-docs: clean-docs init-docs-repo deps-docs
 
diff --git a/docs/README.md b/docs/README.md
deleted file mode 100644
index bd74a76a..00000000
--- a/docs/README.md
+++ /dev/null
@@ -1,184 +0,0 @@
-# react-modal
-
-> Accessible modal dialog component for React.JS
-
-We maintain that accessibility is a key component of any modern web application.  As such, we have created this modal in such a way that it fulfills the accessibility requirements of the modern web.  We seek to keep the focus on accessibility while providing a functional, capable modal component for general use.
-
-## Installation {#installation}
-
-To install the stable version you can use [npm](https://npmjs.org/) or [yarn](https://yarnpkg.com):
-
-
-    $ npm install react-modal
-    $ yarn add react-modal
-
-
-## General Usage {#usage}
-
-The only required prop for the modal object is `isOpen`, which indicates
-whether the modal should be displayed.  The following is an example of using
-react-modal specifying all the possible props and options:
-
-```js
-import ReactModal from 'react-modal';
-
-<ReactModal
-  /*
-    Boolean describing if the modal should be shown or not.
-  */
-  isOpen={false}
-  /*
-    Function that will be run after the modal has opened.
-  */
-  onAfterOpen={handleAfterOpenFunc}
-  /*
-    Function that will be run after the modal has closed.
-  */
-  onAfterClose={handleAfterCloseFunc}
-  /*
-    Function that will be run when the modal is requested to be closed (either by clicking on overlay or pressing ESC)
-    Note: It is not called if isOpen is changed by other means.
-  */
-  onRequestClose={handleRequestCloseFunc}
-  /*
-    Number indicating the milliseconds to wait before closing the modal.
-  */
-  closeTimeoutMS={0}
-  /*
-    Object indicating styles to be used for the modal.
-    It has two keys, `overlay` and `content`.  See the `Styles` section for more details.
-  */
-  style={{ overlay: {}, content: {} }}
-  /*
-    String indicating how the content container should be announced to screenreaders
-  */
-  contentLabel="Example Modal"
-  /*
-     String className to be applied to the portal.
-     See the `Styles` section for more details.
-  */
-  portalClassName="ReactModalPortal"
-  /*
-     String className to be applied to the overlay.
-     See the `Styles` section for more details.
-  */
-  overlayClassName="ReactModal__Overlay"
-   /*
-     String id to be applied to the content div
-   */
-  id=""
-  /*
-     String className to be applied to the modal content.
-     See the `Styles` section for more details.
-  */
-  className="ReactModal__Content"
-  /*
-     String className to be applied to the document.body (must be a constant string).
-     This attribute when set as `null` doesn't add any class to document.body.
-     See the `Styles` section for more details.
-  */
-  bodyOpenClassName="ReactModal__Body--open"
-  /*
-     String className to be applied to the document.html (must be a constant string).
-     This attribute is `null` by default.
-     See the `Styles` section for more details.
-  */
-  htmlOpenClassName="ReactModal__Html--open"
-  /*
-    Boolean indicating if the appElement should be hidden
-  */
-  ariaHideApp={true}
-  /*
-    Boolean indicating if the modal should be focused after render
-  */
-  shouldFocusAfterRender={true}
-  /*
-    Boolean indicating if the overlay should close the modal
-  */
-  shouldCloseOnOverlayClick={true}
-  /*
-    Boolean indicating if pressing the esc key should close the modal
-    Note: By disabling the esc key from closing the modal you may introduce an accessibility issue.
-  */
-  shouldCloseOnEsc={true}
-  /*
-    Boolean indicating if the modal should restore focus to the element that
-    had focus prior to its display.
-  */
-  shouldReturnFocusAfterClose={true}
-  /*
-    String indicating the role of the modal, allowing the 'dialog' role to be applied if desired.
-    This attribute is `dialog` by default.
-  */
-  role="dialog"
-  /*
-    Function that will be called to get the parent element that the modal will be attached to.
-  */
-  parentSelector={() => document.body}
-  /*
-    Additional aria attributes (optional).
-  */
-  aria={{
-    labelledby: "heading",
-    describedby: "full_description"
-  }}
-  /*
-    Additional data attributes (optional).
-  */
-  data={{
-    background: "green"
-  }}
-  /*
-    Overlay ref callback.
-  */
-  overlayRef={setOverlayRef}
-  /*
-    Content ref callback.
-  */
-  contentRef={setContentRef}
-/>
-```
-
-## Using a custom parent node {#custom-parent}
-
-By default, the modal portal will be appended to the document's body.  You can
-choose a different parent element by providing a function to the
-`parentSelector` prop that returns the element to be used:
-
-```jsx
-function getParent() {
-  return document.querySelector('#root');
-}
-
-<Modal
-  ...
-  parentSelector={getParent}
-  ...
->
-  <p>Modal Content.</p>
-</Modal>
-```
-
-If you do this, please ensure that your
-[app element](accessibility/README.md#app-element) is set correctly.  The app
-element should not be a parent of the modal, to prevent modal content from
-being hidden to screenreaders while it is open.
-
-## Refs {#refs}
-
-You can use ref callbacks to get the overlay and content DOM nodes directly:
-
-```jsx
-<Modal
-  ...
-  overlayRef={node => this.overlayRef = node}
-  contentRef={node => this.contentRef = node}
-  ...
->
-  <p>Modal Content.</p>
-</Modal>
-```
-
-## License {#license}
-
-MIT
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
deleted file mode 100644
index b3678b27..00000000
--- a/docs/SUMMARY.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# Summary
-
-* [Overview](/README.md)
-  * [Installation](/README.md#installation)
-  * [Usage summary](/README.md#usage)
-  * [Using a custom parent node](/README.md#custom-parent)
-  * [Refs](/README.md#refs)
-  * [License](/README.md#license)
-
-* [Accessibility](accessibility/README.md)
-  * [The app element](accessibility/README.md#app-element)
-  * [Keyboard navigation](accessibility/README.md#keyboard)
-  * [ARIA attributes](accessibility/README.md#aria)
-
-* [Styles](styles/README.md)
-  * [Using CSS Classes](styles/classes.md)
-  * [Transitions](styles/transitions.md)
-
-* [Testing](testing/README.md)
-
-* [Examples](examples/README.md)
-  * [Minimal](examples/minimal.md)
-  * [Using setAppElement](examples/set_app_element.md)
-  * [Using onRequestClose](examples/on_request_close.md)
-  * [Using shouldCloseOnOverlayClick](examples/should_close_on_overlay_click.md)
-  * [Using Inline Styles](examples/inline_styles.md)
-  * [Using CSS Classes](examples/css_classes.md)
-  * [Using Global Style Overrides](examples/global_overrides.md)
-
-* [Contributing](contributing/README.md)
-  * [Development setup](contributing/development.md)
diff --git a/docs/accessibility/README.md b/docs/accessibility/index.md
similarity index 96%
rename from docs/accessibility/README.md
rename to docs/accessibility/index.md
index 09480de2..5ba13f18 100644
--- a/docs/accessibility/README.md
+++ b/docs/accessibility/index.md
@@ -1,11 +1,9 @@
-## Accessibility
-
 react-modal aims to be fully accessible, using the
 [WAI-ARIA](https://www.w3.org/WAI/intro/aria) guidelines to support users of
 assistive technologies.  This page describes some of react-modal's
 accessibility-oriented features, along with their configuration options.
 
-### The app element {#app-element}
+### [The app element](#app-element)
 
 It is important for users of screenreaders that other page content be hidden
 (via the `aria-hidden` attribute) while the modal is open.  To allow
@@ -14,14 +12,14 @@ selector identifying the root of your app.  For example, if your app content is
 located inside an element with the ID `root`, you could place the following
 call somewhere in your code before any modals are opened:
 
-```js
+```jsx
 Modal.setAppElement('#root');
 ```
 
 You can also pass a DOM element directly, so that the above example could be
 rewritten:
 
-```js
+```jsx
 Modal.setAppElement(document.getElementById('root'));
 ```
 
@@ -32,7 +30,7 @@ to avoid getting a warning that your app element is not specified.
 Using `Modal.setAppElement` will not embed react-modal into your react app as
 a descendent component. It will just help boost up the app accessiblity.
 
-### Keyboard navigation {#keyboard}
+### [Keyboard navigation](#keyboard)
 
 When the modal is opened, it restricts keyboard navigation using the tab key to
 elements within the modal content.  This ensures that elements outside the
@@ -47,7 +45,7 @@ The modal can be closed using the escape key, unless the
 `shouldCloseOnEsc={false}` prop is passed.  Disabling this behavior may cause
 accessibility issues for keyboard users, however, so it is not recommended.
 
-### ARIA attributes {#aria}
+### [ARIA attributes](#aria)
 
 Besides the `aria-hidden` attribute which is applied to the app element when
 the modal is shown, there are many other ARIA attributes which you can use to
diff --git a/docs/contributing/development.md b/docs/contributing/development.md
index bedf4e5b..1c9e1433 100644
--- a/docs/contributing/development.md
+++ b/docs/contributing/development.md
@@ -1,13 +1,11 @@
-### Development setup
-
 `react-modal` uses `make` to build and publish new versions and documentation.
 
 It works as a checklist for the future releases to keep everything updated such as
 `CHANGELOG.md`, `package.json` and `bower.json` and so on.
 
-The minimun works as a normal `npm script`.
+The minimun works as a normal `npm` scripts.
 
-#### Usage
+#### [Usage](#usage)
 
 Once you clone `react-modal`, you can run `sh bootstrap.sh` to check
 and download dependencies not managed by `react-modal` such as `gitbook-cli`.
@@ -15,19 +13,19 @@ and download dependencies not managed by `react-modal` such as `gitbook-cli`.
 It will also show information about the current versions of `node`, `npm`,
 `yarn` and `jq` available.
 
-#### List of `npm` commands:
+#### [List of `npm` or `yarn` commands](#npm-yarn-commands)
 
-    $ npm start -s or yarn start  # to run examples
+    $ npm start
     $ npm run tests
     $ npm run lint
 
-#### List of `make` commands:
+#### [List of `make` commands](#make-commands)
 
     $ make help           # show all make commands available
-    $ make deps           # npm install, gitbook plugins...
-    $ make serve          # to run examples
+    $ make deps           # npm install
+    $ make serve          # start a examples' web server
     $ make tests          # use when developing
     $ make tests-ci       # single run
-    $ make lint           # pass lint
+    $ make lint           # execute lint
     $ make publish        # execute the entire pipeline to publish
     $ make publish-docs   # execute the pipeline for docs
diff --git a/docs/contributing/README.md b/docs/contributing/index.md
similarity index 98%
rename from docs/contributing/README.md
rename to docs/contributing/index.md
index e14949ac..9ad874fe 100644
--- a/docs/contributing/README.md
+++ b/docs/contributing/index.md
@@ -1,5 +1,3 @@
-## Contributing
-
 ### Commit Subjects
 
 If your patch **changes the API or fixes a bug** please use one of the
diff --git a/docs/examples/css_classes.md b/docs/examples/css_classes.md
index 59d2ad04..030b127f 100644
--- a/docs/examples/css_classes.md
+++ b/docs/examples/css_classes.md
@@ -4,4 +4,4 @@ If you prefer to use CSS to handle styling the modal you can.
 
 One thing to note is that by using the className property you will override all default styles.
 
-[](codepen://claydiffrient/KNjVrG)
+[CSS classes example](codepen://claydiffrient/KNjVrG)
diff --git a/docs/examples/global_overrides.md b/docs/examples/global_overrides.md
index 5b162132..56c4b2b9 100644
--- a/docs/examples/global_overrides.md
+++ b/docs/examples/global_overrides.md
@@ -2,4 +2,4 @@
 
 If you'll be using several modals and want to adjust styling for all of them in one location you can by modifying `Modal.defaultStyles`.
 
-[](codepen://claydiffrient/pNXgqQ)
+[Global overrides example](codepen://claydiffrient/pNXgqQ)
diff --git a/docs/examples/README.md b/docs/examples/index.md
similarity index 85%
rename from docs/examples/README.md
rename to docs/examples/index.md
index b0313c09..fe4d9cb9 100644
--- a/docs/examples/README.md
+++ b/docs/examples/index.md
@@ -1,5 +1,3 @@
-## Examples
-
 The following sub-sections contain several examples of basic usage, hosted on
 [CodePen](https://codepen.io).
 
@@ -7,14 +5,11 @@ The `examples` directory in the project root also contains some examples which
 you can run locally.  To build and run those examples using a local development
 server, run either
 
-```
-$ npm start
-```
+    $ npm start
 
 or
 
-```
-$ yarn run start
-```
+    $ yarn start
+
 
 and then point your browser to `localhost:8080`.
diff --git a/docs/examples/inline_styles.md b/docs/examples/inline_styles.md
index 26111bc6..8a1a3be2 100644
--- a/docs/examples/inline_styles.md
+++ b/docs/examples/inline_styles.md
@@ -2,4 +2,4 @@
 
 This example shows how to use inline styles to adjust the modal.
 
-[](codepen://claydiffrient/ZBmyKz)
+[inline styles example](codepen://claydiffrient/ZBmyKz)
diff --git a/docs/examples/minimal.md b/docs/examples/minimal.md
index cea9acab..3cd9649f 100644
--- a/docs/examples/minimal.md
+++ b/docs/examples/minimal.md
@@ -2,4 +2,4 @@
 
 This example shows the minimal needed to get React Modal to work.
 
-[](codepen://claydiffrient/KNxgav)
+[Minimal example](codepen://claydiffrient/KNxgav)
diff --git a/docs/examples/on_request_close.md b/docs/examples/on_request_close.md
index f723a111..341a7ca9 100644
--- a/docs/examples/on_request_close.md
+++ b/docs/examples/on_request_close.md
@@ -5,4 +5,6 @@ This example shows how you can use the `onRequestClose` prop with a function to
 This is especially important for handling closing the modal via the escape key.
 
 Also more important if `shouldCloseOnOverlayClick` is set to `true`, when clicked on overlay it calls `onRequestClose`.
-[](codepen://claydiffrient/KNjVBx)
+
+
+[onRequestClose example](codepen://claydiffrient/KNjVBx)
diff --git a/docs/examples/set_app_element.md b/docs/examples/set_app_element.md
index 715ae454..1228cfd5 100644
--- a/docs/examples/set_app_element.md
+++ b/docs/examples/set_app_element.md
@@ -4,4 +4,4 @@ This example shows how to use setAppElement to properly hide your application fr
 
 You'll notice in this example that the aria-hidden attribute is applied to the #main div rather than the document body.
 
-[](codepen://claydiffrient/ENegGJ)
+[setAppElement example](codepen://claydiffrient/ENegGJ)
diff --git a/docs/examples/should_close_on_overlay_click.md b/docs/examples/should_close_on_overlay_click.md
index b120104e..2dd37bcb 100644
--- a/docs/examples/should_close_on_overlay_click.md
+++ b/docs/examples/should_close_on_overlay_click.md
@@ -6,4 +6,5 @@ This is due to the fact that the `react-modal` doesn't store the `isOpen`
 on its state (only for the internal `portal` (see [ModalPortal.js](https://github.com/reactjs/react-modal/blob/master/src/components/ModalPortal.js)).
 
 [disable 'close on overlay click', codepen by claydiffrient](codepen://claydiffrient/woLzwo)
+
 [enable 'close on overlay click', codepen by sbgriffi](codepen://sbgriffi/WMyBaR)
diff --git a/docs/index.md b/docs/index.md
new file mode 100644
index 00000000..9131af21
--- /dev/null
+++ b/docs/index.md
@@ -0,0 +1,185 @@
+# react-modal
+
+> Accessible modal dialog component for React.JS
+
+We maintain that accessibility is a key component of any modern web application.  As such, we have created this modal in such a way that it fulfills the accessibility requirements of the modern web.  We seek to keep the focus on accessibility while providing a functional, capable modal component for general use.
+
+## [Installation](#installation)
+
+To install the stable version you can use [npm](https://npmjs.org/) or [yarn](https://yarnpkg.com):
+
+
+    $ npm install react-modal
+    $ yarn add react-modal
+
+
+## [General Usage](#usage)
+
+The only required prop for the modal object is `isOpen`, which indicates
+whether the modal should be displayed.  The following is an example of using
+react-modal specifying all the possible props and options:
+
+```jsx
+import ReactModal from 'react-modal';
+
+<ReactModal
+
+  isOpen={
+    false
+  /* Boolean describing if the modal should be shown or not. */}
+
+  onAfterOpen={
+    handleAfterOpenFunc
+  /* Function that will be run after the modal has opened. */}
+
+  onAfterClose={
+    handleAfterCloseFunc
+  /* Function that will be run after the modal has closed. */}
+
+  onRequestClose={
+    handleRequestCloseFunc
+  /* Function that will be run when the modal is requested
+     to be closed (either by clicking on overlay or pressing ESC).
+     Note: It is not called if isOpen is changed by other means. */}
+
+  closeTimeoutMS={
+    0
+  /* Number indicating the milliseconds to wait before closing
+     the modal. */}
+
+  style={
+    { overlay: {}, content: {} }
+  /* Object indicating styles to be used for the modal.
+     It has two keys, `overlay` and `content`.
+     See the `Styles` section for more details. */}
+
+  contentLabel={
+    "Example Modal"
+  /* String indicating how the content container should be announced
+     to screenreaders */}
+
+  portalClassName={
+    "ReactModalPortal"
+  /* String className to be applied to the portal.
+     See the `Styles` section for more details. */}
+
+  overlayClassName={
+    "ReactModal__Overlay"
+  /* String className to be applied to the overlay.
+     See the `Styles` section for more details. */}
+
+  id={
+    "some-id"
+  /* String id to be applied to the content div. */}
+
+  className={
+    "ReactModal__Content"
+  /* String className to be applied to the modal content.
+     See the `Styles` section for more details. */}
+
+  bodyOpenClassName={
+    "ReactModal__Body--open"
+  /* String className to be applied to the document.body 
+     (must be a constant string).
+     This attribute when set as `null` doesn't add any class 
+     to document.body.
+     See the `Styles` section for more details. */}
+
+  htmlOpenClassName={
+    "ReactModal__Html--open"
+  /* String className to be applied to the document.html
+     (must be a constant string).
+     This attribute is `null` by default.
+     See the `Styles` section for more details. */}
+
+  ariaHideApp={
+    true
+  /* Boolean indicating if the appElement should be hidden */}
+
+  shouldFocusAfterRender={
+    true
+  /* Boolean indicating if the modal should be focused after render. */}
+
+  shouldCloseOnOverlayClick={
+    true
+  /* Boolean indicating if the overlay should close the modal */}
+
+  shouldCloseOnEsc={
+    true
+  /* Boolean indicating if pressing the esc key should close the modal
+     Note: By disabling the esc key from closing the modal
+     you may introduce an accessibility issue. */}
+
+  shouldReturnFocusAfterClose={
+    true
+  /* Boolean indicating if the modal should restore focus to the element
+     that had focus prior to its display. */}
+
+  role={
+    "dialog"
+  /* String indicating the role of the modal, allowing the 'dialog' role
+     to be applied if desired.
+     This attribute is `dialog` by default. */}
+
+  parentSelector={
+    () => document.body
+  /* Function that will be called to get the parent element
+     that the modal will be attached to. */}
+
+  aria={
+    {
+      labelledby: "heading",
+      describedby: "full_description"
+    }
+  /* Additional aria attributes (optional). */}
+
+  data={
+    { background: "green" }
+  /* Additional data attributes (optional). */}
+
+  overlayRef={
+    setOverlayRef
+  /* Overlay ref callback. */}
+
+  contentRef={
+    setContentRef
+  /* Content ref callback. */}>
+    <p>Modal Content</p>
+</ReactModal>
+```
+
+## [Using a custom parent node](#custom-parent)
+
+By default, the modal portal will be appended to the document's body.  You can
+choose a different parent element by providing a function to the
+`parentSelector` prop that returns the element to be used:
+
+```jsx
+<Modal
+  ...
+  parentSelector={() => document.querySelector('#root')}>
+  <p>Modal Content.</p>
+</Modal>
+```
+p
+If you do this, please ensure that your
+[app element](accessibility/README.md#app-element) is set correctly.  The app
+element should not be a parent of the modal, to prevent modal content from
+being hidden to screenreaders while it is open.
+
+## [Refs](#refs)
+
+You can use ref callbacks to get the overlay and content DOM nodes directly:
+
+```jsx
+<Modal
+  ...
+  overlayRef={node => (this.overlayRef = node)}
+  contentRef={node => (this.contentRef = node)}>
+  <p>Modal Content.</p>
+</Modal>
+```
+
+## [License](#license)
+
+MIT
diff --git a/docs/styles/classes.md b/docs/styles/classes.md
index 4b38d496..0176d9d9 100644
--- a/docs/styles/classes.md
+++ b/docs/styles/classes.md
@@ -1,5 +1,3 @@
-### CSS Classes
-
 Sometimes it may be preferable to use CSS classes rather than inline styles.
 react-modal can be configured to use CSS classes to style the modal content and
 overlay, as well as the document body and the portal within which the modal is
diff --git a/docs/styles/README.md b/docs/styles/index.md
similarity index 98%
rename from docs/styles/README.md
rename to docs/styles/index.md
index 02464875..5412b39f 100644
--- a/docs/styles/README.md
+++ b/docs/styles/index.md
@@ -1,5 +1,3 @@
-## Styles
-
 Styles passed into the Modal via the `style` prop are merged with the defaults.
 The default styles are defined in the `Modal.defaultStyles` object and are
 shown below.
diff --git a/docs/styles/transitions.md b/docs/styles/transitions.md
index b39ffa62..4e1e3155 100644
--- a/docs/styles/transitions.md
+++ b/docs/styles/transitions.md
@@ -1,5 +1,3 @@
-### Transitions
-
 Using [CSS classes](classes.md), it is possible to implement transitions for
 when the modal is opened or closed.  By placing the following CSS somewhere in
 your project's styles, you can make the modal content fade in when it is opened
diff --git a/docs/testing/README.md b/docs/testing/index.md
similarity index 100%
rename from docs/testing/README.md
rename to docs/testing/index.md
diff --git a/mkdocs.yml b/mkdocs.yml
new file mode 100644
index 00000000..9ae04756
--- /dev/null
+++ b/mkdocs.yml
@@ -0,0 +1,26 @@
+site_name: react-modal documentation
+site_dir: _book
+nav:
+  - Overview: index.md
+  - Accessibility: accessibility/index.md
+  - Styles:
+      - Inline Styles: styles/index.md
+      - Classes: styles/classes.md
+      - Transitions: styles/transitions.md
+  - Examples:
+      - Run local: examples/index.md
+      - Minimal: examples/minimal.md
+      - setAppElement: examples/set_app_element.md
+      - shouldCloseOnOverlayClick: examples/should_close_on_overlay_click.md
+      - onRequestClose: examples/on_request_close.md
+      - Global Overrides: examples/global_overrides.md
+      - Inline Styles: examples/inline_styles.md
+      - Css Classes: examples/css_classes.md
+  - Testing: testing/index.md
+  - Contributing:
+      - Overview: contributing/index.md
+      - Development setup: contributing/development.md
+theme:
+  name: 'material'     
+markdown_extensions:
+  - codehilite