diff --git a/compiler/ballerina-lang/src/main/java/io/ballerina/projects/BalaWriter.java b/compiler/ballerina-lang/src/main/java/io/ballerina/projects/BalaWriter.java
index 0d5e8ca23d67..970fff0d4f26 100644
--- a/compiler/ballerina-lang/src/main/java/io/ballerina/projects/BalaWriter.java
+++ b/compiler/ballerina-lang/src/main/java/io/ballerina/projects/BalaWriter.java
@@ -52,6 +52,7 @@
 import java.util.ArrayList;
 import java.util.Collection;
 import java.util.Collections;
+import java.util.HashMap;
 import java.util.HashSet;
 import java.util.List;
 import java.util.Map;
@@ -105,7 +106,7 @@ public Path write(Path balaPath) {
                                       this.packageContext.packageName().value(),
                                       this.packageContext.packageVersion().value().toString(),
                                       this.target);
-        // Create the archive over write if exists
+        // Create the archive overwrite if exists
         try (ZipOutputStream balaOutputStream = new ZipOutputStream(
                 new FileOutputStream(String.valueOf(balaPath.resolve(balaName))))) {
             // Now lets put stuff in
@@ -129,8 +130,7 @@ private void populateBalaArchive(ZipOutputStream balaOutputStream)
 
         addBalaJson(balaOutputStream);
         addPackageDoc(balaOutputStream,
-                      this.packageContext.project().sourceRoot(),
-                      this.packageContext.packageName().toString());
+                      this.packageContext.packageManifest());
         addPackageSource(balaOutputStream);
         addResources(balaOutputStream);
         addIncludes(balaOutputStream);
@@ -183,6 +183,8 @@ private void addPackageJson(ZipOutputStream balaOutputStream, Optional<JsonArray
         // Set graalvmCompatibility property in package.json
         setGraalVMCompatibilityProperty(packageJson, packageManifest);
 
+        setDocs(packageJson, packageManifest);
+
         // Remove fields with empty values from `package.json`
         Gson gson = new GsonBuilder().registerTypeHierarchyAdapter(Collection.class, new JsonCollectionsAdaptor())
                 .registerTypeHierarchyAdapter(String.class, new JsonStringsAdaptor()).setPrettyPrinting().create();
@@ -195,6 +197,27 @@ private void addPackageJson(ZipOutputStream balaOutputStream, Optional<JsonArray
         }
     }
 
