diff --git a/README.md b/README.md
index 8676b2a..4feeebf 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,102 @@
-# luadocs
-darktable lua documentation
+# darktable Lua Documentation
+
+This is the user documentation for the [darktable](https://darktable.org) [Lua](https://lua.org) extensions. The content is authored in markdown and rendered to HTML using [Hugo](https://gohugo.io) and to PDF and ePub using the [DITA Open Toolkit](https://dita-ot.org).
+
+The auto-built version of the website can be found at https://darktable-org.github.io/luadocs/.
+
+## Contributing
+
+Please see https://darktable-org.github.io/dtdocs/special-topics/contributing/ for information about contributing content
+
+## Obtaining and Building
+
+### Cloning
+
+The theme for the site uses https://gitlab.com/patdavid/hugo-bootstrap-bare as a git submodule.
+In order to clone this submodule along with the site you just need to add the flag `--recurse-submodules` to the clone command:
+
+    git clone --recurse-submodules https://github.com/darktable-org/dtdocs.git
+
+If you already have the site cloned, but haven't included the submodule before:
+
+    git submodule update --init --recursive
+
+
+### Hugo
+
+This site is built with the static site generator Hugo (*extended*).
+Currently v0.75.1 extended:
+```
+$ ./hugo version
+Hugo Static Site Generator v0.73.0/extended windows/amd64 BuildDate: unknown
+```
+
+#### SASS
+
+If cloning the repo fresh, remember to build the bootstrap assets locally:
+
+```
+$ cd ./themes/hugo-bootstrap-bare/assets/
+$ yarn install (or alternatively `npm install`)
+$ cd ../../hugo-darktable-docs-theme/assets/
+$ yarn install
+```
+
+### Updating
+
+If you have the repo cloned but need to update things, it helps to make sure everything is up to date (since we are also using a submodule for the base theme).
+
+As normal, from the project root directory, update things like normal:
+```
+git pull
+```
+
+Double check that the submodule is being updated as well:
+```
+git submodule update --init --recursive
+```
+
+And finally make sure the assets are built:
+```
+cd themes/hugo-bootstrap-bare/assets/
+yarn install (or alternatively `npm install`).
+```
+This should get things up and running.
+
+
+### Building
+
+You can build the HTML website locally, the production site to deploy to hosting, or the PDF.
+
+## Local Website
+
+Building the site to test locally can be done from the root of the repo.
+
+```
+$ hugo server -D --disableFastRender
+```
+
+The site should then be available at http://localhost:1313/dtdocs/
+
+## Production Website
+
+Run the `hugo` command:
+
+```
+hugo
+```
+
+The static files are now available to deploy to a webhost in the `public` directory. This is currently performed automatically when new changes are pushed to the master branch, via github Actions.
+
+## PDF
+
+Ensure you have the [`weasyprint`](https://weasyprint.org) application installed; this will transform the generated HTML to PDF.
+
+```
+mkdir -p public
+hugo server --disableFastRender --config config-pdf.yaml
+weasyprint http://localhost:1313/dtdocs/index.html public/darktable_lua_documentation.pdf
+pkill hugo
+```
+
+The PDF is available in the `public` directory.
diff --git a/content/lua.api/_index.html b/content/lua.api.manual/_index.html
similarity index 82%
rename from content/lua.api/_index.html
rename to content/lua.api.manual/_index.html
index 610cbd0..24aa1e7 100644
--- a/content/lua.api/_index.html
+++ b/content/lua.api.manual/_index.html
@@ -1,6 +1,6 @@
 ---
 title: Lua API Manual
-id: Lua Scripts Manual
+id: Lua API Manual
 weight: 30
 draft: false
 author: "people"
@@ -8,4 +8,4 @@ author: "people"
 
 <p>
 The Lua API manual is currently being converted.
-</p>
\ No newline at end of file
+</p>
diff --git a/content/lua.scripts.manual/scripts/official/check_for_updates.md b/content/lua.scripts.manual/scripts/official/check_for_updates.md
index 466b542..c70cba5 100644
--- a/content/lua.scripts.manual/scripts/official/check_for_updates.md
+++ b/content/lua.scripts.manual/scripts/official/check_for_updates.md
@@ -17,7 +17,7 @@ when there is something. it will only check on startup and only once a week.
 
 ## Usage
 
-* install luasec and cjson for Lua 5.2 on your system
+* install luasec and cjson for Lua 5.3 on your system
 * require this script from your main lua file
 * restart darktable