From b816b96e28a63f6203af89b82834e0486de42bc4 Mon Sep 17 00:00:00 2001 From: Jan Ruhlaender Date: Mon, 9 Nov 2026 21:49:56 +0100 Subject: [PATCH 1/6] docs: explain why MDU, compare it with other tools, and add a contributing guide --- CONTRIBUTING.md | 40 ++++++++++++++++++++++++++++++++++++++++ Docs/OtherTools.md | 12 ++++++++++++ README.md | 11 +++++++++++ 3 files changed, 63 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..c74f2287 --- /dev/null +++ b/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 add your project to a discussion if it 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:/`. + +[`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). diff --git a/Docs/OtherTools.md b/Docs/OtherTools.md index b96b0287..b701c5ef 100644 --- a/Docs/OtherTools.md +++ b/Docs/OtherTools.md @@ -17,5 +17,17 @@ 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 | +| Markdown linter | Built in (`mdu lint`) | Plugins | Plugins | Plugins | — | +| 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 | +| Source files | Plain Markdown | Markdown with extensions | 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. diff --git a/README.md b/README.md index 79b006a0..2e397d2f 100644 --- a/README.md +++ b/README.md @@ -69,6 +69,17 @@ 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 + +- **One tool, nothing else to set up.** A standalone executable, a .NET tool, or a Docker image — themes, search, diagrams, and PDF export are included. +- **Plain Markdown.** Your files stay portable and 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 From 4f1216508d04c78d1d78a2e75b5d5261b88ce102 Mon Sep 17 00:00:00 2001 From: Jan Ruhlaender Date: Mon, 9 Nov 2026 21:52:44 +0100 Subject: [PATCH 2/6] docs: split installation and included features in Why MDU --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 2e397d2f..792614d5 100644 --- a/README.md +++ b/README.md @@ -71,7 +71,8 @@ Prefer a standalone executable or Docker? See the [installation guide](https://c ## Why MDU -- **One tool, nothing else to set up.** A standalone executable, a .NET tool, or a Docker image — themes, search, diagrams, and PDF export are included. +- **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. - **Plain Markdown.** Your files stay portable and 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. From ed1d7e2740d83e09717aaeb0de82fd2f0c4690d5 Mon Sep 17 00:00:00 2001 From: Jan Ruhlaender Date: Mon, 9 Nov 2026 21:57:16 +0100 Subject: [PATCH 3/6] docs: describe MDU's Markdown extensions accurately --- Docs/OtherTools.md | 2 +- README.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/Docs/OtherTools.md b/Docs/OtherTools.md index b701c5ef..47e74fd2 100644 --- a/Docs/OtherTools.md +++ b/Docs/OtherTools.md @@ -27,7 +27,7 @@ What each tool needs and brings without extra plugins: | Markdown linter | Built in (`mdu lint`) | Plugins | Plugins | Plugins | — | | 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 | -| Source files | Plain Markdown | Markdown with extensions | MDX | Markdown and MDX | Markdown with extensions | +| Page format | Markdown with extensions | Markdown with extensions | 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. diff --git a/README.md b/README.md index 792614d5..5f38980c 100644 --- a/README.md +++ b/README.md @@ -73,7 +73,7 @@ Prefer a standalone executable or Docker? See the [installation guide](https://c - **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. -- **Plain Markdown.** Your files stay portable and readable on GitHub, GitLab, or in any editor. +- **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. From 74a0556a84468c694b1896837bc553f467f84dd3 Mon Sep 17 00:00:00 2001 From: Jan Ruhlaender Date: Mon, 9 Nov 2026 21:58:19 +0100 Subject: [PATCH 4/6] docs: note Markdown support in Docusaurus --- Docs/OtherTools.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Docs/OtherTools.md b/Docs/OtherTools.md index 47e74fd2..68098aeb 100644 --- a/Docs/OtherTools.md +++ b/Docs/OtherTools.md @@ -27,7 +27,7 @@ What each tool needs and brings without extra plugins: | Markdown linter | Built in (`mdu lint`) | Plugins | Plugins | Plugins | — | | 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 | MDX | Markdown and MDX | Markdown with extensions | +| 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. From 23dacd056bfa23fed3ba4ce4350b802949a3ca7e Mon Sep 17 00:00:00 2001 From: Jan Ruhlaender Date: Mon, 9 Nov 2026 21:59:48 +0100 Subject: [PATCH 5/6] docs: list DocFX among other tools --- Docs/OtherTools.md | 1 + 1 file changed, 1 insertion(+) diff --git a/Docs/OtherTools.md b/Docs/OtherTools.md index 68098aeb..f0286460 100644 --- a/Docs/OtherTools.md +++ b/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 | From bc8ecad26839bfa06546e955225d51d646a47795 Mon Sep 17 00:00:00 2001 From: Jan Ruhlaender Date: Tue, 10 Nov 2026 20:21:53 +0100 Subject: [PATCH 6/6] docs: compare broken-link checks accurately and drop the discussions reference --- CONTRIBUTING.md | 2 +- Docs/OtherTools.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c74f2287..78ce0f86 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -7,7 +7,7 @@ Thanks for your interest in MDU! Bug reports, ideas, documentation fixes, and co - **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 add your project to a discussion if it uses MDU. +- **Tell others** about MDU, or open an issue to tell us about a project that uses MDU. ## Development setup diff --git a/Docs/OtherTools.md b/Docs/OtherTools.md index f0286460..01a5fd07 100644 --- a/Docs/OtherTools.md +++ b/Docs/OtherTools.md @@ -25,7 +25,8 @@ 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 | -| Markdown linter | Built in (`mdu lint`) | Plugins | Plugins | Plugins | — | +| 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 |