diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..78ce0f8 --- /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 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:/`. + +[`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 b96b028..01a5fd0 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 | @@ -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. diff --git a/README.md b/README.md index 79b006a..5f38980 100644 --- a/README.md +++ b/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