diff --git a/.github/workflows/build-docs.yml b/.github/workflows/build-docs.yml
new file mode 100644
index 0000000..60842a3
--- /dev/null
+++ b/.github/workflows/build-docs.yml
@@ -0,0 +1,43 @@
+name: Build docs
+
+on:
+  pull_request:
+    branches:
+      - main
+  push:
+    branches:
+      - docs
+  workflow_dispatch:
+  
+jobs:
+
+  build-and-upload-artifact:
+    name: build
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install 'setuptools<50.0'
+          python -m pip install .[testing,docs]
+
+      - name: Build docs
+        run: |
+          python docs/replace_description_text.py
+          cd docs
+          make html
+          cd ..
+          
+      - name: Upload artifact
+        uses: actions/upload-artifact@v2
+        with:
+          name: docs
+          path: docs/_build/html
diff --git a/.github/workflows/deploy-docs.yml b/.github/workflows/deploy-docs.yml
new file mode 100644
index 0000000..9aa543e
--- /dev/null
+++ b/.github/workflows/deploy-docs.yml
@@ -0,0 +1,43 @@
+name: Deploy docs
+
+on:
+  push:
+    branches:
+      - main
+    tags:
+      - "v*" # Push events to matching v*, i.e. v1.0, v20.15.10
+  # Allows you to run this workflow manually from the Actions tab
+  workflow_dispatch:
+
+jobs:
+
+  build-and-deploy:
+    name: deploy 
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Set up Python 3.9
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.9
+
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install 'setuptools<50.0'
+          python -m pip install .[testing,docs]
+
+      - name: Build docs
+        run: |
+          python docs/replace_description_text.py
+          cd docs
+          make html
+          cd ..
+
+      - name: Deploy docs 🚀
+        uses: JamesIves/github-pages-deploy-action@4.1.5
+        with:
+          branch: gh-pages
+          folder: docs/_build/html
diff --git a/docs/conf.py b/docs/conf.py
index 9a8289f..2d32dd0 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -31,6 +31,7 @@
 # ones.
 extensions = [
         'sphinx.ext.ifconfig',
+        'myst_parser',
         ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -38,8 +39,8 @@
 
 # The suffix(es) of source filenames.
 # You can specify multiple suffix as a list of string:
-# source_suffix = ['.rst', '.md']
-source_suffix = '.rst'
+source_suffix = ['.rst', '.md']
+# source_suffix = '.rst'
 
 # The encoding of source files.
 #source_encoding = 'utf-8-sig'
@@ -110,7 +111,7 @@
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for
 # a list of builtin themes.
-html_theme = 'alabaster'
+html_theme = 'furo'
 
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
diff --git a/docs/index.rst b/docs/index.rst
index 0450bd6..d44b710 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -6,11 +6,14 @@
 Welcome to affinder's documentation!
 ===============================================================
 
-Contents:
-
 .. toctree::
    :maxdepth: 2
 
+   usage
+
+
+.. include:: ../README.md
+   :parser: myst_parser.sphinx_
 
 
 Indices and tables
diff --git a/docs/replace_description_text.py b/docs/replace_description_text.py
new file mode 100644
index 0000000..096b26d
--- /dev/null
+++ b/docs/replace_description_text.py
@@ -0,0 +1,18 @@
+"""
+for ../.napari/DESCRIPTION.md
+find URLs ending in .mp4 and replace URL wrapped in HTML video tag 
+"""
+
+replacement_url = '<video width="640" height="480" controls>\n\
+    <source src="{}" type="video/mp4">\n\
+Your browser does not support the video tag.\n\
+</video>\n'
+new_text = ""
+
+with open(".napari/DESCRIPTION.md", 'r+') as desc_file:
+    for line in desc_file:
+        if line.strip().startswith("https://user-images.githubusercontent") and line.strip().endswith(".mp4"):
+            line = replacement_url.format(line.strip())
+        new_text += line
+    desc_file.seek(0)
+    desc_file.write(new_text)
diff --git a/docs/usage.rst b/docs/usage.rst
new file mode 100644
index 0000000..2ee172f
--- /dev/null
+++ b/docs/usage.rst
@@ -0,0 +1,5 @@
+Using affinder
+==============
+
+.. include:: ../.napari/DESCRIPTION.md
+   :parser: myst_parser.sphinx_
diff --git a/setup.cfg b/setup.cfg
index a32ae97..4f88f12 100644
--- a/setup.cfg
+++ b/setup.cfg
@@ -53,7 +53,8 @@ testing =
     pytest-qt
     scikit-image[data]
     napari[pyqt5]
-    zarr
-
+docs = 
+    furo
+    myst-parser
 [options.package_data]
 affinder = napari.yaml