diff --git a/README b/README
deleted file mode 100644
index 415c5b6..0000000
--- a/README
+++ /dev/null
@@ -1,34 +0,0 @@
-xbps-make: Minimal Package Builder for XBPS
-===========================================
-A lightweight, POSIX-compliant Makefile wrapper to automate building packages 
-for the XBPS package manager (used in Void Linux). Designed for developers who
-want a simple, scriptable interface to streamline package builds without 
-complex tooling.
-
-Features:
-	- Minimal dependecies (coreutils, xbps, bmake, git, curl, sed, tar, gzip)
-	- Declarative build system
-	- Hackable for other package managments
-	- Rebuilds only when necessary
-
-Usage:
-	bmake devel/tcc.src   # download source
-	bmake devel/tcc.xbps  # build and make package
-	bmake clean           # clean build directory if failed
-
-Options:
-	MAN=no                     (Do not install manuals)
-	POSIX=no                   (Do not install posix complice options)
-	BUILDDIR=path              (compile .src on path)
-	CACHEDIR=path              (save .src on path)
-	XBPSDIR=path               (save .xbps on path)
-
-Warning:
-	* This proyect it's used with bmake, other posix make programs
-	haven't been tested, but it should work, feel free to adapt it
-	if needed.
-	* GNU make doesn't work because the "include" command work 
-	diferent than posix make "include" command.
-
-Licence:
-	0BSD - Zero Clause BSD Licence
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b723fa8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,41 @@
+# xbps-make: Minimal Package Builder for XBPS
+A lightweight, POSIX-compliant Makefile wrapper to automate building packages 
+for the XBPS package manager (used in Void Linux). Designed for developers who
+want a simple, scriptable interface to streamline package builds without 
+complex tooling.
+
+## Features
+- Minimal dependecies (coreutils, xbps, bmake, git, curl, sed, tar, gzip)
+- Declarative build system
+- Hackable for other package managments
+- Rebuilds only when necessary
+
+## Usage
+```sh
+	bmake devel/tcc.src   # download source
+	bmake devel/tcc.xbps  # build and make package
+	bmake clean           # clean build directory if failed
+```
+
+## Options
+You can customize behavior with these environment variables:
+
+Variable|Description
+--------|------------
+MAN=no|Skip installinkg man pages
+POSIX=no|Skip installing POSIX-compilant options
+BUILDDIR=path|Set custom path to compile `.src` files
+CACHEDIR=path|Set custom cache directory fo `.src` files
+XBPSDIR=path|Set custom path to output directory for `.xbps` packages
+
+## Warning
+- This project is built with `bmake` (NetBSD make). Other POSIX-compliant make tools should work, but haven't been tested.
+- *GNU Make is not supported* — its include syntax is incompatible with POSIX make.
+
+## Licence
+0BSD – Zero Clause BSD License. See [LICENSE](./LICENSE) for details.
+Feel free to use, modify, and share freely — no restrictions.
+
+## Contributing
+Contributions are welcome! Feel free to submit issues or pull requests.
+For every issue please add a test