New card-based home page

[OsirisTerje]

Revisits the idea from #1026 (see discussion #1023). This is not just a new layout but a different way of presenting NUnit: organized around what users want to do, in their own words, with writing tests up front. Contributor and project material is gathered under Developer info.

This means we move from a NUnit technical perspective to a more user centric perspective.

The new home page (docs/index.md)

• Hero: the message ("Write tests you can trust, for any .NET code", including the analyzers), calls to action (Write your first test / Install NUnit / What's new in NUnit 5), popular topics phrased in user terms, and a sample test.
• The nine cards from WIP: New layout #1026, in the same order:

Card	Contents
Writing tests (featured, tall)	Guides: ordinary tests, setup and teardown, data driven tests, automating tests, checking several things at once, tests that depend on other tests, flaky and slow tests, organizing and selecting tests. Reference: attributes, assertions overview, fluent/classic/special assertions, assumptions, warnings, TestContext, analyzer rules
Getting started	Create a test project in Visual Studio, VS Code, Rider or from the command line, add NUnit to an existing project, pre-release builds, samples, upgrading to NUnit 5
News	Release notes for every component: what's new in NUnit 5, framework, test adapter, NUnit Analyzers (GitHub), console and engine (new page pointing to the GitHub releases; the notes up to 3.17 are linked from there), VS Test Generator
Run anywhere	Visual Studio/Rider/dotnet test, Microsoft.Testing.Platform, .runsettings, command line console, NUnitLite, choosing which tests to run, TestCentric GUI
NUnit Tech	Analyzers, engine, supported .NET versions, parallel execution, usage notes, result file format, API reference
Articles	Known problems, trace and debug output, troubleshooting the test adapter, test generator, more resources
Developer info	Teams, practices, coding standards, XML docs, contributions, issue tracking, specifications, NUnit internals, packaging
Advanced	Extending NUnit, custom constraints/attributes, action attributes, execution hooks, engine extensions
Archive (full-width strip at the bottom)	2.x docs, migrating to NUnit 4, breaking changes up to 4.0, upgrading from NUnit 2 and 3, Xamarin runners, and a link to the new Archive page with everything else

News, NUnit Tech and Articles only had placeholders in #1026. They are filled with existing pages here ; we have to adjust this as we go forward.

New user guides for writing tests

The three Writing tests guides from #1026 are ported into the existing articles/nunit/writing-tests/ folder, at the top of its menu:

• ordinary-tests.md: a first test, Arrange/Act/Assert, [SetUp]
• setup-and-teardown.md: [SetUp]/[TearDown], [OneTimeSetUp]/[OneTimeTearDown] and [SetUpFixture], when to use which, the order they run in, and what happens when setup fails
• data-driven-tests.md: [TestCase], ExpectedResult, [TestCaseSource]/TestCaseData, [ValueSource], parameterized fixtures
• automating-tests.md: letting NUnit generate cases with [Values], [Range], [Random], [Pairwise]/[Sequential], and theories. This page was empty in WIP: New layout #1026 and is new.

All code samples live in Snippets.NUnit/WritingTestsGuideExamples.cs, so they compile and run as tests. The Writing Tests menu entry now opens Ordinary tests instead of the attribute list.

Archive and menu clean-up

A new Archive page (articles/archive.md) and a single Archive section in the side menu collect the pages for older versions, deprecated features and tools that are no longer maintained. These pages are removed from their old menus but keep their URLs. See the plan in the PR comments for the full list.

No documents were moved

#1026 copied about 250 files into new folders. Apart from the three guides above, those were copies of existing pages. Moving them would break URLs that are linked from Stack Overflow, blogs and every NUnit Analyzer diagnostic (helpLinkUri). The landing page gives a user-oriented view over the existing structure instead.

Switching to the new home page

The new layout is now docs/index.md, so it is what readers see at the site root. The previous home page is kept as docs/classic.md and linked from the top menu as Classic Home, so it stays reachable while the new page settles. The preview banner and the layout-switch script from earlier commits are removed.

Other page updates

• NUnit introduction (articles/nunit/intro.md): rewritten. The docs cover NUnit 3 and later; NUnit 2 is a separate product, documented in the Archive.
• Test adapter overview (articles/vs-test-adapter/Index.md): rewritten for adapter 6: NUnit 3 to 5, VSTest and Microsoft.Testing.Platform, .NET Framework 4.6.2 and .NET 8 and later.

About HTML in Markdown

The DocFX default template has no per-page layout hook, so home.md is one HTML block with MD033 disabled for that file only. All styles are in custom_template/styles/main.css, scoped under .nh.

Checks

• docfx docs/docfx.json --warningsAsErrors true: 0 warnings, 0 errors (docfx 2.78.3, as in CI)
• dotnet test on the snippets: all new examples pass
• markdownlint and cspell pass on the changed files

🤖 Converted from earlier work (ref PR #102) and have been assisted by Claude Code to create this version.

[OsirisTerje]

Previewing the new home page

PRs no longer get a Netlify preview (it was removed in #1063). Each CI run does attach the built site as the siteArtifact artifact, so you can view it locally.

1. Download the artifact

• Latest build for this PR: NUnit Documentation Build Process, run 36240844819. Scroll to Artifacts at the bottom of the page and download siteArtifact. For newer commits, open the most recent run from the PR's Checks tab.

• Or, with the GitHub CLI:

  gh run download 36240844819 --repo nunit/docs --name siteArtifact

2. Unzip it (it is a zip inside a zip)

The artifact contains _site.zip, which contains the site under docs/_site/.

# macOS / Linux / Git Bash
unzip siteArtifact.zip        # skip if gh run download already extracted it, which it is most likely to do
unzip _site.zip

# PowerShell
Expand-Archive siteArtifact.zip -DestinationPath .   # skip if gh run download already extracted it
Expand-Archive _site.zip -DestinationPath .

3. Serve it

Serve the folder over HTTP. Opening the files straight from disk breaks search and some scripts. Any static server works, for example:

cd docs/_site
python -m http.server 8080
# or: npx serve -l 8080
# or: docfx serve .

4. Open the pages

• New home page: http://localhost:8080/ (or http://localhost:8080/index.html)
• Previous home page: http://localhost:8080/classic.html, also linked from the top menu as Classic Home
• New writing-tests guides: http://localhost:8080/articles/nunit/writing-tests/ordinary-tests.html

Alternatively, build it yourself: run serve in the dev container, or docfx docs/docfx.json --serve, and open http://localhost:8080/.

[Copilot]

Copilot review overview

🟡 Changes recommended

The preview links need corrected .html URLs, and the documented wording issues should be addressed.

Review effort: Lite
Findings: 2

Open (2)

• Use .html URLs for internal raw HTML anchors · New
• Use the published home.html URL for the preview link · New

What changed in this PR

Adds a preview card-based NUnit landing page, beginner writing-test guides, and compilable examples while retaining the classic homepage.

Changes:

• Adds the responsive preview homepage and layout switching.
• Adds Ordinary, Data-driven, and Automating Tests guides.
• Updates navigation and homepage links.

File	Summary
docs/​styles/​main.js	Adds persistent homepage layout switching.
docs/​snippets/​Snippets.NUnit/​WritingTestsGuideExamples.cs	Adds compilable guide examples.
docs/​index.md	Adds a preview link; moderate issue: use home.html instead of home.md.
docs/​home.md	Adds the card-based landing page; moderate issue: convert internal .md links to .html.
docs/​custom_template/​styles/​main.css	Adds scoped landing-page styling.
docs/​articles/​nunit/​writing-tests/​toc.yml	Updates writing-tests navigation.
docs/​articles/​nunit/​writing-tests/​ordinary-tests.md	Adds the ordinary-tests guide; nit regarding overly restrictive public-visibility wording.
docs/​articles/​nunit/​writing-tests/​data-driven-tests.md	Adds the data-driven-tests guide.
docs/​articles/​nunit/​writing-tests/​automating-tests.md	Adds the automating-tests guide; nit to qualify Pairwise “just enough” wording.
docs/​articles/​nunit/​toc.yml	Updates the NUnit section navigation.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[OsirisTerje]

Plan: placing the remaining documentation on the new landing page

This plan covers the pages in the old navigation (the left-hand menu under Articles and the classic home page) that
the new landing page (docs/home.md, PR #1246) does not link to yet. For each one it suggests where it should go.

No documents are moved. Every suggestion is a link from the landing page, a link from another page, or an entry in the
Archive, so all existing URLs keep working.

Ground rules

1. User language on the cards. Link text says what the reader wants to do ("Run tests from the command line"),
   not what the page is called internally ("Console Runner").
2. At most about eight links per card. When a card needs more, it links to a section page, and that page lists
   the rest. This keeps the landing page scannable.
3. Current versions up front, history in the Archive. Anything that only applies to NUnit 4.0 or earlier, or to
   discontinued tools, goes to the Archive.
4. Contributor material goes to Developer info. Internals, specifications and packaging are for people working
   on NUnit, not for people using it.

Worth lifting up

Going through the old menus turned up several topics that answer common user questions, but that today are only
reachable as attribute or adapter reference pages. They deserve more visibility than a plain card link.

Topic	Where it lives today	Suggestion
Running with Microsoft.Testing.Platform	Adapter menu, NUnit-And-Microsoft-Test-Platform.md	Add to Run anywhere and as a Popular chip. It is the newest way to run tests, and users moving from VSTest will look for it.
Configuring runs with .runsettings	Adapter menu, Tips-And-Tricks.md (the page title says "Tips and tricks")	Add to Run anywhere as Configuring with .runsettings. It is the full reference for dotnet test settings.
Tests that depend on other tests	Attribute pages [DependsOnTest] and [DependsOnFixture] (new in NUnit 5)	New short guide in Writing tests, and a Popular chip during the NUnit 5 launch. It replaces [Order] for most uses.
Flaky tests	Attribute pages [Retry] and [Repeat] (repeat with a success threshold is new in NUnit 5)	New short guide, Handling flaky tests, in Writing tests.
Tests that must finish in time	Attribute pages [CancelAfter], [Timeout] and [MaxTime]	Cover in the same guide as flaky tests, or a guide of its own, Slow and hanging tests.
Organizing and selecting tests	Attribute pages [Category], [Explicit] and [Ignore], the Test Selection Language, and dotnet test --filter	New short guide, Organizing and selecting tests, in Writing tests, linked from Run anywhere › Choosing which tests to run.
Checking several things at once	assertions/multiple-asserts.md	Add to the Writing tests guide list.
Supported .NET versions	Adapter menu, Supported-Frameworks.md	Add to NUnit Tech. It is a frequent question.
Known problems and workarounds	Adapter menu, Known-Problems.md	Add to Articles.

The new guides would follow the pattern of Ordinary tests, Data driven tests and Automating tests: a short
task-oriented page with tested snippets that links to the attribute reference for the details.

Already reachable, no change needed

These are not on the landing page, but a page that is on it lists them, so readers find them in one click.

Old menu entry	Reached from
Attribute Descriptions (all attribute pages)	Writing tests › Attributes
All constraint pages	Writing tests › Fluent assertions (Assert.That)
Classic and special assertion pages	Writing tests › Classic assertions / Special assertions
NUnit Analyzers rule pages (NUnit1001 and so on)	Writing tests › Analyzer rules
Framework extensibility interfaces (IApplyToTest and so on)	Advanced › Extending NUnit
Creating engine extensions (listeners, drivers, loaders, writers)	Advanced › Engine extensions
Release notes of each component	News
Xamarin runner getting-started pages	Archive › Xamarin runners

Suggested placements

Writing tests card

Page	Suggestion
Assertions overview (writing-tests/assertions/assertions.md)	Add to Reference as Assertions overview. It explains the constraint and classic models side by side.
Multiple Asserts (assertions/multiple-asserts.md)	Add to the guide list as Checking several things at once. It is a common question from users.
Assumptions (Assumptions.md) and Warnings (Warnings.md)	Add to Reference as Assumptions and warnings, or link both from the Ordinary tests guide.
TestContext (TestContext.md)	Add to Reference. It was on the first version of the page and is widely used.
TestCaseData, TestFixtureData	No card link. Both are already linked from the Data driven tests guide.
Randomizer Methods (Randomizer-Methods.md)	No card link. Link it from the Automating tests guide, next to [Random].
Template Based Test Naming (running-tests/Template-Based-Test-Naming.md)	Link it from the Data driven tests guide ("Giving test cases readable names").

Getting started card

Page	Suggestion
Downloading (getting-started/downloading.md)	Add as Pre-release and developer builds. The page is mostly about MyGet and pre-release packages.
NUnit License (nunit/license.md)	Not on a card. Add License to the line at the bottom of the page. The copyright line says 2004-2021 and should be checked.

Run anywhere card

Page	Suggestion
Microsoft.Testing.Platform (vs-test-adapter/NUnit-And-Microsoft-Test-Platform.md)	Add as Running with Microsoft.Testing.Platform. This is the newest way to run tests and deserves visibility.
Configuration with runsettings (vs-test-adapter/Tips-And-Tricks.md)	Move here from Articles as Configuring with .runsettings. The page is really the runsettings reference, and "Tips and tricks" undersells it.
Console Command Line (running-tests/Console-Command-Line.md)	Link it from the Command line console page, or add it here if we want the options one click away.
NUnitLite Options (running-tests/NUnitLite-Options.md)	Link it from the NUnitLite Runner page. No card link.
TestCentric GUI (external)	Add as Running tests in a GUI (TestCentric). It is the GUI runner users ask about.
Adapter Installation (vs-test-adapter/Adapter-Installation.md) and Usage (Usage.md)	No card link. The adapter overview page that the card links to should link to both.

NUnit Tech card

Page	Suggestion
Supported Frameworks (vs-test-adapter/Supported-Frameworks.md)	Add as Supported .NET versions. It answers a frequent question.
Adapter-Engine Compatibility (vs-test-adapter/Adapter-Engine-Compatibility.md)	Link it from Supported .NET versions. No card link.
Engine Getting Started and Test Engine API (nunit-engine/Getting-Started.md, Test-Engine-API.md)	Link them from The NUnit Engine page. No card link.
Usage notes: configuration files, assembly isolation, runtime and platform selection, engine parallel execution, test filters, XML formats, counting tests, debugging support	Add one link, Usage notes, to the Usage Notes page, which lists them all. The card title already points there, but a visible link helps.
NUnit Test Projects (running-tests/NUnit-Test-Projects.md)	Link it from the Usage notes page (next to NUnit Project XML Format).

Articles card

Page	Suggestion
Known Problems (vs-test-adapter/Known-Problems.md)	Add as Known problems and workarounds.
Resources (vs-test-adapter/Resources.md)	Add as More resources (blog posts and videos about NUnit).
Trace and Debug Output, adapter version (vs-test-adapter/Trace-and-Debug.md)	Link it from the framework Trace and debug output page, since both cover the same topic from each side.
Debugger Source-Stepping (vs-test-adapter/Adapter-Source-Stepping.md)	Link it from Debugging your tests.

Advanced card

Page	Suggestion
Execution Hooks (extending-nunit/Execution-Hooks.md)	Add as Execution hooks. It is a new extension point and is not listed anywhere else on the page.
Available Engine Extensions and Installing Engine Extensions (nunit-engine/extensions/)	Link them from the Engine extensions page. If users often need them (for example the TeamCity or NUnit V2 result writers), add Installing engine extensions to the card instead.

Developer info card

Page	Suggestion
Specifications (technical-notes/nunit-internals/specs/Specifications.md)	Add as Specifications. The classic home page lists it under Developer Documentation.
NUnit Internals and its pages (architecture, APIs, framework design, attribute hierarchy, test discovery and execution)	Add as NUnit internals, and move the link away from any user-facing card.
Packaging pages (extensions, console and engine, installer, V3/V4 adapter)	Replace the single Packaging link with a small Packaging index page that lists them, or link the framework page and add the others to it.

Archive

Page	Why
AssertionHelper (writing-tests/AssertionHelper.md)	Deprecated in NUnit 3.7. Should also be removed from the Writing Tests menu.
ListMapper (writing-tests/ListMapper.md)	Removed in NUnit 4.0. Should also be removed from the Writing Tests menu.
Addin Replacement in the Framework (technical-notes/usage/Addin-Replacement-in-the-Framework.md)	Describes the move away from NUnit 2 add-ins.
Visual Studio Support (technical-notes/usage/Visual-Studio-Support.md)	Needs a review first. If it only covers older Visual Studio versions, it belongs here.
NUnit 3.0 Architecture (2009)	Historical design document.
Test Generator release notes for VS2015 and VS2017/VS2019	Older Visual Studio versions.
Packaging the V2 Adapter (developer-info/Packaging-the-V2-Adapter.md)	The V2 adapter is no longer maintained.
Packaging the Installer (developer-info/Packaging-the-Installer.md)	Check whether the MSI installer is still produced. If not, archive it.
NUnit Project Editor (external, nunit-legacy)	The project lives in the nunit-legacy organization.
Towards NUnit 4 (nunit/Towards-NUnit4.md) and Notes Toward NUnit 4.0	Planning documents for a released version. Move from Articles and Developer info to the Archive.

Pages that need a decision

Page	Question
NUnit introduction (nunit/intro.md)	It says "This documentation covers NUnit 3.0 and higher". Update it for NUnit 5, or let the new landing page replace it and turn it into a short pointer.
Classic home page (index.md)	Once the new page is the default, keep the classic page for a while at a stable URL, or retire it.
Top navigation bar (Articles, API Reference)	When the new page becomes the default, consider top-level entries that match the cards (for example Write tests, Run tests, Tools, Release notes). This only changes toc.yml files, not document locations.
Adapter License (vs-test-adapter/Adapter-License.md)	Link it from the adapter overview page, or list it next to the NUnit license at the bottom of the landing page.

Suggested order of work

1. Lift up the user topics: the links and Popular chips from Worth lifting up, then the new guides (test
   dependencies, flaky and slow tests, organizing and selecting tests) one at a time.
2. Remaining card links: TestContext, Assertions overview, Downloading, TestCentric GUI, Execution hooks,
   Specifications, NUnit internals, and the Archive entries. These are link changes in docs/home.md only.
3. Cross-links between pages: the "link it from" items above, so every page is reachable in one click from a
   card.
4. Menu clean-up: remove the deprecated pages (AssertionHelper, ListMapper) from the Writing Tests menu and add
   the Archive entries to a single Archive menu section.
5. Decisions: the intro page, the classic home page and the top navigation bar.

[OsirisTerje]

How it looks now:

[stevenaw]

So far so good on my end @OsirisTerje .
I like the new look, and the usage-based guidance docs and archival of older docs are both nice improvements

[SeanKilleen]

Quite a bit of work you've put in! 👏

Aiming to review it tonight in a few hours.