+    private void setDocs(PackageJson packageJson, PackageManifest packageManifest) {
+        if (packageManifest.readme() == null) {
+            // ballerinai packages
+            return;
+        }
+        Map<String, String> docs = new HashMap<>();
+        String packageDocPathPrefix = BALA_DOCS_DIR + UNIX_FILE_SEPARATOR;
+        docs.put(packageManifest.descriptor().name().toString(),
+                packageDocPathPrefix + Paths.get(packageManifest.readme()).getFileName());
+        Map<String, PackageManifest.Modules> modules = packageManifest.modules();
+        for (Map.Entry<String, PackageManifest.Modules> module : modules.entrySet()) {
+            if (module.getValue().readme().isEmpty()) {
+                continue;
+            }
+            String moduleDoc = packageDocPathPrefix + MODULES_ROOT + UNIX_FILE_SEPARATOR + module.getKey() +
+                    UNIX_FILE_SEPARATOR + Paths.get(module.getValue().readme().get()).getFileName();
+            docs.put(module.getValue().name(), moduleDoc);
+        }
+        packageJson.setDocs(docs);
+    }
+
     private void setGraalVMCompatibilityProperty(PackageJson packageJson, PackageManifest packageManifest) {
         Map<String, PackageManifest.Platform> platforms = packageManifest.platforms();
         Boolean allPlatformDepsGraalvmCompatible = isAllPlatformDepsGraalvmCompatible(packageManifest.platforms());
@@ -253,20 +276,18 @@ private String otherPlatformGraalvmCompatibleVerified(String target,
 
     // TODO when iterating and adding source files should create source files from Package sources
 
-    private void addPackageDoc(ZipOutputStream balaOutputStream, Path packageSourceDir, String pkgName)
+    private void addPackageDoc(ZipOutputStream balaOutputStream, PackageManifest packageManifest)
             throws IOException {
-        final String packageMdFileName = "Package.md";
-        final String moduleMdFileName = "Module.md";
 
-        Path packageMd = packageSourceDir.resolve(packageMdFileName);
+        if (packageManifest.readme() == null) {
+            return;
+        }
+        Path pkgReadme = Paths.get(packageManifest.readme());
         Path docsDirInBala = Path.of(BALA_DOCS_DIR);
 
-        // If `Package.md` exists, create the docs directory & add `Package.md`
-        if (packageMd.toFile().exists()) {
-            Path packageMdInBala = docsDirInBala.resolve(packageMdFileName);
-            putZipEntry(balaOutputStream, packageMdInBala,
-                    new FileInputStream(String.valueOf(packageMd)));
-        }
+        Path packageMdInBala = docsDirInBala.resolve(pkgReadme.getFileName());
+        putZipEntry(balaOutputStream, packageMdInBala,
+                new FileInputStream(pkgReadme.toString()));
 
         // If `icon` mentioned in the Ballerina.toml, add it to docs directory
         String icon = this.packageContext.packageManifest().icon();
@@ -276,35 +297,16 @@ private void addPackageDoc(ZipOutputStream balaOutputStream, Path packageSourceD
             putZipEntry(balaOutputStream, iconInBala, new FileInputStream(String.valueOf(iconPath)));
         }
 
-        // If `Module.md` of default module exists, create `docs/modules` directory & add `Module.md`
-        Path defaultModuleMd = packageSourceDir.resolve(moduleMdFileName);
         Path modulesDirInBalaDocs = docsDirInBala.resolve(MODULES_ROOT);
 
-        if (defaultModuleMd.toFile().exists()) {
-            Path defaultModuleMdInBalaDocs = modulesDirInBalaDocs.resolve(pkgName).resolve(moduleMdFileName);
-            putZipEntry(balaOutputStream, defaultModuleMdInBalaDocs,
-                    new FileInputStream(String.valueOf(defaultModuleMd)));
-        }
-
-        // Add other module docs
-        File modulesSourceDir = new File(String.valueOf(packageSourceDir.resolve(MODULES_ROOT)));
-        File[] directoryListing = modulesSourceDir.listFiles();
-
-        if (directoryListing != null) {
-            for (File moduleDir : directoryListing) {
-                if (moduleDir.isDirectory()) {
-                    // Get `Module.md` path
-                    Path otherModuleMd = packageSourceDir.resolve(MODULES_ROOT).resolve(moduleDir.getName())
-                            .resolve(moduleMdFileName);
-                    // Create `package.module` folder, if `Module.md` path exists
-                    if (otherModuleMd.toFile().exists()) {
-                        Path otherModuleMdInBalaDocs = modulesDirInBalaDocs.resolve(pkgName + "." + moduleDir.getName())
-                                .resolve(moduleMdFileName);
-                        putZipEntry(balaOutputStream, otherModuleMdInBalaDocs,
-                                new FileInputStream(String.valueOf(otherModuleMd)));
-                    }
-                }
+        for (Map.Entry<String, PackageManifest.Modules> module : packageManifest.modules().entrySet()) {
+            if (module.getValue().readme().isEmpty()) {
+                continue;
             }
+            Path otherReadmeMdInBalaDocs = modulesDirInBalaDocs.resolve(module.getKey())
+                    .resolve(Paths.get(module.getValue().readme().get()).getFileName());
+            putZipEntry(balaOutputStream, otherReadmeMdInBalaDocs,
+                    new FileInputStream(module.getValue().readme().get()));
         }
     }
 
diff --git a/compiler/ballerina-lang/src/main/java/io/ballerina/projects/internal/ManifestBuilder.java b/compiler/ballerina-lang/src/main/java/io/ballerina/projects/internal/ManifestBuilder.java
index 2b0186935704..159d6d07f584 100644
--- a/compiler/ballerina-lang/src/main/java/io/ballerina/projects/internal/ManifestBuilder.java
+++ b/compiler/ballerina-lang/src/main/java/io/ballerina/projects/internal/ManifestBuilder.java
@@ -75,6 +75,7 @@
 import static io.ballerina.projects.internal.ManifestUtils.getBooleanFromTomlTableNode;
 import static io.ballerina.projects.internal.ManifestUtils.getBuildToolTomlValueType;
 import static io.ballerina.projects.internal.ManifestUtils.getStringFromTomlTableNode;
+import static io.ballerina.projects.util.ProjectConstants.DOT;
 import static io.ballerina.projects.util.ProjectUtils.defaultName;
 import static io.ballerina.projects.util.ProjectUtils.defaultOrg;
 import static io.ballerina.projects.util.ProjectUtils.defaultVersion;
@@ -226,7 +227,7 @@ private PackageManifest parseAsPackageManifest() {
 
                 String customReadmeVal = getStringValueFromTomlTableNode(pkgNode, README, null);
                 readme = validateAndGetReadmePath(pkgNode, customReadmeVal);
-                moduleEntries = getModuleEntries(pkgNode, customReadmeVal);
+                moduleEntries = getModuleEntries(pkgNode, customReadmeVal, packageDescriptor.name());
             }
         }
 
@@ -269,7 +270,7 @@ localRepoDependencies, otherEntries, diagnostics(), license, authors, keywords,
     }
 
     private Map<String, PackageManifest.Modules> getModuleEntries(
-            TomlTableNode pkgNode, String customReadmeVal) {
+            TomlTableNode pkgNode, String customReadmeVal, PackageName packageName) {
 
         Map<String, PackageManifest.Modules> moduleMap = new HashMap<>();
         Path modulesRoot = this.projectPath.resolve(ProjectConstants.MODULES_ROOT);
@@ -296,9 +297,9 @@ private Map<String, PackageManifest.Modules> getModuleEntries(
                         modReadme = modReadmePath.toString();
                     }
                     PackageManifest.Modules module = new PackageManifest.Modules(
-                            moduleDir.getFileName().toString(), false,
+                            packageName + DOT + moduleDir.getFileName().toString(), false,
                             Optional.empty(), Optional.ofNullable(modReadme));
-                    moduleMap.put(moduleDir.getFileName().toString(), module);
+                    moduleMap.put(packageName + DOT + moduleDir.getFileName().toString(), module);
                 }
                 return moduleMap;
             }
@@ -314,9 +315,9 @@ private Map<String, PackageManifest.Modules> getModuleEntries(
                     modReadme = modReadmePath.toString();
                 }
                 PackageManifest.Modules module = new PackageManifest.Modules(
-                        moduleDir.getFileName().toString(), false,
+                        packageName + DOT + moduleDir.getFileName().toString(), false,
                         Optional.empty(), Optional.ofNullable(modReadme));
-                moduleMap.put(moduleDir.getFileName().toString(), module);
+                moduleMap.put(packageName + DOT + moduleDir.getFileName().toString(), module);
             }
             return moduleMap;
         }
