From ac5c80c992aeff0bbb3482a5cc83c6726ed43298 Mon Sep 17 00:00:00 2001
From: Dean Chen <862469039@qq.com>
Date: Sat, 15 Aug 2026 17:52:37 +0500
Subject: [PATCH] docs(top): add process list examples

Show the default table and passing extra args through to ps
on Linux.

Fixes #588

Signed-off-by: Dean Chen <862469039@qq.com>
---
 docs/reference/commandline/container_top.md | 25 +++++++++++++++++++++
 docs/reference/commandline/top.md           | 25 +++++++++++++++++++++
 2 files changed, 50 insertions(+)

diff --git a/docs/reference/commandline/container_top.md b/docs/reference/commandline/container_top.md
index 7974577c69aa..fc9196c47914 100644
--- a/docs/reference/commandline/container_top.md
+++ b/docs/reference/commandline/container_top.md
@@ -9,3 +9,28 @@ Display the running processes of a container
 
 
 <!---MARKER_GEN_END-->
+
+## Description
+
+The `docker top` command shows the processes running inside a container.
+
+On Linux, extra arguments after the container name are passed through to
+`ps`. On Windows, those extra arguments aren't supported.
+
+## Examples
+
+### Show processes in a container
+
+```console
+$ docker top my-container
+UID                 PID                 PPID                C                   STIME               TTY                 TIME                CMD
+root                1853                1838                0                   12:01               ?                   00:00:00            nginx: master process nginx -g daemon off;
+```
+
+### Pass options through to ps (Linux)
+
+```console
+$ docker top my-container -o pid,comm
+PID                 COMMAND
+1853                nginx
+```
diff --git a/docs/reference/commandline/top.md b/docs/reference/commandline/top.md
index b35f4920316f..ab323e3e598f 100644
--- a/docs/reference/commandline/top.md
+++ b/docs/reference/commandline/top.md
@@ -10,3 +10,28 @@ Display the running processes of a container
 
 <!---MARKER_GEN_END-->
 
+## Description
+
+The `docker top` command shows the processes running inside a container.
+
+On Linux, extra arguments after the container name are passed through to
+`ps`. On Windows, those extra arguments aren't supported.
+
+## Examples
+
+### Show processes in a container
+
+```console
+$ docker top my-container
+UID                 PID                 PPID                C                   STIME               TTY                 TIME                CMD
+root                1853                1838                0                   12:01               ?                   00:00:00            nginx: master process nginx -g daemon off;
+```
+
+### Pass options through to ps (Linux)
+
+```console
+$ docker top my-container -o pid,comm
+PID                 COMMAND
+1853                nginx
+```
+