docs: add a custom DocFX theme, landing page, and guides

README.md

@@ -97,9 +97,12 @@ dotnet run --project src/ProjGraph.Mcp
 ### Analyze Project Dependencies
 
 ```bash
-# Tree format (default)
+# Mermaid format (default)
 projgraph visualize ./MySolution.sln
 
+# ASCII tree format
+projgraph visualize ./MySolution.sln --format tree
+
 # Mermaid format for documentation
 projgraph visualize ./MySolution.slnx --format mermaid --output docs/dependencies.mmd
 ```

docfx/docfx.json

@@ -20,14 +20,18 @@
   "build": {
     "content": [
       {
-        "files": ["api/*.yml"]
+        "files": [
+          "api/*.yml"
+        ]
       },
       {
         "files": [
           "index.md",
           "license.md",
           "toc.yml",
+          "guides/*.md",
           "guides/toc.yml",
+          "samples/toc.yml",
           "dev/toc.yml"
         ]
       },
@@ -66,14 +70,21 @@
     "dest": "_site",
     "template": [
       "default",
-      "modern"
+      "modern",
+      "templates/projgraph"
     ],
     "globalMetadata": {
       "_appTitle": "ProjGraph",
-      "_appFooter": "Made with DocFX.",
+      "_appFooter": "<div class=\"pg-footer\"><span>ProjGraph &mdash; diagrams from the code you already have</span><nav><a href=\"https://github.com/HandyS11/ProjGraph\">GitHub</a><a href=\"https://www.nuget.org/packages/ProjGraph.Cli\">NuGet</a><a href=\"https://github.com/HandyS11/ProjGraph/releases\">Releases</a><a href=\"https://github.com/HandyS11/ProjGraph/blob/develop/LICENSE\">MIT</a></nav></div>",
       "_enableSearch": true,
       "_appFaviconPath": "icon.png",
-      "pdf": false
+      "pdf": false,
+      "_appName": "ProjGraph",
+      "_appLogoPath": "icon.png",
+      "_gitContribute": {
+        "repo": "https://github.com/HandyS11/ProjGraph",
+        "branch": "develop"
+      }
     }
   }
 }

docfx/guides/getting-started.md

