search

dotnet / AspNetCore.Docs

Documentation for ASP.NET Core
https://docs.microsoft.com/aspnet/core
Creative Commons Attribution 4.0 International
12.64k stars 25.28k forks source link

Split MapStaticAssets and UseStaticFiles into 2 docs #34080

Open Rick-Anderson opened 1 week ago

Rick-Anderson commented 1 week ago

Description

Per #34002, split them via:

  1. remove all the UseStaticFiles from this doc. set uid: fundamentals/mapStaticFiles Probably rename the file MapStaticAssets.md ( unless it messes up the PR files diff)
  2. Copy the V8 version ~/fundamentals/static-files.md into UseStaticFiles.md

The above will make for the most productive changes to review. After PR merges, hook up the TOC for mapStaticFiles

Review UseStaticFiles history to see what UseStaticFiles changes were made from .NET 8 to .NET 9. I think only a few bug fixes.

@tdykstra @guardrex please review.

Page URL

https://learn.microsoft.com/en-us/aspnet/core/fundamentals/static-files?view=aspnetcore-9.0

Content source URL

https://github.com/dotnet/AspNetCore.Docs/blob/main/aspnetcore/fundamentals/static-files.md

Document ID

3fec6e08-fc99-7a5c-796f-3f2347cad891

Article author

@Rick-Anderson

Related Issues

Associated WorkItem - 343087

guardrex commented 1 week ago

The UID/file naming doesn't match the usual convention for lowercase, possibly with dashes. Should it be more like ...

tdykstra commented 6 days ago

The UID/file naming doesn't match the usual convention for lowercase, possibly with dashes. Should it be more like ...

  • MapStaticFiles

    • UID: fundamentals/mapstaticfiles or fundamentals/map-static-files
    • Filename: mapstaticfiles.md or map-static-files.md

  • UseStaticFiles

    • UID: fundamentals/usestaticfiles or fundamentals/use-static-files
    • Filename: usestaticfiles.md or use-static-files.md

I vote for map-static-files and use-static-files UID and file name. Whatever we do, I don't think we want upper case letters in UID or file name.

tdykstra commented 6 days ago

Comments on the procedural text here for splitting the article into two:

guardrex commented 6 days ago

move much of the Blazor article text to the base article

divide up the remaining Blazor-specific content into Map and Use sections and work them into Blazor sections in the new Map and Use articles.

Blazor article text that applies to all ASP.NET Core static file scenarios should move. Much of what's in the Blazor article is specific to Blazor, and it shouldn't be moved into the main doc set articles. I floated the idea that Blazor fundamentals content (all of it, not just for static files) should be moved entirely to the main doc set Fundamentals node (somehow), but no 🎲🎲 on that suggestion. I suppose it would be efficient if I made a set of HTML comments in that text for what can be moved and what has to stay. I've opened #34098, and I'll try to get that done today but certainly by EOW at the latest.

Rick-Anderson commented 5 days ago

The UID/file naming doesn't match the usual convention for lowercase, possibly with dashes. Should it be more like ...

  • MapStaticFiles

    • UID: fundamentals/mapstaticfiles or fundamentals/map-static-files
    • Filename: mapstaticfiles.md or map-static-files.md

  • UseStaticFiles

    • UID: fundamentals/usestaticfiles or fundamentals/use-static-files
    • Filename: usestaticfiles.md or use-static-files.md

I vote for map-static-files and use-static-files UID and file name. Whatever we do, I don't think we want upper case letters in UID or file name.

For sure I'm not going to change the original UID which is a PK, no reason. There's no advantage to following a semi-convention on the implementation of the PK. I'll follow the convention for mapstaticfiles, UID: fundamentals/mapstaticfiles

Comments on the procedural text here for splitting the article into two:

  • It doesn't seem to take into account what Dan said about wanting to move much of the Blazor article text to the base article.

@guardrex will handle the Blazor changes

  • A lot of the text is devoted to comparing Map... vs. Use..., which will make splitting the text up into two well-organized articles more complicated than these instructions suggest.

No, it makes it easier, all that goes to the usestaticfiles file with a pointer to that in the mapstaticfiles files. mapstaticfiles handles the majority use case. If you need something that can only be done with usestaticfiles, that's in another doc.

  • It might make sense to divide up the remaining Blazor-specific content into Map and Use sections and work them into Blazor sections in the new Map and Use articles.

I'll let @guardrex refactor the Blazor-specific content

guardrex commented 5 days ago

I'll cut out 🔪 the offending bits from the Blazor article, but I'll wait until the split takes place here and new Map Static Files article goes into place. That way, I can cross-link to it.

It's also probably best for me to wait so that you can see what I have there. I understand you're going to two articles, while the single Blazor article has them both, but you can at least lift any of the text that you like before I get to cutting 🔪🔪 🔪 🔪 on the article.