From 859cc2d467b4d872669f5e4a80563fe9a4bea8b1 Mon Sep 17 00:00:00 2001
From: Piya Das <piyadas2006@gmail.com>
Date: Tue, 27 Oct 2026 11:57:52 +0100
Subject: [PATCH] docs: add CLI reference page and link it from README

---
 docs/CLI.md    | 41 +++++++++++++++++++++++++++++++++++++++++
 docs/README.md |  2 ++
 2 files changed, 43 insertions(+)
 create mode 100644 docs/CLI.md

diff --git a/docs/CLI.md b/docs/CLI.md
new file mode 100644
index 0000000..6fc32f2
--- /dev/null
+++ b/docs/CLI.md
@@ -0,0 +1,41 @@
+# Command Line Interface
+
+## Commands
+
+MkDocs is used entirely from the command line. At this stage of the pre-release, there are two commands available:
+
+### `mkdocs build`
+
+Builds your documentation into a static site - a folder of HTML files you can host anywhere.
+
+```shell
+mkdocs build
+```
+
+By default, this reads your source files from `docs/` and writes the generated site to `site/`. You can change either location:
+
+```shell
+mkdocs build --dir SOURCE_DIRECTORY --output OUTPUT_DIRECTORY
+```
+
+**Note:** The list `mkdocs build` shows the source files it read, not the HTML files it generated - the build itself still completes correctly. ([Tracked as issue #61.](https://github.com/encode/mkdocs/issues/61))
+
+### `mkdocs serve`
+
+Starts a local development server so you can preview your site in a browser before publishing it.
+
+```shell
+mkdocs serve
+```
+
+By default, this serves your site at `http://127.0.0.1:8080`. Press `Ctrl+C` to stop it.
+
+Like `build`, you can change the source directory:
+
+```shell
+mkdocs serve --dir SOURCE_DIRECTORY
+```
+
+There's currently no option to change the address or port `serve` runs on. If something else on your machine is already using port 8080, you'll need to free it up first.
+
+**Note:** `serve` does not currently watch your files for changes - editing and saving a doc while the server is running does not trigger a rebuild or refresh the browser automatically. You'll need to refresh your browser manually, to see your latest edits.
\ No newline at end of file
diff --git a/docs/README.md b/docs/README.md
index 1f2a318..02a617e 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -18,6 +18,8 @@ This will install the version 2.0 pre-release. For full installation steps, incl
 2. Run `mkdocs serve` to view your documentation in a browser.
 3. Run `mkdocs build` to build a static website ready to host.
 
+For a full list of commands and options, see the [CLI Reference](CLI.md).
+
 ## Writing your docs
 
 1. Create additional markdown pages.