@@ -0,0 +1,117 @@
+---
+title: Getting started
+---
+
+# Getting started
+
+Install ProjGraph, point it at code you already have, and read the diagram it
+gives back. This page takes you through the first run for both the CLI and the
+MCP server. For the full set of flags on each command, see the
+[CLI reference](../../src/ProjGraph.Cli/README.md).
+
+## Before you start
+
+You need the [.NET 10 SDK](https://dotnet.microsoft.com/download) or later.
+Check what you have:
+
+```bash
+dotnet --version
+```
+
+ProjGraph reads source files directly. You do not need to build the project you
+are analysing, run a database, or apply migrations first.
+
+## Install the CLI
+
+```bash
+dotnet tool install -g ProjGraph.Cli
+```
+
+Confirm the tool is on your path. This lists the four commands and their
+options:
+
+```bash
+projgraph --help
+```
+
+If the command is not found, your shell has not picked up the global tools
+directory yet. Open a new terminal, or see
+[Troubleshooting](troubleshooting.md#projgraph-command-not-found).
+
+## Draw your first diagram
+
+Start with the solution you are standing in, because it needs no arguments
+beyond a path:
+
+```bash
+projgraph visualize ./MySolution.slnx
+```
+
+That prints a Mermaid graph to stdout, wrapped in a fenced code block ready to
+paste into Markdown. To read it in the terminal instead, ask for the tree:
+
+```bash
+projgraph visualize ./MySolution.slnx --format tree
+```
+
+Both render the same graph. [Output formats](output-formats.md) covers when to
+reach for which.
+
+## Draw the rest
+
+Each command takes a path and writes to stdout, so you can redirect it anywhere:
+
+```bash
+# Database schema, from an EF Core DbContext
+projgraph erd ./Data/LibraryContext.cs
+
+# One class, with its base types and dependencies
+projgraph classdiagram ./Models/Book.cs --inheritance --dependencies
+
+# Architectural metrics for the whole solution
+projgraph stats ./MySolution.slnx
+```
+
+Use `--output` rather than a shell redirect when you want the file written for
+you, including any missing directories:
+
+```bash
+projgraph erd ./Data/LibraryContext.cs --output docs/database-schema.md
+```
+
+## Use it from an AI assistant
+
+The MCP server exposes the same four analyses as tools an assistant can call,
+so you can ask about your architecture instead of remembering command names.
+
+Add the server to your MCP client's configuration. Replace `x.x.x` with the
+current version from
+[NuGet](https://www.nuget.org/packages/ProjGraph.Mcp):
+
+```json
+{
+  "servers": {
+    "ProjGraph.Mcp": {
+      "type": "stdio",
+      "command": "dnx",
+      "args": ["ProjGraph.Mcp@x.x.x", "--yes"]
+    }
+  }
+}
+```
+
+Restart the client, then ask it something that needs the tools:
+
+```text
+Show me the entity relationships in my DbContext.
+Which projects in this solution are referenced the most?
+```
+
+The [MCP reference](../../src/ProjGraph.Mcp/README.md) documents every tool,
+prompt, and resource the server provides.
+
+## Where to go next
+
+- [Output formats](output-formats.md) — pick between Mermaid, tree, and Markdown.
+- [Showcase](../../samples/README.md) — real commands and the diagrams they produced.
+- [Troubleshooting](troubleshooting.md) — when a diagram comes back empty.

docfx/guides/output-formats.md

@@ -0,0 +1,143 @@
+---
+title: Output formats
+---
+
+# Output formats
+
+Every ProjGraph command writes text to stdout. What that text *is* — a Mermaid
+diagram, an ASCII tree, or a fenced Markdown block — depends on the command, the
+`--format` flag, and whether you asked for a file. This page explains the
+choices so you can pick one deliberately.
+
+## The three renderings
+
+| Rendering | Available on | Shows | Renders as a picture in |
+| --- | --- | --- | --- |
+| `mermaid` | `visualize`, and always for `erd` / `classdiagram` | The whole graph, as diagram source | GitHub, GitLab, this site, VS Code |
+| `tree` | `visualize` | Each root expanded recursively through its whole chain | Nowhere — it is already the picture |
+| `flat` | `visualize` | Every project once, with its direct references only | Nowhere — it is already the picture |
+
+`erd` and `classdiagram` have no `--format` flag. Both always emit Mermaid,
+because an entity relationship diagram and a class diagram have no useful
+plain-text form.
+
+## Choosing between them
+
+`tree` and `flat` answer different questions, and the difference is not
+cosmetic.
+
+**Tracing what a project pulls in transitively? Use `tree`.** It starts from the
+projects nothing else references and expands each chain to its full depth. A
+project that appears more than once is expanded on first sight and marked
+`(see above)` afterwards, so the output stays finite:
+
+```bash
+projgraph visualize ./MySolution.slnx --format tree
+```
+
+```text
+🧪 ProjGraph.Tests.Contract
+└── ProjGraph.Mcp
+    └── ProjGraph.Lib
+        ├── ProjGraph.Lib.ClassDiagram
+        │   └── ProjGraph.Lib.Core
+        │       └── ProjGraph.Core
+        └── ProjGraph.Lib.Dependencies
+            └── ProjGraph.Lib.Core (see above)
+```
+
+**Auditing what each project references directly? Use `flat`.** Every project is
+listed exactly once, grouped by type, with only its immediate references. No
+chain is followed, so nothing is repeated and nothing is elided:
+
+```bash
+projgraph visualize ./MySolution.slnx --format flat
+```
+
+```text
+🔷 ProjGraph.Lib
+├── → ProjGraph.Lib.ClassDiagram
+├── → ProjGraph.Lib.Dependencies
+└── → ProjGraph.Lib.EntityFramework
+🔷 ProjGraph.Lib.ClassDiagram
+└── → ProjGraph.Lib.Core
+```
+
+**Committing to docs? Use `mermaid`,** which is the default for `visualize`:
+
+```bash
+projgraph visualize ./MySolution.slnx
+```
+
+The emoji mark the project type: 🔷 library, 🚀 executable, 🧪 test project.
+
+## Fenced or raw: what `--output` changes
+
+This is the part that surprises people. The same command produces two different
+things depending on where it is going:
+
+- **To stdout**, Mermaid arrives wrapped in a `mermaid` code fence, so you can
+  paste it straight into a Markdown file and have it render.
+- **To a file via `--output`**, the extension decides. Only `.mmd` suppresses
+  the fence — a `.mmd` file is already understood to contain nothing but a
+  diagram. Every other extension, `.md` included, keeps it.
+
+```bash
+# Fenced Markdown, ready to commit into a docs page
+projgraph visualize ./MySolution.slnx --output docs/dependencies.md
+
+# Raw Mermaid, for a tool that parses .mmd directly
+projgraph visualize ./MySolution.slnx --output docs/dependencies.mmd
+```
+
+Prefer `--output` over a shell redirect. It creates missing directories for you,
+and it is what selects the right fencing.
+
+## Piping the output
+
+`mermaid` keeps stdout clean: progress messages go to stderr, so a redirect
+captures the diagram and nothing else.
+
+`tree` and `flat` are written for a human at a terminal, and their progress
+header goes to stdout along with the graph. If you redirect them, that header
+lands in your file too. Use `--output`, which writes the rendered graph and
+leaves the progress message on the terminal where it belongs:
+
+```bash
+# Captures the header as well - probably not what you want
+projgraph visualize ./MySolution.slnx --format tree > deps.txt
+
+# Captures the graph, with its title block
+projgraph visualize ./MySolution.slnx --format tree --output deps.txt
+```
+
+The diagram's own title block is part of the render, so it is written to the
+file either way. Drop it with `--show-title false`.
+
+## Titles
+
+Every diagram carries a title block naming what was analysed. Drop it when you
+are embedding the diagram under a heading that already says the same thing:
+
+```bash
+projgraph erd ./Data/LibraryContext.cs --show-title false
+```
+
+`--show-title` is available on `visualize`, `erd`, and `classdiagram`.
+
+## What `stats` does instead
+
+`stats` is the exception: it reports numbers, not a graph, so it has no
+`--format` and no `--output`. It prints a formatted table to the terminal and
+nothing else.
+
+```bash
+projgraph stats ./MySolution.slnx --top 10
+```
+
+## Rendering Mermaid on this site
+
+The [showcase](../../samples/README.md) pages embed their Mermaid output
+directly, so you can see exactly what each command produces without running it.
+That is the same text the CLI writes — the pages are regenerated from the tool
+whenever it changes.

docfx/guides/toc.yml

@@ -1,3 +1,12 @@
+- name: 🚀 Start here
+- name: Getting started
+  href: getting-started.md
+- name: Output formats
+  href: output-formats.md
+- name: Troubleshooting
+  href: troubleshooting.md
+
+- name: 📖 Reference
 - name: CLI Guide
   href: ../../src/ProjGraph.Cli/README.md
 - name: MCP Guide