InstaCSS: the CSS docs you always wish you had | Hacker News Reader

InstaCSS: the CSS docs you always wish you had

instacss.com

449 pointsidan91 comments

Hey there, creator of instacss here. Thanks for all the feedback! I posted this as a Show HN last week, but it's nice to see that someone has re-discovered it: http://news.ycombinator.com/item?id=3222253.

Since then I've added a few features, one of which being the ability to have permalinks so that you could use it as a google chrome search. This is why I push to the url bar as you type. I'm really open to feedback on how to do this without screwing with people's back buttons, since I agree that's pretty bad.

Though the MDN docs are down right now check out the replaceState method. It allows to write over the url (on the same domain) without creating a new history object. This is a textbook example of where using replaceState would make sense.

An idea would be to separate the history push from the loading of the resources, and only push history after an action that denotes the user has found the result they were looking for (blur of input, pressing enter, etc) to avoid a search history filled with every keystroke of a query.

A different take would be to never automatically push the results to the url bar, but still parse the address bar for queries, and provide a permalink for each result with the hash in it.

Just add a short delay between the keypress & the search/url push, and add a check to see if the query is the same. If after a ~second or so the query is the same, do the search and update the URL.

Yes please! This was the first thing I noticed, maybe my netbook is too slow but I do a lot of coding on the little thing.

The way I solved this in a similar auto-complete app was using a setTimeOut to prevent updating or requesting data unless no key had been pressed in the last 0.2 seconds or so:

    var updateId = 0;
    function searchKeypress(e) {
      if ((e || window.event).keyCode == 13) {
        updateCookie(radioStations.selected);
        document.location = radioStations.selected.links[0].url;
      }
      clearTimeout(updateId);
      updateId = setTimeout(searchUpdate, 200);
    }

Disclaimer: this piece of code is about 4 years old and as you can see it doesn't even use jQuery, but I trust it demonstrates the principle well enough.

I'd use underscore.js's _.debounce method, simples!

Would be nice if you share some of the used backend technology

Here you go :) https://github.com/rgarcia/instacss

Data is scraped mostly from MDN using node-scraper and then thrown into mongodb for storage.

Backend is also node and just provides a json endpoint for pulling the entire db client-side (along with serving up index.html and all the client-side js).

Frontend is all backbonejs, which makes writing the search function pretty insanely simple: https://github.com/rgarcia/instacss/blob/master/static/js/vi...

Both backend and frontend code is organized using requirejs, which I am pretty much in love with.

Love it. One thought - have standardized CSS listed first. I type in "background" and get "-webkit-background-composite" as a first result. I'd probably want to see just "background" come up, followed by declarations less popular. Regardless of this minor issue, I'll be using this regularly. Thanks for this!

The query is a regex, so background$ gets you what you want.

Hey, pretty cool but you should have a delay between when the user types something and when the url gets updated and a query gets made. i.e. some sort of definition of "user stopped typing". This improves usability by a ton.

Second is, maybe you should have a sidebar on the right that shows you clickable / keyboard navigatable titles of all the search results so I don't have to scroll down browsing.

Agreed. The back button is made almost useless since it is stuffed with each intermediate typed character.

This is a separate question. The URL can be updated without creating browser history.

Nice, but a few UX nitpicks:

* Default to sort by relevence: Put the more relevant matching properties at the top. For example, I type "backg" instead the highest result being the obscure "-webkit-background-composite" ... actually most relevant result "background" which should be the first result instead of the third.

* Default results list to condensed format: Instead of showing the full verbose docs for every matching result instead show a sparse summary of each result with a option to expand it. If there's only one matching result then show the complete doc for it

* Nice example palette for standard colors. How about an example palette for the standard font families?

Agree with all of these points, especially the condensed-at-first display.

I would also like it if the search box was in the fixed header, so I don't have to scroll back to the top to re-search.

Otherwise nice tool!

Yes, needs better separator elements to distinguish between the hits. A condensed default view would help with this though.

Agree, however if there is a single result (such as a background$ query), then show in expanded format.

My immediate thought when I saw this was:

Takes regular expressions as user input. Probably DOS'able.

After looking at it for a few seconds, I realised that it's doing the regex matching on the client side, so it's ok.

If you ever accept arbitrary regular expressions as user input, be very careful: https://www.owasp.org/index.php/Regular_expression_Denial_of...

