gruntjs / grunt-docs

Grunt documentation. https://github.com/gruntjs/gruntjs.com
https://gruntjs.com/
80 stars 128 forks source link

Add doc for the mini-badge. #11

Closed kahlil closed 10 years ago

kahlil commented 11 years ago

Hey @vladikoff, @isaacdurazo & @cowboy.

Here is my first stab at the doc for the mini-badge just as a screenshot:

2013-11-02 at 20 24

Here just the copy:


grunt-mini-badge

Do you use Grunt in your projects and want to proudly display that in your project README on Github?

We too! That's why we had our very own Isaac Durazo make a nice mini-badge for you that you can place up top in your README. If you are using the Travis mini-badges ours fits nicely next to it.

Here is how you place it in your README:

First, Download the badge here and place it in the root of your project.

After you published that project to Github click through to the raw version of the mini-badge image file.

2013-11-02 at 20 10

And copy the URL.

Then insert the following code snippet into your README file just underneath the Headline and replace the copied link with the link in the snippet or replace the parts in caps with the correct names:

![Grunt Mini-Badge](https://raw.github.com/USERNAME-OR-ORG-NAME/REPO-NAME/master/grunt-mini-badge.png)

Let us know if you are using it on Twitter or on IRC in the #grunt channel.


Any feedback or thoughts?

kahlil commented 11 years ago

Made some edits. See the issue.

vladikoff commented 11 years ago

Hey, looks great! Some feedback (my opinion):

  1. "We too!" sounds strange to me
  2. The ALT text in the markdown should read "Built with Grunt" (or something like that)
  3. I'm not sure I understand the RAW workflow. See http://about.travis-ci.org/docs/user/status-images/ page for an example.
  4. We need to make sure that the badge image is not hotlinked from gruntjs.com
  5. "place it in the root of your project." this is asking too much I think, I would not want random PNG files that have nothing to do with the project in the directory. This might not be the best practice.

"4" and "5" are hard to solve, because we don't really want to host that image file, but from "5", committing the image file is not the way to go, none of the other badges do that. How else can this be approached?

kahlil commented 11 years ago

Yep i also thought 4 and 5 should be adressed. Maybe we can get support from a CDN company like @cdnify or so to host our image?

Sent from my iPhone

On 02.11.2013, at 21:51, Vlad Filippov notifications@github.com wrote:

Hey, looks great! Some feedback (my opinion):

  1. "We too!" sounds strange to me
  2. The ALT text in the markdown should read "Built with Grunt" (or something like that)
  3. I'm not sure I understand the RAW workflow. See http://about.travis-ci.org/docs/user/status-images/ page for an example.
  4. We need to make sure that the badge image is not hotlinked from gruntjs.com
  5. "place it in the root of your project." this is asking too much I think, I would not want random PNG files that have nothing to do with the project in the directory. This might not be the best practice.

"4" and "5" are hard to solve, because we don't really want to host that image file, but from "5", committing the image file is not the way to go, none of the other badges do that. How else can this be approached?

— Reply to this email directly or view it on GitHub.

kahlil commented 11 years ago

Also thanks for the feedback @vladikoff. Will remove the We too! remark and once we have a solution for the image hosting I will change the instructions.

kahlil commented 11 years ago

Looks like cdnify would like to help with this. https://twitter.com/cdnify/status/396971426819080193

I wrote him an email. Will report back once I hear back from him.

vladikoff commented 11 years ago

@kahlil make sure to get final approval regarding using cdnify from @cowboy

kahlil commented 11 years ago

@vladikoff of course I will just get in the proposal. @cowboy decides.

kahlil commented 11 years ago

@cowboy @vladikoff @isaacdurazo

Hey guys so cdnify is offering to host the badge (and also 2 other version of the badge if we want) with their cdn.

Basically it would go like this:

Seems like it would be the same as setting up a standard resource. We would mirror the site and target that one image (or three if there are more badges). Then it would just be a matter of you guys updating the subdomains at your end.

In exchange we would mention them and link to cdnify on the instructions page.

This would make the instructions for inserting the mini-badge much smaller. We could offer a snippet with the link to the badge and everybody can use that one snippet since the CDN delivers it to the browser, also performance should be optimal since:

your assets are automatically delivered to your users from the server that is nearest to them. With automatic access to over 80+ locations, CDNify has more POP's than any other CDN, so you never need to worry about adding more to meet demand.

So the offer stands. If you guys approve we can get it set up immediately. Let me know and I will set it in motion if you want.

If you have questions you can ask Mike directly via "mike at igniso dot com".

cowboy commented 11 years ago

Let me see if we already use an CDN solution at bocoup, and I'll let you know!

kahlil commented 11 years ago

Awesome. :cloud:

kahlil commented 11 years ago

@cowboy any news?

kahlil commented 11 years ago

Here the updated copy for the mini-badge page:

gmb

The link to the badge will have to be changed to whatever it needs to be.

kahlil commented 11 years ago

@vladikoff is there a way to turn off syntax-highlighting for the markdown snippet?

mikecunsolo commented 11 years ago

Hi, Mike here from CDNify. We love Grunt and would be more than happy to help out in any way we can.

cowboy commented 11 years ago

@kahlil @mikecdnify let's go with CDNify, it sounds great!

I want to make sure that what we do can be expanded to a few other hosted images in the future. I'm not sure what they might be yet, of course!

What will the image URL for the "Built with Grunt" mini badge look like?

cowboy commented 11 years ago

@kahlil a few comments:

mikecunsolo commented 11 years ago

Great news, looking forward to working with you guys.

kahlil commented 11 years ago

@cowboy:

I want to make sure that what we do can be expanded to a few other hosted images in the future. I'm not sure what they might be yet, of course!

@mikecdnify already said that we can host more than one image with them. I guess we'll just take it one at a time, yes?

What will the image URL for the "Built with Grunt" mini badge look like?

@mikecdnify can you enlighten us here? Do we just link to our server and set up a redirect for that link to the CDN or do we use a CDN-Link in the snippet? What is the best practice here?

  • Perhaps offer both a markdown version and an HTML version of the link code.

OK, will change accordingly.

  • Should the title be "Built With Grunt" or "Built with Grunt"? I like the lowercase "w" personally.

Lowercase "w" is better. I will use that.

  • Can the page show an example of how the mini-badge lines up with other mini-badges (like Travis, etc)?

Yep, good idea. Will integrate.

  • I think the "Mini Badge" instructions should be a sub-section of a larger page called "Logos and Badges" or something similar. That way we can add other badges or logos later on. What do you think, @isaacdurazo?

Let me know @isaacdurazo :smiley:

isaacdurazo commented 11 years ago

I've been thinking and maybe within the brand guide we should have that "Logos and Badges" section, so like a sub-sub-section.

What do you guys think about that?

mikecunsolo commented 11 years ago

We would need to set up a resource with the origin being the domain where the image is stored. We'd then add the cname and change the urls in the code, as normal. The url for the image would then be, for example, cdn.grunt.com/images/built_with_grunt.jpg or whatever. This assumes that the resource set up is cdn.grunt.com.

cowboy commented 11 years ago

@mikecdnify, so if we make the image available at http://gruntjs.com/cdn/built-with-grunt.jpg can the CDN grab that and map it to http://cdn.gruntjs.com/built-with-grunt.jpg?

If so, we can then store anything we need to on the CDN under that path on gruntjs.com. Right?

Either way, I can set cdn.gruntjs.com to point to whatever you'd like, just let me know how this all needs to work!

cowboy commented 11 years ago

@isaacdurazo that could work, but only if we call the "Brand Guide" page something that works for both users looking for Grunt logo & brand usage for "legal" reasons (book / video publishing, etc) as well as Grunt logo & brand usage for "community" reasons (badges, etc).

There might be two totally separate audiences for each of those things... and if there is, maybe we should have two separate pages that each focus on their separate things ("Brand Usage Guidelines" vs "Badges"), with perhaps links between the two if people get to one page but are looking for the other thing.

Thoughts?

kahlil commented 11 years ago

@cowboy @isaacdurazo

I definitely think that the badges should live on their own page. I am sure it will be in high demand just like the stickers because people love to display that they love and work with Grunt.

The Logo and branding page is important to but just as Ben said, it has a much different use case and context.

mikecunsolo commented 11 years ago

Yeah, I'll set up an account and drop you an email with the steps you need to take at your end.

On 8 Nov 2013, at 20:44, Ben Alman notifications@github.com wrote:

@mikecdnify, so if we make the image available at http://gruntjs.com/cdn/built-with-grunt.jpg can the CDN grab that and map it to http://cdn.gruntjs.com/built-with-grunt.jpg?

If so, we can then store anything we need to on the CDN under that path on gruntjs.com. Right?

Either way, I can set cdn.gruntjs.com to point to whatever you'd like, just let me know how this all needs to work!

— Reply to this email directly or view it on GitHub.

cowboy commented 11 years ago

@vladikoff can you make the badge image available at http://gruntjs.com/cdn/built-with-grunt.jpg (or png)? Then I can set up the CDN to use that resource and I'll make it available at the correct URL.

kahlil commented 11 years ago

w00t! :boar:

@vladikoff here the link to the badge as a png that I cut out from @isaacdurazo's design: https://f.cloud.github.com/assets/104712/1459727/f606673a-43f2-11e3-8f3c-676d86160519.png

karl-sjogren commented 11 years ago

I wouldn't go with a cutout since you loose transparency on the edges that way. It will work fine on white backgrounds but on other colors you will get noticable artifacts: http://imgur.com/BPqoMZW

Is there any chance that @isaacdurazo might supply a badge with correct transparency on the corners/edges so it might be used in other places as well (such as project websites and/or documentation)?

kahlil commented 11 years ago

@karl-sjogren that's true!

:+1:

isaacdurazo commented 11 years ago

Hey guys here is a PNG for the badge :+1:

grunt-badge

kahlil commented 11 years ago

@isaacdurazo thanks!

mikecunsolo commented 11 years ago

Looks great!

vladikoff commented 11 years ago

@cowboy http://gruntjs.com/cdn/built-with-grunt.png

cowboy commented 11 years ago

@mikecdnify I see that cdn.gruntjs.com is mirroring gruntjs.com. Is there any way to prevent it from serving HTML files or to limit it to a subdirectory or wildcard pattern of assets on gruntjs.com? The reason is that people shouldn't be able to browse http://cdn.gruntjs.com/ and see the entire site, which they currently can. This is potentially very bad for SEO, and might be confusing when it comes to determining which URIs are canonical.

FWIW, I see that the example at http://cdnify.com/learn/set-up-your-first-cdn/ does this with http://cdn.birdsong.fm/ which is probably not great.

Let me know what we can do to make this work, thanks!

mikecunsolo commented 11 years ago

@cowboy The cdn is caching static content only so dynamic content, the stuff that is likely to be indexed by search engines, is always served from the origin server. It is true, however, that if someone was to hit cdn.gruntjs.com they would be able to access any of your assets. The absolute path of the badge url means that it is the only asset that resolves to the cdn. All the other links are relative and will resolve to the origin server.

cowboy commented 11 years ago

My concern is that if anyone links to http://cdn.gruntjs.com/ or any subpage, site indexing will be compromised. Can we disable this?

mikecunsolo commented 11 years ago

Unfortunately you can't blacklist or whitelist certain assets but we are working on adding this functionality.

cowboy commented 11 years ago

@mikecdnify do you have an ETA? I'd really like to get this badge launched.

@vladikoff In the short-term, could we get another server setup that simply hosts that file at /cdn/built-with-grunt.png? Then we can tell the CDN to just mirror that server for now. Right?

vladikoff commented 11 years ago

@cowboy http://grunt-badge.herokuapp.com/built-with-grunt.png is this good?

cowboy commented 11 years ago

@vladikoff can you make it http://grunt-badge.herokuapp.com/cdn/bwg.png ?

vladikoff commented 11 years ago

@cowboy here you go http://grunt-badge.herokuapp.com/cdn/bwg.png

cowboy commented 11 years ago

Ok, the image is live.

Question: do we need https, or will http work?

http://cdn.gruntjs.com/cdn/bwg.png

Built with Grunt

HTML

<a href="http://gruntjs.com/"><img src="http://cdn.gruntjs.com/cdn/bwg.png" alt="Built with Grunt"></a>

Markdown

[![Built with Grunt](http://cdn.gruntjs.com/cdn/bwg.png)](http://gruntjs.com/)
vladikoff commented 11 years ago

@cowboy I vote for an HTTPS option, seems like all other badges work over HTTPS

cowboy commented 11 years ago

If we decide to go the SSL route through CDNify, the URL will be like https://gruntjs.r.worldssl.net/cdn/bwg.png which means that if we ever want to go with a different CDN provider in the future, we'll end up with a different domain, and a BILLION broken images out there.

So, I'm not sure that's a good idea. Are there other options for SSL? /cc @mikecdnify

vladikoff commented 11 years ago

@cowboy that URL is scary

kahlil commented 11 years ago

@cowboy can't we just do a redirect on the server that sends all requests to http://grunt-badge.herokuapp.com/cdn/bwg.png to go to the CDN location of the image? Making it irrelevant what the CDN-URL is effectively?

In other news: I don't know anything about this stuff...

kahlil commented 11 years ago

I changed the doc for the mini badge and pushed the latest changes to the mini-badge branch. See the current file here: https://github.com/gruntjs/grunt-docs/blob/mini-badge/Badges.md

What has changed & a few issues:

2013-11-22 at 07 43

nickdtodd commented 11 years ago

@cowboy Hi. My name is Nick and I work at CDNify. The redirect solution you mentioned would work but it is a hack. If that is how you'd like to proceed then let me know and I'll set up the new resource with the origin being the new server hosting the badge file. You'd then do the redirect at your end. Thanks.

cowboy commented 11 years ago

I don't think I like the idea of redirecting with an SSL asset. Can we do this another way?

cowboy commented 11 years ago

@kahlil @isaacdurazo both buttons are the same height but the Grunt button looks taller because it's not antialiased around the edges like the Travis one. Should we antialias ours?

cowboy commented 11 years ago

@kahlil if you put an anchor around the Travis image, it'll create a space between them.