Aspnetcore.docs: Remove wwwroot assets (CSS/JavaScript/images/lib) from samples that don't need them

Created on 24 Oct 2018 · 16Comments · Source: dotnet/AspNetCore.Docs

Only the following on boarding tutorial samples will contain wwwroot assets:

Create a Web API
Create a Razor Pages web app
Create a web app with ASP.NET Core MVC
Tutorial: Get started with ASP.NET Core SignalR
EF/RP intro

The remaining samples will contain README.ME explaining how to acquire the assets.

@danroth27 will be mentioned on all PRs

Source

Rick-Anderson

Most helpful comment

@guardrex Having some simple styles that we can use in samples without bringing in all of bootstrap and jquery sounds like a reasonable idea.

danroth27 on 24 Oct 2018

👍2 ❤1

All 16 comments

@danroth27 mentioned today it would be really bad if someone had to get the wwwroot contents for a sample. I don't think it's that problematic compared to rewriting the tutorials so they don't depend on wwwroot. You could use the following instructions.

Generate wwwroot assets: dotnet new webapp -o ContosoUniversity
copy wwwroot folder to sample.

@danroth27 please respond.

Rick-Anderson on 24 Oct 2018

The remaining samples will contain README.ME explaining how to acquire the assets.

I would recommend something different. For many samples you really don't need much for the UI. For example, if you're demonstrating config or options or DI you can just use some raw HTML. It doesn't have to be pixel pretty. My suggestion is to dramatically simplify samples to focus on the feature they are trying to demonstrate.

danroth27 on 24 Oct 2018

@danroth27 OK, that will be the new policy. When topics/samples are updated we'll remove the dependency on wwwroot assets. That means we won't make non-trivial progress on removing wwwroot assests in the next 6 months.

Rick-Anderson on 24 Oct 2018

Before ... 🌹

capture

After ... 🙈

capture1

... and note that many of the samples that I created have text blocks to explain what the sample is doing (how it works) on the landing page. I call this approach the Self-documenting Sample:tm:, and I think it's great for a sample-on-the-go scenario or even just when it's a pain point to be flipping back-and-forth between sample and topic. Without styles, these paragraphs span the window width, so they're hard to read and less effective.

Recommendation

A <style> tag paste-in that we can drop into these pages that will make them look halfway decent.

Permission to float you a tag concept for this? :pray:

cc: @scottaddie @tdykstra

guardrex on 24 Oct 2018

I don't follow what you mean by a style tag paste-in.

tdykstra on 24 Oct 2018

My suggestion is to dramatically simplify samples to focus on the feature they are trying to demonstrate.

This should be a project by project process; git-ignoring the entire wwwroot folder seems like it might create more problems than it will solve.

tdykstra on 24 Oct 2018

guardrex on 24 Oct 2018

If you just mean a snippet of HTML markup that we can copy and paste, I'd say go ahead and if it's something we'd use in many samples we could store it in https://github.com/aspnet/Docs/blob/master/CONTRIBUTING.md

tdykstra on 24 Oct 2018

👍1

@guardrex Having some simple styles that we can use in samples without bringing in all of bootstrap and jquery sounds like a reasonable idea.

danroth27 on 24 Oct 2018

👍2 ❤1

kk ... here's an I-dear.

The following styles would have us perform the following for any dotnet new template sample ...

Kill the navbar (if the sample requires links, put them at the top of the layout).
Kill the footer.
Drop rows and columns from pages. (Leave the panels alone.)
Add the <style> tag to the <head> of the _Layout.cshtml file.

The doc author might need to make a few minor adjustments for any MIA Bootstrap styles that they call for.

Example for Distributed Caching Sample

Hey! That looks just like Bootstrap!

The Tag

Could prob use a little more work, but just spitball'in here.

\

guardrex on 24 Oct 2018

For what it's worth, LGTM :smile:

danroth27 on 24 Oct 2018

I'll test each time to make sure this works. We might (or _probably_) need to tweak it. It looks soooooooo much better than raw HTML tho. 😀

guardrex on 24 Oct 2018

and it's soooooooo much smaller! :tada:

danroth27 on 24 Oct 2018

👍1

Note to self (i.e. You've heard of Hello World! ... this is more like World Ignore Me!):

<style>body{margin:0;padding-bottom:20px;font-family:"Helvetica Neue", Helvetica, Arial, sans-serif;font-size:18px;color:#333}h1{font-size:36px;margin-top:20px;margin-bottom:15px;font-weight:500}h2{font-weight:500}:before,*:after{box-sizing:border-box;}p{margin:0 0 10px;}.container{padding-right:15px;padding-left:15px;margin-right:auto;margin-left:auto;width:800px;}.container:before,.container:after{display:table;content:" ";}.container:after{clear:both;}.body-content{padding-left:15px;padding-right:15px;}</style>

guardrex on 7 Jan 2019

Let's pick back up our chat over here.

Just use .gitignore. That's our standard. The debug assets are trivial.
If you use .gitignore, the only problem is non-development.

I don't grok that. On the dev's machine ...

In dev environment, the app uses un-minifed static resources, which aren't present unless .gitignore forces them into the repo.
In prod environment, the app uses CDN resources or falls back to minified static resources.

So, if .gitignore is used to force un-minified static assets into the app, ok ... I'm with u there, but that defeats the goal of slimming down the repo. There's another way ... better way imo ...

What I've been doing is totally removing static assets for samples that don't absolutely need them (i.e., non-auth samples almost always don't need them) and dropping in a line of styles that make the app look great. It provides the following advantages:

Super-slim app ... slim repo eventually as more-and-more samps get this treatment.
App looks great no matter if the dev is online or offline or running it in dev or prod environments.

That's what I thought we worked out here earlier.

WRT forcing in with .gitignore, ok ... I may have just misunderstood what was being said. I'm not doing that tho unless I have to (e.g., the auth samples, which really need their full static assets to look good everywhere).

guardrex on 12 May 2019

Solved offline.
The policy is to depend on .gitignore to prevent production assets into the rep.

If the sample app doesn't need static assets and other files, feel free to delete them.

Rick-Anderson on 12 May 2019

👍1

Was this page helpful?

0 / 5 - 0 ratings