diff --git a/README.md b/README.md
new file mode 100644
index 0000000..27f161a
--- /dev/null
+++ b/README.md
@@ -0,0 +1,56 @@
+# Gitea Docker Image with Jupyter Support
+
+This repository builds a custom Gitea container image based on the official `docker.gitea.com/gitea` image and adds Python/Jupyter tooling for notebook rendering inside Gitea.
+
+## What this image includes
+
+- Gitea runtime from the official upstream image
+- `uv` for Python tool installation
+- Python runtime configured via `PYTHON_VERSION`
+- Jupyter and `nbconvert` for rendering `.ipynb` files in the Gitea markup pipeline
+- Typical Gitea data directories mounted under `/data/gitea` and `/data/git`
+
+This is intended for environments where notebooks should be previewed in Gitea and where the image must include the Jupyter rendering dependencies required by the app configuration.
+
+## Build
+
+```bash
+docker build \
+  --build-arg GITEA_VERSION=1.26.4 \
+  --build-arg PYTHON_VERSION=3.14 \
+  -t gitea-jupyter:latest .
+```
+
+The default build arguments are:
+
+- `GITEA_VERSION=1.26.4`
+- `PYTHON_VERSION=3.14`
+
+## Run
+
+```bash
+docker run -d \
+  --name gitea \
+  -p 3000:3000 \
+  -p 22:22 \
+  -v "$PWD/data:/data" \
+  gitea-jupyter:latest
+```
+
+Then open:
+
+- http://localhost:3000
+- SSH on port 22 if you are using Gitea's Git over SSH
+
+## Notebook rendering support
+
+The configured notebook pipeline is enabled with:
+
+```ini
+[markup.jupyter]
+ENABLED = true
+FILE_EXTENSIONS = .ipynb
+RENDER_COMMAND = "jupyter-nbconvert --stdin --stdout --to html --template basic"
+```
+
+This allows `.ipynb` files to be rendered as HTML within Gitea, which is useful for documentation and notebook-heavy repositories.