It filled my back button up with mess :(

This is terrible and needs fixing immediately.

yes, history clutter no good at all :(

This site would be even better if they included compatibility. Maybe there could be an API call to http://caniuse.com/ ?

Rad. Lose this "gimmeh teh CSS docs." to get taken seriously.

Agreed, "gimmeh teh" is lolcats idiocy instead of a professional tool. I'm embarrassed to have it up on my monitor in a work setting.

The first thing I searched for (background-color) wasn't found. Uhh...

That's the first thing I searched for too, and also with no success...

Working on fixing this...looks like the scraper croaked on that MDN page. Thanks for finding this.

Same here. Also got nothing for 'inline' or 'block'.

I searched for it too. Weird.

Yeah, I am stuck with that too.

Nice. To avoid the annoying type-to-search feature, just search for "a" and get the whole document at once:

http://instacss.com/#a

Edit: ugh, that doesn't actually work. It only gives you p-z. Hey instacss! Please provide us with a link to the actual document. Preferably in plain HTML so we can download it. Alternately, anybody care to scrape this thing and post it in full?

Here ya go https://developer.mozilla.org/en/CSS

The query is a regex, so it's pretty easy: http://instacss.com/#.

http://instacss.com/#^

guys, just type "." - regex 101

I second this. An option to see the whole document would be /really/ nice.

This design breaks the back button pretty badly.

The creator should really put the search field in the persistent top-bar.

I think your DNS for www.instacss.com is broken:

;; ANSWER SECTION: www.instacss.com. 300 IN CNAME http://morning-warrior-3377.herokuapp.com/.

CNAME accepts only hostnames or (depends on your RFC-acceptance-level) a FQDN. No URI/URL

Ah, thanks--I've been meaning to fix this. Should be working shortly.

One minor bug: I notice the anchor (and results!) changing as I type and backspace, but if I backspace all the way to an empty it is stuck on the single-letter anchor. Would be nice if it cleared out entirely and took me back to the empty front page.

Any chance of getting it to apply the filter on page load as well? It appears that it's not possible to link to a result set. i.e., if I send someone a link to http://instacss.com/#background in order for results to be shown they must perform a keypress of some sort in the search field.

edit: Apparently if you've searched something before it does display it on page load (after a brief delay)? So it seems this link might not be a good example URL. But hopefully you can just edit the URL and submit it directly to see what I'm talking about.

It would be nice to show something more useful on the front page before the user types anything into the search box. Like an index or a table of contents or so.

I wouldn't say these are the css docks I wish I always had. see I want better presentation. I don't really want to scroll through the actual CSS docs from W3C, I want to get some quick view of what my search query returned (property, {values}, notes). After that I could click on the entry for that property and read it's docs. It's just information overload. Nice work though, but that's my suggestions.

Nice! It's great that it has detailed version support info, like:

  *Support for multiple, comma-separated, background images was added in Gecko 1.9.2.*

but I wish it showed what fraction of web users that represents. Maybe with a little green/red fuel gauge icon.

The OP said he's pulling the data from MDN (Mozilla Dev Network I think?), which means all the comments are only going to be Firefox-related. What I would want is for it to show all browsers and what version the feature is available in (but if he's automating the data pull, this probably isn't going to happen I imagine).

FYI: MDN is a wiki. Feel free to add information about other browsers. It's meant to be docs for the web, and that includes more than just Firefox.

MDN has started improving that, and showing compatibility information for more than just Mozilla browsers. They already include full compatibility tables for some of the more frequently used features.

I searched for "layout" and found nothing. These are not docs I always wish I had.

I typed "^color$" and it wreaked havoc on my page history. Usually, I open the story in the same window then hit the back button to see the comments. This time it took me handful clicks before I get to my previous page.

I can't take this seriously when it beings like this: "gimmeh teh CSS docs."

In addition to the complaints about this flooding history, I expect the "background" style to appear first once I've typed "bac", and even with "background" there's some webkit thing first.

The link is broken for me.

Jup, for me too. And not even Google Cache shows something.

I've found MDN to be the best resource: https://developer.mozilla.org/en/CSS

This app is using the data from MDN. It's similar to http://w3viewer.com/ which makes it easier to browse W3C specs.

Hell yeah, thank you. I've been so tired of googling up "css background" and click 2-3 website and hope they'd show what I want.

Really, nice resource. I would love some quick links after a search to save on scrolling.

You were faster ;) Yes, that was also my first thought :)

Some linking love to MDN and highlighting the wiki property would be nice.

some things aren't meant for automatic submission as you type. this is a good example. it's annoying.

also - the automatic URL hashing of the query breaks the back button to a ridiculous degree.

cool content, bad design.

It would be nice if it sorted by relevance; i.e. a search for background would give you the definition of the background property first instead of the -webkit-background-composite property which is almost certainly less relevant (worse match, less used).

searching for cursor yielded some nice content. A few proprietary things I didn't know about. Thanks!

how is it better than google -> check the first result?

It's faster and more consistent--I don't have to worry about which site I'm getting information from each time.

faster? I think it's less practical since it needs you to add a new bookmark (and I have way too much of those)

What, no azimuth?!

http://news.ycombinator.com/item?id=3222253

Oh look, it's another site that loads nothing with JavaScript off. What is wrong with you? Progressively enhance, or gracefully degrade, or display something other than a completely blank page to non-JavaScript visitors. I harbor many doubts re: your competence in the realm of usability.

The percentage of users with Javascript disabled[1] is smaller than the percentage of users using Opera[2].

So there is nothing wrong with choosing to not support 2 out of every 100 users; that's simply a time/cost assessment. What's wrong with you?

[1] http://developer.yahoo.com/blogs/ydn/posts/2010/10/how-many-...

[2] http://www.w3schools.com/browsers/browsers_stats.asp

