diff --git a/docs/cmd/graph.md b/docs/cmd/graph.md
index 03fd77a35..6daaf5d47 100644
--- a/docs/cmd/graph.md
+++ b/docs/cmd/graph.md
@@ -4,8 +4,59 @@
 
 The `graph` command generates graphical representaitons of the deployed topology.
 
-Two graph styles are available, using [Graphviz](https://graphviz.org/) or using a HTML page generated by `containerlab` using a Go html template.
-
+Two graph styles are available, using [Graphviz](https://graphviz.org/) or using a HTML page generated by `containerlab` based on a Go html template.
+
+#### Graphviz
+
+PLACEHOLDER
+
+#### HTML
+
+The HTML based graph is created by rendering a [GoHTML](https://golang.org/pkg/html/template/) template against a `struct` containing the topology name as well as a `json` string where 2 lists are present: `nodes` and `links` .
+
+`nodes` contains data about the lab nodes, such as name, kind, type, image, state, IP addresses,...
+
+`links` contains the list of links defined by source node and target node, as well as the endpoint names
+
+```json
+{
+  "nodes": [
+    {
+      "name": "node1-1",
+      "image": "srlinux:20.6.1-286",
+      "kind": "srl",
+      "group": "tier-1",
+      "state": "running/Up 21 seconds",
+      "ipv4_address": "172.23.23.3/24",
+      "ipv6_address": "2001:172:23:23::3/80"
+    },
+    // omitted rest of nodes
+  ],
+  "links": [
+    {
+      "source": "node1-2",
+      "source_endpoint": "e1-1",
+      "target": "node2-1",
+      "target_endpoint": "e1-2"
+    },
+    {
+      "source": "node2-1",
+      "source_endpoint": "e1-4",
+      "target": "node3-1",
+      "target_endpoint": "e1-1"
+    },
+    // omitted rest of links 
+  ]
+}
+```
+
+Within the template Javascript libraries such as  [**d3js directed force graph**](https://observablehq.com/collection/@d3/d3-force) or [**vis.js network**](https://visjs.github.io/vis-network/docs/network/) can be used to generate custom topology graphs.
+
+`containerlab` comes with a (minimalistic) default template using [d3js](https://github.com/d3/d3-force).
+
+After the graph generation, it allows to freely move the nodes to a desired position then export the graph in PNG format
+
+![default_graph](../images/html_topo.png)
 
 ### Usage
 
@@ -19,13 +70,25 @@ With the global `--name | -n` flag a user sets the name of the lab that will be
 
 #### srv
 
-With `--srv` flag it is possible to set the 
+The `--srv` flag enables the HTML graph representation if present, it specifies an address a http server will listen to.
 
+A single path `/` is served, where the graph is generated based on either a default template or on the template supplied using `--template`
 
 #### template
 
-With `--template` flag it is possible to set the 
+The `--template` flag allows to customize the HTML based graph by supplying a user defined template that will be rendered and exposed on the address specified by `--srv`
 
 
 ### Examples
 
+```bash
+
+# generate topo1 graph using Graphviz
+containerlab graph --topo /path/to/topo1.yaml
+
+# start an http server on :3002 where topo1 graph will be rendered using the default template
+containerlab graph --topo /path/to/topo1.yaml --srv ":3002"
+
+# start an http server on :3002 where topo1 graph will be rendered using a custom template my_template.html
+containerlab graph --topo /path/to/topo1.yaml --srv ":3002" --template my_template.html
+```
\ No newline at end of file
diff --git a/docs/images/html_topo.png b/docs/images/html_topo.png
new file mode 100644
index 000000000..b87db018b
Binary files /dev/null and b/docs/images/html_topo.png differ
diff --git a/mkdocs.yml b/mkdocs.yml
index be4e81ed5..4bc986727 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -14,6 +14,7 @@ nav:
           - inspect: cmd/inspect.md
           - save: cmd/save.md
           - generate: cmd/generate.md
+          - graph: cmd/graph.md
   - Lab examples:
       - About: lab-examples/lab-examples.md
       - Single SR Linux node: lab-examples/single-srl.md