diff --git a/README.md b/README.md
index 33da441..eaf4d87 100644
--- a/README.md
+++ b/README.md
@@ -1 +1,20 @@
-# developer-portal-codebase
\ No newline at end of file
+# Developer Portal Codebase
+
+## Description
+**developer-portal-codebase** is an extension of the [Espressif Developer Portal](https://github.com/espressif/developer-portal).  
+This repository hosts source code used in **articles, workshops, examples, demos, and tests** that support ESP-IDF content published on the developer portal.
+
+It is **not** intended for the Hugo-based website code — instead, it serves as the technical foundation for code examples, educational materials, and developer resources shared on [developer.espressif.com](https://developer.espressif.com).
+
+## Repository Links
+
+- **Developer Portal:** [https://github.com/espressif/developer-portal](https://github.com/espressif/developer-portal)  
+- **Developer Site:** [https://developer.espressif.com](https://developer.espressif.com)
+
+## How to Clone
+
+To clone this repository locally:
+
+```bash
+git clone https://github.com/espressif/developer-portal-corebase.git
+cd developer-portal-corebase