search

dotnet / docfx

Static site generator for .NET API documentation.
https://dotnet.github.io/docfx/
MIT License
3.94k stars 839 forks source link

[Feature Request] Enable SystemMetadataGenerator to never use a relative path but always an absolute path #10028

Open rmannibucau opened 1 week ago

rmannibucau commented 1 week ago

Is your feature request related to a problem? Please describe. I want any asset or page to use absolute links from the root of the website (to be configured in this mode). Goal is to be able to configure the base of the website on github pages (or any similar system). Instead of having for subfolders something like ../../public/docfx.min.js I'd like to get /myproject/public/docfx.min.js and so on.

This issue pops obviously for pages not stored in the URL path folder. A common example is 404.html - created from 404.md - which will be served when hitting /myproject/foo/bar/whatever/not/existing.

Describe the solution you'd like Ideally I'd like to put in header metadata on 404.md a flag to use absolute path for this page - but if global for all pages I'm happy too.

Describe alternatives you've considered For now I added a js script in the page to redirect on the actual 404 page url when the subfolder is not matching the hosting but this changes the url and is not satisfying.

filzrev commented 1 week ago

This issue pops obviously for pages not stored in the URL path folder. A common example is 404.html

I've tested Rewriting 404.html file on deploying GitHub Pages approach. And it seems to works as expected.

PowerShell steps to rewrite HTML https://github.com/filzrev/docfx_sample_404_notfound/blob/main/.github/workflows/build_docs.yml#L78C1-L93C47

Sample 404.md file that simulate default 404: NotFound page https://raw.githubusercontent.com/filzrev/docfx_sample_404_notfound/main/docs/404.md

Sample render result page https://filzrev.github.io/docfx_sample_404_notfound/foo/bar/whatever/not/existing

Is there other scenario that needs Root relative URL? If there is such a requirements, I thought it need to add following features.

  1. Add <base href="/{baseURL}/" /> tag inside <head> tag.
  2. Rewrite URLs to Root relative URL by custom PostProcessor.
rmannibucau commented 1 week ago

@filzrev <base> is a workaround indeed but it has side effects (in particular when embedding js in pages) so it is always better to avoid it. Indeed a custom implementation will make it work, this is why this issue is about ensuring default generation is compatible with common frontend middleware error page mapping without redirection hacks or breaking the site js.

filzrev commented 1 week ago

<base> is a workaround indeed but it has side effects (in particular when embedding js in pages) so it is always better to avoid it.

I agree with that opinion. I've using <base> tag for 404 page thought. It should be avoided for general purpose usage.

this is why this issue is about ensuring default generation is compatible with common frontend middleware error page mapping without redirection hacks or breaking the site js.

This issue title states SystemMetadataGenerator should use absolute path. Though, Is there any problems when using custom HtmlPostProcessor approach? I though it seems can be implemented as custom PostProcessor that rewrite related urls.

rmannibucau commented 1 week ago

@filzrev no issue to impl it differently. My reasoning was : generate it right, but a "fix it after works" too even if I will not hide I dont fully get why it is better it would do the job so no issue for me. Only key point: no dev needed for end user.

filzrev commented 6 days ago

I've tested Custom HTML PostProcessor approach at this branch

UrlRewritePostProcessor rewrite HTML relative URLs to specified Absolute URL or Site Relative URL.

The problems that can be raised are.

It might be better approach, Simply rewrite HTMLs on site deployment timing.

rmannibucau commented 6 days ago

Eactly, this is why I thought about ensuring the generator is able to generate an error-free website instead of relying on relative links which can be broken by globbing rewrite rules.

What I don't get quite well right now is why you don't want to generate the website with absolute links if url is set in the docfx.json? Any technical blocker from your point of view?