Which is all well and good unless users don't have a choice. http://en.wikipedia.org/wiki/Comparison_of_screen_readers

Except, that's a poor argument: http://webaim.org/projects/screenreadersurvey3/#javascript

Except that most sites don't care about providing decent clues (correct mark-up, ARIA attributes, etc) for javascript interactions, so that's also a poor argument.

How many web developers looking up CSS reference material are using screen readers though?

It's OK to develop for your target audience, right?

I admit I'm atypical here, but I do all my development work in emacs, and it's nice to have reference material that can also be accessed through emacs.

There is something wrong - in many countries you are mandated by law to make your site accessible :)

Of course this doesn't apply here, but I wanted to be dramatic. Should be piece of cake to just show the full content if javascript is off, since it is already loading all of it.

I can't reply to your last comment, so I'm going to to it here:

> The point is that it's trivial to make a site like this usable without JS, with little effort. You just have to start with the right mindset.

How are you supposed to make a instant search usable without JS?

If it doesn't need to be instant, just normal search with a nice GET /search?q=border, one would have to program a server side script to do that search.

Or maybe you'd just want to show the whole reference on the HTML, then the JS would have to use that to do the search and hide/show the appropriate div, or you'd have to load everything twice (once in the HTML body and again via ajax). Even then, what's the point? It's a instant search. If the user can't use the only feature of it, he's better off googling.

Is there other way that I'm missing? I don't see that as "trivial".

If you read the other parts of the thread, or check the source code, you'll see that the whole content is loaded at once. There are no further requests. It's all already there with `display:none`.

    document.getElementsByTagName('html')[0].className += ' js'

    .js #search-results { display:none; }

That's basically all you need.

Screen readers support Javascript-enabled browsers these days.

Accessibility is not just about screen-readers. There are hundreds of mobile browsers, consoles and a myriad of other devices with zero to broken javascript support. And even in screen-readers that do support JS, most interactions are broken unless you use proper mark-up and manage page focus and keyboard shortcuts.

The point is that it's trivial to make a site like this usable without JS, with little effort. You just have to start with the right mindset.

> There are hundreds of mobile browsers, consoles and a myriad of other devices with zero to broken javascript support.

These days, both of the major mobile browsers use WebKit and have great JavaScript support, though they may not support bleeding-edge browser functionality quite yet (for which all non-demo sites definitely need fallbacks). The unofficial mobile browsers have great JavaScript too. Consoles have decent browsers with decent JavaScript, and in any case not all sites need to expect console browsers as a remotely common case.

You have to draw the line somewhere, and not all sites need to support Lynx, Links, or Mosaic. I certainly agree that having decent fallbacks for a site like this doesn't require that much effort, but not all functionality supports graceful degradation.

These days, browsing without JavaScript seems less likely to indicate an older browser, and more likely to indicate a user with JavaScript intentionally disabled using something like NoScript. That user may get righteously offended that a document would dare to run code on their system, but that doesn't necessarily make them right.

All web features tend to follow a three-step lifecycle: too new to use at all except for demos, stable enough to use with fallbacks for older browsers, universal enough to use without fallbacks. Depending on your site and your target audience, basic JavaScript may fall in the second or the third category.

You don't have to draw a line anywhere in cases like this. The technology is there that makes it perfectly possible to have at least basic text display on any client. The "major" mobile browsers with webkit represent only 20-30% of the global market.

Anyway, it's just a couple of extra lines of code, get over it :)

Again, that works just fine in cases like this. Though note that the solutions for this site require either server-side scripting or just completely disabling the search functionality.

However, many sites use more advanced JavaScript features which do not necessarily allow for graceful degradation.

(Also, most other mobile browsers of the type you allude to consist of barely more than WAP; only the simplest of non-interactive websites has any hope of working with them. And many sites simply won't have any of those users in their target audience.)

The creator of this website, rgarcia, specifically said (when he posted it a couple of days ago) that it was a 24-hour project: http://news.ycombinator.com/item?id=3222253

Cut him some slack! I harbor many doubts re: your competence in the realm of friendliness.

That is a relevant piece of information I hadn't known. Thank you.

> What is wrong with you?

There's got a be a more polite way to phrase that.

Also, while I understand the reasons for disabling JavaScript generally, is this really something to get that upset about?

"Doesn't function right without JavaScript" disabled rates a shrug - JS enables lots of cool stuff. "Displays a completely blank page without JavaScript" is - well, in this case, as others have pointed out, one of the tradeoffs made in pursuit of a 24-hour project. However, in a mature site (I'm looking at certain MSDN blogs), it's very disturbing, it's a big warning flag for "lack of attention to detail."

My reactions to broken-without-JS sites spring from security, privacy, usability, and accessibility concerns. "Sites that completely break without JS" is a category that strongly correlates with "sites that have major issues in at least one of those four categories."

Yeah, how the OP dares to shows us a prototype of something that he probably hacked in a couple of hours and doesn't even support the very specific user that has JS disabled by default.

Don't even get a blank page :) Get a "Server not found"

I wish I could downvote this.

sigh

Reply on news.ycombinator.com