Improve docs for mixed mode applications

[Neutrino-Sunset]

I'm trying to add Piranha to a Razor pages application and I'm finding the documentation so lacking that it's impossible to get a simple application running.

My attempt can be viewed here https://github.com/Neutrino-Sunset/PiranhaTest1

I've created a new Razor Pages application and followed the instructions in application-setup.

Without options.AddRazorRuntimeCompilation = true the app starts and displays the standard Index page for a new Razor pages application.

If I then navigate to ~\manager and publish an instance of SimplePage with the title First Page that then breaks the application, the default Index page no longer loads and returns 404. Editing the SimplePage I just created in the manager shows that it's been created with the default slug first-page, but navigating to that address also returns 404. The logging shows nothing useful like why the routing has failed, just loads of SQL queries.

I've had a look at the Razor template application and the startup for my code appears exactly the same as the template application. The template application isn't really useful in the case where you want to integrate Piranha into an existing application though, since it doesn't actually have any Razor pages mapped by the standard Razor Page routing at all, its entire content is served by Piranha.

Clearing the DB and adding options.AddRazorRuntimeCompilation = true the Index page loads, (very slowly) and with the footer broken and attached to the bottom of the content instead of at the bottom of the page.

If I then navigate to ~\manager and publish an instance of SimplePage with the title First Page that then breaks the application again, but in a different way. Now navigating to either the Index page or to first-page just renders my blank Page template.

The documentation on Routing and Advanced Routing has no information on how any of this works using Razor Pages and instead demonstrates an MVC controller based approach.

The Razor Pages template application uses pages that use a Piranha.Models.Page as a model instead of a standard AspNetCore.Mvc.RazorPages.PageModel, but unlike the controller based implementation described in the doucmentation this doesn't demonstrate how you would handle querystring arguments, nor how you would inject any dependencies into the model. I've attempted to achieve this using a standard Razor PageModel in my commented out Page.cshtml.cs but that doesn't work either.

I've been floundering with this for a few days now and could really use some help.

[Neutrino-Sunset]

Just in case it isn't clear from the last post I'm trying to achieve two key things.

1. I want to be able to serve standard Razor pages from some routes while the CMS handles other routes.
2. I want to be able to handle routing arguments and inject dependencies into my page models without having to resort to using controllers.

[Neutrino-Sunset]

I fixed the issue with the CMS not generating the pages correctly. That was caused by VS2022 corrupting my project file and excluding the Page.cshtml from the build. I pushed the fix for that to my repo.

I've also worked out how to implement the Razor page models so that dependency injection and querystring argument capture works in the conventional manner, (something not at all described by either the documentation nor the template project), and will upload the code for that too in case it helps someone else.

[tidyui]

Moving this to the documentation repo as it has nothing to do with the code itself.