@@ -331,7 +332,14 @@ private Map<String, PackageManifest.Modules> getModuleEntries(
                     // TODO: report diagnostic - default module not allowed
                     continue;
                 }
-                if (Files.notExists(this.projectPath.resolve(ProjectConstants.MODULES_ROOT).resolve(moduleName))) {
+
+//                String[] moduleNameParts = moduleName.split(packageName + DOT);
+//                if (moduleNameParts.length < 2) {
+//                    // TODO: report diagnostic - invalid module provided. module not found
+//                    continue;
+//                }
+                if (Files.notExists(this.projectPath.resolve(ProjectConstants.MODULES_ROOT)
+                        .resolve(moduleName))) {
                     // TODO: report diagnostic - invalid module provided. module not found
                     continue;
                 }
@@ -348,9 +356,9 @@ private Map<String, PackageManifest.Modules> getModuleEntries(
                         modReadme = this.projectPath.resolve(modReadme).toString();
                     }
                 }
-                PackageManifest.Modules module = new PackageManifest.Modules(moduleName, export,
+                PackageManifest.Modules module = new PackageManifest.Modules(packageName + DOT + moduleName, export,
                         Optional.ofNullable(description), Optional.ofNullable(modReadme));
-                moduleMap.put(moduleName, module);
+                moduleMap.put(packageName + DOT + moduleName, module);
             }
         }
         return moduleMap;
