Problems running docs project locally

[Jcparkyn]

Describe the bug

There seem to be a few issues with running the docs project locally (I'm putting them all in one issue because I assume most are related):

1. The docs readme says to run docfx from docs/, but this gives an error Cannot find config file [...]\bUnit\docs\docfx.json. Should this be docfx site/docfx.json or "run from docs/site/"?

2. I get a compilation error when running docfx:

error: C:\Users\James\Files\git\ext\bUnit\src\bunit.web\Extensions\Internal\CssSelectorElementFactory.cs(6,51): error CS0246: The type or namespace name 
'IElementWrapperFactory' could not be found (are you missing a using directive or an assembly reference?)

3. From docs-deploy.yml, it looks like I shouldn't even be running docfx and instead use dotnet run Site.csproj?

4. Due to the above compilation error, the API spec doesn't get generated (with either of the above methods) unless I set "allowCompilationErrors": true in docfx.json.

5. docfx.min.js doesn't get loaded due to "Cannot use import statement outside a module". This is fixed by setting type="module" on the relevant script tag.

6. The deployed docs don't have correct formatting for block quotes (e.g. see "The current thread is not associated" at https://bunit.dev/docs/interaction/trigger-renders.html) - but this seems to be fixed when running locally.

7. Typo in "Verfiy docs samples" in docs-deploy.yml (doesn't cause any issues).

Version info:

• bUnit version: n/a
• .NET Runtime and Blazor version: n/a (.NET 8 SDK)
• OS type and version: Windows 10

Additional context:

I think some or all of these are related to #1286

[linkdotnet]

Good point and thanks for reporting - I will fix that

[linkdotnet]

Fixed by #1306

[linkdotnet]

For the time being @Jcparkyn

1. Build the whole bunit solution from the root folder
2. Go to docs/site and run dotnet run. That invokes the site generator.
3. Then you can use the dotnet serve tool - or the cmd file.

[linkdotnet]

If you rebase the current main branch it should be solved.
If not, let us know!

[Jcparkyn]

@linkdotnet I think problems 4 and 5 from above are still present (running from the latest main commit).

See this screenshot, where the TOC and search don't work, the xrefs are broken, and there was a SyntaxError from docfx.min.js:

I also have nothing generated in docs/site/api (which I assume is why the xrefs are broken).

[egil]

Yeah I think that late issue is due to the template needs updating.