docs: explain why MDU, compare it with other tools, and add a contributing guide

CONTRIBUTING.md

@@ -0,0 +1,40 @@
+# Contributing to MDU
+
+Thanks for your interest in MDU! Bug reports, ideas, documentation fixes, and code are all welcome.
+
+## Ways to help
+
+- **Report a bug or ask a question** in the [issue tracker](https://github.com/capjan/mdu/issues). Include the `mdu --version` output, the command you ran, and a small Markdown example if possible.
+- **Pick an issue** labeled [`good first issue`](https://github.com/capjan/mdu/labels/good%20first%20issue) or [`help wanted`](https://github.com/capjan/mdu/labels/help%20wanted). Comment on it so others know you are working on it.
+- **Improve the documentation** in the [`Docs`](Docs) folder. It is plain Markdown and rendered by MDU itself.
+- **Tell others** about MDU, or open an issue to tell us about a project that uses MDU.
+
+## Development setup
+
+The [.NET 10 SDK](https://dotnet.microsoft.com/download) is all you need to build, test, and run MDU.
+
+```bash
+dotnet restore Mdu.sln
+dotnet build Mdu.sln
+dotnet test Mdu.sln
+dotnet doctor fix            # installs the local Git hooks
+```
+
+Preview the documentation with your local build:
+
+```bash
+dotnet run --project Source/Mdu -- serve Docs
+```
+
+Open the preview at `http://127.0.0.1:<port>/`.
+
+[`AGENTS.md`](AGENTS.md) describes the architecture and the repository conventions in more detail.
+
+## Pull requests
+
+- Keep a pull request focused on one change and add tests for new behavior.
+- Commit messages and pull request titles follow [Conventional Commits](https://www.conventionalcommits.org/), for example `feat(renderer): add …` or `fix(lint): …`. The changelog and the version are generated from them.
+- Keep existing CLI commands, aliases, and arguments working.
+- Build tools, generators, and tests use .NET only.
+
+By contributing, you agree that your contribution is released under the [MIT License](LICENSE).

Docs/OtherTools.md

@@ -9,6 +9,7 @@ MDU focuses on one job: publishing a folder of plain Markdown with a single tool
 
 | Tool | Built on | Typical use |
 | --- | --- | --- |
+| [DocFX](https://dotnet.github.io/docfx/) | .NET | API reference generated from .NET code, combined with conceptual Markdown docs |
 | [Docusaurus](https://docusaurus.io/) | React, Node.js | Product documentation with MDX components, versions, and translations |
 | [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) | MkDocs, Python | Feature-rich MkDocs theme; end of life on **May 5, 2027** |
 | [MkDocs](https://www.mkdocs.org/) | Python | Simple project documentation configured in one YAML file |
@@ -17,5 +18,18 @@ MDU focuses on one job: publishing a folder of plain Markdown with a single tool
 | [VuePress](https://vuepress.vuejs.org/) | Vue | Documentation with Vue components in Markdown |
 | [Zensical](https://zensical.org/) | Python, Rust | Successor to Material for MkDocs from the same team |
 
+## How MDU compares
+
+What each tool needs and brings without extra plugins:
+
+| | MDU | Material for MkDocs | Docusaurus | Starlight | DocFX |
+| --- | --- | --- | --- | --- | --- |
+| Runtime to build the site | None (standalone executable) or .NET | Python | Node.js | Node.js | .NET |
+| Broken links | Error in `mdu lint`, including anchors | Build warning, error with `--strict` | Build error | Plugins | Build warning |
+| Path casing and structure checks | Built in (`mdu lint`) | — | — | — | — |
+| Diagrams | Static SVG at build time, no JavaScript | Mermaid in the browser | Mermaid in the browser | Plugins | Mermaid in the browser |
+| PDF export | Built in (`mdu pdf`) | Plugins | Plugins | Plugins | Built in |
+| Page format | Markdown with extensions | Markdown with extensions | Markdown and MDX | Markdown and MDX | Markdown with extensions |
+
 > [!TIP]
 > Coming from Material for MkDocs? MDU understands the same icon shortcodes, and [`mdu fix`](./Usage/fix.md#migrating-mkdocs-material-markdown) converts admonitions, tabs, card grids, and `.pages` files to portable Markdown.

README.md

@@ -69,6 +69,18 @@ mdu render                   # build the site into ./site
 
 Prefer a standalone executable or Docker? See the [installation guide](https://capjan.github.io/mdu/Setup/).
 
+## Why MDU
+
+- **Install it your way.** As a standalone executable, a .NET tool, or a Docker image.
+- **Everything included.** Theme, navigation, search, and icons work out of the box, with no plugins to choose.
+- **Portable Markdown.** Callouts use the GitHub syntax and diagrams are code blocks, so your files stay readable on GitHub, GitLab, or in any editor.
+- **Checked in CI.** `mdu lint` finds broken links, wrong link casing, and unknown tags before you publish.
+- **Diagrams without JavaScript.** Mermaid flowcharts, sequence and state diagrams, and PlantUML component diagrams become static SVG with light and dark themes.
+- **PDF included.** `mdu pdf` exports the whole site as one document.
+- **Coming from Material for MkDocs?** The icon shortcodes work as they are, and `mdu fix` converts admonitions, tabs, and card grids.
+
+See [how MDU compares](https://capjan.github.io/mdu/OtherTools.html#how-mdu-compares) with Material for MkDocs, Docusaurus, Starlight, and DocFX.
+
 ## Explore the documentation
 
 <table>