diff --git a/compiler/ballerina-lang/src/main/java/io/ballerina/projects/internal/bala/PackageJson.java b/compiler/ballerina-lang/src/main/java/io/ballerina/projects/internal/bala/PackageJson.java
index 2cd780f68e82..6440b3879a7c 100644
--- a/compiler/ballerina-lang/src/main/java/io/ballerina/projects/internal/bala/PackageJson.java
+++ b/compiler/ballerina-lang/src/main/java/io/ballerina/projects/internal/bala/PackageJson.java
@@ -21,6 +21,7 @@
 import com.google.gson.JsonArray;
 
 import java.util.List;
+import java.util.Map;
 
 /**
  * {@code PackageJson} Model for Package JSON file.
@@ -57,6 +58,9 @@ public class PackageJson {
     private boolean template; //?
     private String template_version; //?
 
+    //Docs
+    private Map<String, String> docs;
+
     public PackageJson(String organization, String name, String version) {
         this.organization = organization;
         this.name = name;
@@ -221,4 +225,12 @@ public String getTemplateVersion() {
     public void setTemplateVersion(String template_version) {
         this.template_version = template_version;
     }
+
+    public Map<String, String> getDocs() {
+        return docs;
+    }
+
+    public void setDocs(Map<String, String> docs) {
+        this.docs = docs;
+    }
 }
diff --git a/langlib/jballerina.java/src/main/ballerina/Module.md b/langlib/jballerina.java/src/main/ballerina/Module.md
deleted file mode 100644
index ebb5474091d2..000000000000
--- a/langlib/jballerina.java/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,9 +0,0 @@
-## Module overview
-
-This module provides library operations required for Java interoperability in Ballerina. It includes a set of
- Ballerina annotations with which Java constructors, methods, and fields can provide implementations of Ballerina
-  functions with external function bodies.
-
-For information on the operations, which you can perform with the Java module, see the following learn page.
-- [Calling Java Code from Ballerina](https://ballerina.io/learn/user-guide/interoperability/calling-java-code-from-ballerina/)
-
diff --git a/langlib/lang.annotations/src/main/ballerina/Module.md b/langlib/lang.annotations/src/main/ballerina/README.md
similarity index 100%
rename from langlib/lang.annotations/src/main/ballerina/Module.md
rename to langlib/lang.annotations/src/main/ballerina/README.md
diff --git a/langlib/lang.array/src/main/ballerina/Module.md b/langlib/lang.array/src/main/ballerina/Module.md
deleted file mode 100644
index 6ddc730b3743..000000000000
--- a/langlib/lang.array/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.array` module corresponds to the `list` basic type.
diff --git a/langlib/lang.boolean/src/main/ballerina/Module.md b/langlib/lang.boolean/src/main/ballerina/Module.md
deleted file mode 100644
index d24a71e940b2..000000000000
--- a/langlib/lang.boolean/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.boolean` module corresponds to the `boolean` basic type.
diff --git a/langlib/lang.decimal/src/main/ballerina/Module.md b/langlib/lang.decimal/src/main/ballerina/Module.md
deleted file mode 100644
index ef3294b88813..000000000000
--- a/langlib/lang.decimal/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.decimal` module corresponds to the `decimal` basic type.
diff --git a/langlib/lang.error/src/main/ballerina/Module.md b/langlib/lang.error/src/main/ballerina/Module.md
deleted file mode 100644
index b673eec0ea72..000000000000
--- a/langlib/lang.error/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.error` module corresponds to the `error` basic type.
diff --git a/langlib/lang.float/src/main/ballerina/Module.md b/langlib/lang.float/src/main/ballerina/Module.md
deleted file mode 100644
index c45bacd9d1e2..000000000000
--- a/langlib/lang.float/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.float` module corresponds to the `float` basic type.
diff --git a/langlib/lang.function/src/main/ballerina/Module.md b/langlib/lang.function/src/main/ballerina/Module.md
deleted file mode 100644
index 6af2fefae196..000000000000
--- a/langlib/lang.function/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.function` module corresponds to the `function` basic type.
diff --git a/langlib/lang.future/src/main/ballerina/Module.md b/langlib/lang.future/src/main/ballerina/Module.md
deleted file mode 100644
index 47f15068f18f..000000000000
--- a/langlib/lang.future/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.future` module corresponds to the `future` basic type.
diff --git a/langlib/lang.int/src/main/ballerina/Module.md b/langlib/lang.int/src/main/ballerina/Module.md
deleted file mode 100644
index b36ba9231129..000000000000
--- a/langlib/lang.int/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.int` module corresponds to the `int` basic type.
diff --git a/langlib/lang.map/src/main/ballerina/Module.md b/langlib/lang.map/src/main/ballerina/Module.md
deleted file mode 100644
index 8c6b1a2d2742..000000000000
--- a/langlib/lang.map/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.map` module corresponds to the `mapping` basic type.
diff --git a/langlib/lang.object/src/main/ballerina/Module.md b/langlib/lang.object/src/main/ballerina/Module.md
deleted file mode 100644
index 10b7ac8806b8..000000000000
--- a/langlib/lang.object/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.object` module corresponds to the `object` basic type.
diff --git a/langlib/lang.query/src/main/ballerina/Module.md b/langlib/lang.query/src/main/ballerina/Module.md
deleted file mode 100644
index cab6e07419a1..000000000000
--- a/langlib/lang.query/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-This module provides lang library operations on `query-action`s & `query-expression`s.
\ No newline at end of file
diff --git a/langlib/lang.regexp/src/main/ballerina/Module.md b/langlib/lang.regexp/src/main/ballerina/Module.md
deleted file mode 100644
index 66c0797557ec..000000000000
--- a/langlib/lang.regexp/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.regexp` module corresponds to the `regexp` basic type.
diff --git a/langlib/lang.runtime/src/main/ballerina/Module.md b/langlib/lang.runtime/src/main/ballerina/Module.md
deleted file mode 100644
index a577d9fca025..000000000000
--- a/langlib/lang.runtime/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.runtime` module provides functions related to the language runtime that are not specific to a particular basic type.
diff --git a/langlib/lang.stream/src/main/ballerina/Module.md b/langlib/lang.stream/src/main/ballerina/Module.md
deleted file mode 100644
index 411f655fdf57..000000000000
--- a/langlib/lang.stream/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.stream` module corresponds to the `stream` basic type.
diff --git a/langlib/lang.string/src/main/ballerina/Module.md b/langlib/lang.string/src/main/ballerina/Module.md
deleted file mode 100644
index 95bf5515613b..000000000000
--- a/langlib/lang.string/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.string` module corresponds to the `string` basic type.
diff --git a/langlib/lang.table/src/main/ballerina/Module.md b/langlib/lang.table/src/main/ballerina/Module.md
deleted file mode 100644
index 5e9b53c654ef..000000000000
--- a/langlib/lang.table/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.table` module corresponds to the `table` basic type.
diff --git a/langlib/lang.transaction/src/main/ballerina/Module.md b/langlib/lang.transaction/src/main/ballerina/Module.md
deleted file mode 100644
index e4a6b40c4666..000000000000
--- a/langlib/lang.transaction/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.transaction` module supports transactions.
\ No newline at end of file
diff --git a/langlib/lang.typedesc/src/main/ballerina/Module.md b/langlib/lang.typedesc/src/main/ballerina/Module.md
deleted file mode 100644
index f4bdd6169fbe..000000000000
--- a/langlib/lang.typedesc/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.typedesc` module corresponds to the `typedesc` basic type. 
diff --git a/langlib/lang.value/src/main/ballerina/Module.md b/langlib/lang.value/src/main/ballerina/Module.md
deleted file mode 100644
index 937b6abc2ece..000000000000
--- a/langlib/lang.value/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.value` module provides functions that work on values of more than one basic type.
diff --git a/langlib/lang.xml/src/main/ballerina/Module.md b/langlib/lang.xml/src/main/ballerina/Module.md
deleted file mode 100644
index fdcbb17317b9..000000000000
--- a/langlib/lang.xml/src/main/ballerina/Module.md
+++ /dev/null
@@ -1,3 +0,0 @@
-## Module overview
-
-The `lang.xml` module corresponds to the `xml` basic type.