diff --git a/README.md b/README.md
new file mode 100644
index 0000000..07f998a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,136 @@
+# hugo-theme-paradox
+
+Paradox is a theme for Hugo intended documentation sites.
+
+## Features and recommendations
+
+### config.toml
+
+general config settings you might want to use
+
+```toml
+baseURL = 'https://docs.pixelfed.org/'
+languageCode = 'en-us'
+title = 'Pixelfed Documentation'
+theme = 'paradox'
+defaultContentLanguage = 'en'
+enableGitInfo = true
+
+disableKinds = ["taxonomy"]
+ignoreErrors = ["error-disable-taxonomy"]
+
+[languages]
+[languages.en]
+contentDir = 'content/en'
+languageName = 'English'
+weight = 1
+
+[frontmatter]
+lastmod = ["lastmod", ":git", "date", "publishDate"]
+
+[markup.tableOfContents]
+ordered = true
+
+[markup.goldmark.renderer]
+unsafe = true
+
+[markup.highlight]
+codeFences = true
+lineNumbersInTable = false
+tabWidth = 3
+noClasses = false
+```
+
+To get search working:
+
+```toml
+[outputs]
+home = ["HTML", "RSS", "JSON"]
+page = ["HTML"]
+```
+
+Theme-specific features and parameters:
+
+```toml
+[params]
+icon = "https://avatars0.githubusercontent.com/u/38410642?s=200&v=4"
+title = "Pixelfed documentation" # sets the header title separately from metadata (may be removed in the future? idk if the top-level title should always be the same)
+forge = "github" # github, gitea
+# forgeUrl = "https://git.trwnh.com" # if set to gitea
+repo = "pixelfed/docs" # the path to the repo
+branch = "main" # the branch to use for edits
+autonumbering = true # global default for whether to autonumber section headings (can also be used on a per-page level via frontmatter params)
+# borders = true # whether to use borders to separate the layout
+```
+
+main menu (goes in header for now)
+
+```toml
+[menu]
+[[menu.main]]
+identifier = 'pixelfed'
+name = 'pixelfed.org'
+url = 'https://pixelfed.org'
+weight = 10
+pre = ''
+
+[[menu.main]]
+identifier = 'github'
+name = 'pixelfed/docs'
+url = 'https://github.com/pixelfed/docs'
+weight = 20
+pre = ''
+```
+
+you can also put a simple/short menu in the footer (currently intended for attribution info)
+
+```toml
+[[menu.footer]]
+identifier = "copyright"
+name = "CC BY-SA 4.0"
+url = "https://creativecommons.org/licenses/by-sa/4.0/"
+weight = 10
+pre = ''
+```
+
+next to the footer menu there is a social menu intended for icon links
+
+```toml
+[[menu.social]]
+identifier = "mastodon"
+pre = ''
+url = "https://mastodon.social/@pixelfed"
+weight = 10
+
+[[menu.social]]
+identifier = "pixelfed"
+pre = ''
+url = "https://pixelfed.social/pixelfed"
+weight = 15
+
+[[menu.social]]
+identifier = "twitter"
+pre = ''
+url = "https://twitter.com/pixelfed"
+weight = 20
+
+[[menu.social]]
+identifier = "github"
+pre = ''
+url = "https://github.com/pixelfed/pixelfed"
+weight = 30
+```
+
+### frontmatter
+
+anything put in the docs menu will be available as in the big beefy menu section (which becomes a sidebar when the page is wide enough)
+
+```toml
+title = "Generic installation guide"
+summary = "How to set up everything you need to run your own Pixelfed instance."
+weight = 20
+[menu]
+[menu.docs]
+identifier = "admin/installation"
+parent = "admin"
+```
\ No newline at end of file