From 229bf0e3fe4c02018a7344ac1aab719eaa84f39e Mon Sep 17 00:00:00 2001
From: Hariom Verma <hariom.verma@tendermint.com>
Date: Tue, 16 Apr 2024 23:03:12 +0530
Subject: [PATCH] docs: namespaces concepts page (#1909)

Adds info about the namespaces and package/realm path.
---
 docs/concepts/namespaces.md | 35 +++++++++++++++++++++++++++++++++++
 misc/docusaurus/sidebars.js |  1 +
 2 files changed, 36 insertions(+)
 create mode 100644 docs/concepts/namespaces.md

diff --git a/docs/concepts/namespaces.md b/docs/concepts/namespaces.md
new file mode 100644
index 00000000000..74129697c88
--- /dev/null
+++ b/docs/concepts/namespaces.md
@@ -0,0 +1,35 @@
+---
+id: namespaces
+---
+
+# Namespaces
+
+Namespaces provide users with the exclusive capability to publish contracts under their designated namespaces, similar to GitHub's user and organization model.
+
+This feature is currently a work in progress (WIP). To learn more about namespaces, please checkout https://github.com/gnolang/gno/issues/1107.
+
+# Package Path
+
+A package path is a unique identifier for each package/realm. It specifies the location of the package source code which helps differentiate it from others. You can use a package path to:
+
+- Call a specific function from a package/realm. (e.g using `gnokey maketx call`)
+- Import it in other packages/realms.
+
+Here's a breakdown of the structure of a package path:
+
+- Domain: The domain of the blockchain where the package is deployed. Currently, only `gno.land/` is supported.
+- Type: Defines the type of package.
+    - `p/`: [Package](packages.md)
+    - `r/`: [Realm](realms.md)
+- Namespace: A namespace can be included after the type (e.g., user or organization name). Namespaces are a way to group related packages or realms, but currently ownership cannot be claimed. (see [Issue #1107](https://github.com/gnolang/gno/issues/1107) for more info)
+- Remaining Path: The remaining part of the path.
+    - Can only contain alphanumeric characters (letters and numbers) and underscores.
+    - No special characters allowed (except underscore).
+    - Cannot consist solely of underscores. It must have at least one allowed alphanumeric character.
+    - Cannot start with a number. It should begin with a letter.
+    - Cannot end with a trailing slash (`/`).
+
+Examples:
+
+- `gno.land/p/demo/avl`: This signifies a package named `avl` within the `demo` namespace.
+- `gno.land/r/gnoland/home`: This signifies a realm named `home` within the `gnoland` namespace.
diff --git a/misc/docusaurus/sidebars.js b/misc/docusaurus/sidebars.js
index 5a2533d7a44..b7dcc861290 100644
--- a/misc/docusaurus/sidebars.js
+++ b/misc/docusaurus/sidebars.js
@@ -45,6 +45,7 @@ const sidebars = {
             items: [
                 'concepts/realms',
                 'concepts/packages',
+                'concepts/namespaces',
                 {
                     type: 'category',
                     label: 'Standard Libraries',