diff --git a/.github/assets/demo.png b/.github/assets/demo.png
new file mode 100644
index 0000000..adef019
Binary files /dev/null and b/.github/assets/demo.png differ
diff --git a/README.md b/README.md
index b5d2445..da0e98e 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,42 @@
 # 🚨 mdlinkt
 
 A CLI tool for detecting dead or inaccessible links in markdown files.
+
+## Usage
+
+To check a markdown file for dead or inaccessible links
+
+```console
+mdlinkt -file your-file.md
+```
+
+This will return each tested link and a summary message in an example markdown file containing 1 valid and 1 invalid file.
+
+```console
+mdlinkt -file test.md
+2023/12/12 12:00:00 ERROR Invalid link: https://probablynotvalid.com
+2023/12/12 12:00:00 INFO Summary: 1 valid links, 1 invalid links
+```
+
+Should you want more details on the links that are scanned, you may pass the `-verbose` flag.
+
+```console
+2023/12/12 12:00:00 INFO https://github.com: 200
+2023/12/12 12:00:00 ERROR Invalid link: https://probablynotvalid.com
+2023/12/12 12:00:00 INFO Summary: 1 valid links, 1 invalid links
+```
+
+In case of invalid links, the program will exit with exit code 1, making it perfect for usage in
+GitHub actions or other pipelines.
+
+## Hacking
+
+A nix flake is provided. Use `direnv allow` or `nix develop` to enter the development shell.
+
+### Contributing
+
+PRs are always welcome.
+
+## License
+
+**mdlinkt** is licensed under the GPLv3. See [LICENSE](LICENSE) for more details.