CSS in GitHub Readmes | Hacker News Reader

CSS in GitHub Readmes

github.com

544 pointsMH15193 comments

Open articleView on HN

If anyone's interested, I'm particularly proud of my SVG animations in this readme:

https://github.com/boemska/create-sas-app

what did you use to create them?

Based on the SVG markup, termtosvg [1].

1: https://github.com/nbedos/termtosvg

ah i could have used this. my readme is a simulation of a github profile ;)

https://github.com/conceptualspace

Freezes mobile GH app on Android.

Cool idea, although with the new Dark mode on Github enabled it was very easy to see what is going on :)

This pleases me more than it should! Cool stuff! :o)

Awfully laggy on slow machines.

That's the termtosvg animation ruining it for all the others. I'm actually going to replace it with a gif. The UI anims are really smooth.

If you're interested in adding SVGs that look like truthful screenshots, I wrote a Chrome/Firefox extension that can take screenshots of webpages in SVG: https://github.com/felixfbecker/svg-screenshots

It can't screen record an animation though, but it could be a baseline for hand-animating the elements. Accepting PRs for screen recording functionality :D

Whoa, if this does what I hope it does I'll be ecstatic! Thank you!

(Here's the Chrome extension link for anyone who's interested: https://chrome.google.com/webstore/detail/svg-screenshot/nfa...)

Similar: emacs can take SVG screenshots of itself:

https://gist.githubusercontent.com/alphapapa/65b0b9d4b3f5534...

That's insane ^^

Seems to depend on Cairo, which is AKAIK only available in X11 environments. Does anybody know how to get this working on OSX?

macOS has APIs to get a vector PDF snapshot from any view/window [1]. If emacs ends up drawing using platform APIs such as CoreText it should be possible to get a screenshot that way.

[1]: https://developer.apple.com/documentation/appkit/nswindow/14...

This is really cool!

Would be super helpful to have some example screenshots linked in the readme though, to help set expectations.

Here are some examples produced by the tests of the underlying library, including HN, GitHub and the Google homepage: https://github.com/felixfbecker/dom-to-svg/suites/1630896833...

The tests take a PNG screenshot of the webpage, then a PNG screenshot of the created SVG and pixelmatch the two. The difference must be below 0.5% for tests to pass.

404's for me

Ah, looks like GitHub actions don't allow public access to artifacts: https://github.community/t/public-read-access-to-actions-art...

In that case - just install the extension and try it out? :)

Added! https://github.com/felixfbecker/svg-screenshots#examples

crashed on the first page I tried it on

Could you file a bug here and include the URL you tried it on? https://github.com/felixfbecker/dom-to-svg/issues/new

This is great, thank you!

I'd love a tool like this for generating animated SVG clips of a web page, it'd help immensely when creating walkthroughs. Video recordings do work, but it's a mess working with different encodings to make it look ok. Not to mention, with SVG such walkthroughs could actually be made interactive...

Looks like we have a similar hobby!

https://github.com/TomasHubelbauer/SVG-Screencast

This is for screen recordings. SVG animations as the OP I play around with, too:

https://github.com/TomasHubelbauer/SVG-3D

Oh that's cool! Did you ever think about recreating the DOM in SVG elements in animating those with CSS, instead of using raster images? It would potentially be possible with MutationObserver, and optionally "copying" any CSS animations in the source DOM. Will likely not be perfect but could still be a good trade-off for a little demo animation of e.g. how to fill out a certain form instead of using a GIF or video.

I'm building this to use to record Electron window recordings - I ultimately want to use this to automatically build animated SVGs showcasing features of VS Code extensions as a part of their CI so the showcased can be coded using VS Code API and the animations in the extension readme just fall out of that. So no DOM in this case. But I am thinking of ways to optimize this. I know this will be used for screen recordings and that gives me some flexibility in what assumptions I can make in the optimization pipeline. At the moment I plan on trying to come up with an algorithm to detect scrolling/jumping regions (like in the demo where the whole line height grows once the first emoji is typed on a given line) and animate their scrolling and cropping using CSS animations instead of image patches. But I think what you describe is definitely something to explore and I might take that up next if I figure a use case for it as it sounds really interesting and fun!

I can't find it on addons.mozilla.org. According to Mozilla[1] I can only use unsigned addons with ESR, Nightly and the Developer Edition of Firefox (which I don't use). I've tried setting xpinstall.signatures.required to false in about:config. It's not helping.

[1] https://support.mozilla.org/en-US/kb/add-on-signing-in-firef...

It's linked from the README: https://addons.mozilla.org/en-US/firefox/addon/svg-screensho... No need to add an unsigned extension :)

Oh! I looked for it, I promise!

Sounds cool but no examples in the README so (lazy) potential users have no idea whether it's worth looking into.

Source: I am lazy.

The only reason I didn't have examples was because I am lazy. Your argument about laziness convinced me, so I added some: https://github.com/felixfbecker/svg-screenshots#examples

Haha, rock on! (Looks great btw)

I recognize your name from some of the VS Code extensions that I use and just want to say thank you!

Hi! Just wanted to say this is an excellent readme, and your Boemska website is equally great. Very impressive – kudos to you and keep up the great work!

Thank you for your kind words. That's made my day :)

Can't SVG's also be used to run code?

Yes, you can: https://stackoverflow.com/questions/5378559/including-javasc...

brb as I write a follow up article.

Yes, that’s what I am thinking. I can imagine hundreds of security researchers writing a proof of concept to report this “feature” as a security problem to GitHub’s bug bounty program.

There’s nothing to report. For all intents and purposes SVG files are treated exactly like images. All interactivity and even the ability to load other resources is disabled.

FYI millions of readmes have had SVG badges for years.

Pretty sure they're just making a joke that a lot of bug bounty programs get tons of bullshit reports from security "researchers" who don't understand what they're doing. They're not actually claiming there's a legitimate issue.

I'm not sure that's true.

For example, what happens when you right-click "View image" on an svg file? Does embedded JS get run in that case?

> For example, what happens when you right-click "View image" on an svg file? Does embedded JS get run in that case?

Servers can use CSP http headers to disable javascript execution completely AFAIK. Obviously older browsers like IE that do not support CSP will be vulnerable, but at that point, IE should be simply banned by Webservers, for the sake of the user.

There are SVGs which will crash most browsers, so SVGs could still be abused for denial-of-service attacks.

For example, you could post one of those SVGs in every issue thread of a GitHub project if you wanted to mess with someone.

Not eligible for a bug bounty though since this issue has been known (but not fixed) for years.

I just tried this in a Github readme, it looks like Github removes the JS.

Would be interesting to try to find a hole in this.

There is no hole. The SVG is loaded as an image. If you find a hole, it would be in the browser’s handling of SVG images, which would be a pretty big hole.

When you load an SVG file as an image, JavaScript is not executed, but SMIL animations and CSS (which includes animations) are.

If you open the SVG file directly, then JavaScript will be executed. But any hosting platforms that hosts your content on their domain should filter out any JavaScript on SVG as it would on HTML.

> But any hosting platforms that hosts your content on their domain should filter out any JavaScript on SVG as it would on HTML.

That's definitely not a thing that happens. Web servers just serve the file as-is.

The point is they either need to filter the served content, or serve it from a different domain (e.g. githubusercontent.com), otherwise you have XSS-like problems.

My understanding is that things like this are one of the reasons GitHub moved GitHub Pages subdomains from github.com to github.io.

See https://news.ycombinator.com/item?id=25350248

GitHub raw endpoints do it. They will either serve the SVG without an image/svg+xml Content-Type, making it not render in the browser, or you have to append ?sanitize=true to the URL which will, as the name suggest, sanitize it.

ok but that is github...parent poster stated its common to do that...it is not.

It's web security 101 for handling user uploads. (although in the case of SVG most sites solve it by just not accepting "weird" formats like SVG)

GitHub uses Camo [1] to serve assets like images and SVG files. It removes any "dangerous" code like JS from the file before serving it from a GitHub CDN.

1. https://github.com/atmos/camo

Ah svg, reminds me these fine windows metafile days.

Seriously, can we stop inventing formats that execute arbitrary code under the hood?

The problem isn’t SVG necessarily. It’s a nice vector format with many hidden features available to those who explore (especially with SVG 2 around the corner). The problem is JavaScript. Unfortunately, there’s not much one can do if they want interactive images[a][b] short of a Turing Complete language. And if you’re going to need that, JavaScript’s right there (for better or for worse).

[a]: Embedding the SVG directly into the HTML and manipulating it using the JavaScript in the HTML is an option, but not many people do that

[b]: We can argue all we want about whether we should be making interactive images in the first place, but the fact of the matter is, either you add it to your format, or someone else will

Can svg's even do anything malicious with that capability?

Where they can execute JS, they can do so in the same security context as the containing document. So, yeah, they can be used in situ for any privacy or security intrusion that a script tag can.

This is not entirely correct. An SVG file embedded in an <iframe> or <object> is a document itself, and if cross-origin, can not access the outer document. However, if not in a sandboxed iframe, it can still do things like trigger alert prompts or navigation.

Sorry, this is right. I should have said it’s just as capable or limited in SVG as a bare script tag in the same place.

Every time someone does, someone else comes along and either presents a compelling enough use case that arbitrary execution is introduced or just wraps the thing in an environment where it’s funneled in.

Are you sure?

Yes they use Camo, but that's a proxy to ensure that you don't serve JS from the same domain as github.com so that 3rd party assets have the JavaScript domain security policy applied.

I do not believe that Camo is a sanitising proxy... just a proxy.

Oh my! Never knew SVG was such a rabbit hole lol! Thanks for this info!

Camo is just a proxy that allows them to (a) always serve remote content from HTTPS and (b) more constrained CSP rules. Camo doesn't remove any code nor sanitize it.

Edit: I think I narrowed down where you were wrong! Github "raw" endpoints for repository files DOES have a sanitizing option. But that's not Camo (camo is for remote, non repo, assets (linked in comments or in markdown)).

I think allowing scripts and stuff in SVGs was a huge mistake that is why they are still not widely supported yet. For example you can't upload or send SVGs as images in typical messaging services or image sharing sited, in part because it would be a security vulnerability.

But as a consequence now we (still) have no easily portable vector format :'(

SVG is still a stupid format. Who wants to send image data through XML? It would be like sending a raster image through a big JSON array.

Who wants to send image data through XML?

SVGs aren't image data. They're a set of instructions for recreating image data using a structured language. XML is very good for data like that.

And their text format is exceedingly useful if you're writing code to generate them.

I don't think it would really be any more difficult if it were binary. The only real reason to use XML is better integration with HTML, CSS and JavaScript, which is admittedly a compelling reason.

But I think he's right - it would be nice if there was a "proper" binary vector format that was widely supported.

I mean, I can write a line of Python that goes

  print(f"""<rect x="{x}" y="{y}" width="{w}" height="{h}"/>""")

I find this eminently easier than working with a binary format.

That's a pretty error prone way of writing SVGs though. In well written code you would use a strongly typed API and that API would be exactly the same for a binary format.

Think about how you write Protobuf files for example.

In the circumstances where I actually cared I would use a strongly typed language with nice wrappers, of course ;) The reason why I love SVGs is you can just belt them out from scripts and it's the easiest thing in the world. Same reason why I love GraphViz and Netpbm.

Text-based formats like XML and JSON are good if most of your data is strings, but storing numeric data in decimal strings is both inefficient and inaccurate. That's why I think that HTML is an appropriate use of XML-like markup but perhaps vector images would need a true binary version.

However I agree with saagarjha that it is very easy to write code to emit SVG, which is nice.

SVG is vector. So basically XML is suitable for that task.

One could conceivably make a binary format based on Messagepack or Flatbuffers for vector data, which would be much more efficient and eliminate rounding problems of converting between floats and decimal numbers in text representations.

One version of the SVG standard had raw socket support, which thankfully was removed.

They basically wanted everything that Flash had.

If only this was accessible. All a screen reader will announce is "image" plus the alt text, you cannot navigate any of the text inside the SVG when it's embedded with <img>. I was always surprised that noone ever talks about this with regard to SVG badges in readmes. You can if it's embedded with <object> or <iframe> though, but GitHub doesn't allow that in markdown (just like they don't allow many useful things like <video>, forcing people to use GIFs instead). <iframe> actually being the more secure option here because you can disallow all scripts using <iframe sandbox> (and GitHub could easily enforce that). <iframes> still can't stretch to the content though without using JS even in 2020.

I doubt iframes can stretch to the content even with JS.

Maybe for special cases, where the content is from the same domain or is actively messaging the size outwards so you can code some interplay between the outer page and the iframe. But neither side can do it alone.

I'm on mobile and can't double check this right now, but couldn't you resize the frame until it no longer scrolls?

There are projects such as iFrame Resizer [0] for this, and you're correct that it does require cooperation from the iframe source.

[0]: https://davidjbradshaw.github.io/iframe-resizer/

Aren't SVG badges meant to be non-essential? Just display some stats to show-off?

Edit: To clarify, I'd love to see SVGs become more accessible, but I would hope the lack of support today isn't a problem as far as README shields.

If they are useful for sighted users, they are also useful to non-sighted users. E.g. if it is useful for a sighted user to read the weekly download count of a package to get a sense for how popular it is, to read the latest version, the license, etc (it arguably is) then the same applies to a non-sighted user. They shouldn't be forced to find and collect all that same information elsewhere (if it's available at all).

I imagine the hard part of securing <iframe /> tags isn't the sandbox, but instead maintaining user privacy. GitHub caches and proxies all of the images they render. One of the benefits of this is that a 3rd party can't fingerprint or otherwise log information about the requester. Seems a lot harder to get that right in the <iframe /> case.

It's technically possible to have an iframe with no "src" (not loading from a 3rd party) but still embed html/css inside the frame for sandboxing purposes.

I believe the sandbox attribute would also block javascript / scripts, although not sure what cross browser support on that looks like.

You can still cache an SVG embedded through <iframe> the same way you cache an SVG embedded through <img>. It's just an HTTP exchange. The sandbox attribute and a CSP can make sure no external content is loaded inside the SVG either (not even external images, fonts etc).

Accessibility software absolutely could read text from SVGs embedded using img tags. Just because none do so yet doesn't mean that it can't or won't be done.

Having a11y tools read svg's in img's as a part of the dom tree seems like it goes against the spec which says "An img element represents an image", and in basically all other places of the spec an image either has a proper alternate representation (the alt attribute) or is not parsed for a11y purposes.

This is a hack to be able to embed design within a tool that was never meant for graphic design. If github readmes where meant to be both accessible and designable they would not be just markdown/rst.

Your suggestion means a11y software having a hack that goes against the spec to enable a hack that was used to circumvent a platform that knowingly crippled it's document representation because they thought it would be used for mostly unstyled info.

SVGs can also be referenced with object tags at which part they become part of the DOM. This is required if you want SVGs with embedded hyperlinks to work.

Yeah, my point was having them as a11y objects in img tags, which is how they have to be used within the github readmes. felixfbecker's parent comment talked about object/iframes for SVG's.

That will run scripts inside the SVG though. <iframe> can be set to disallow that using `sandbox` and/or `csp`.

If your accessibility software gives up when it sees an image without an alt attribute, then I see that as an opportunity for improvement.

It's almost 2021. Accessibility software can use ML and OCR to provide a semblance of navigable semantics for visual-first media like images. See Project Naptha [1] for one such example of adding OCR-powered text detection to images encountered in your browser.

In the specific case of SVG, the text can already be fully semantically extracted with very little work.

1. https://projectnaptha.com/

This is not just about "text extraction", my whole point was that an alt text is not enough. An SVG document has a DOM and a navigatable accessibility tree just like HTML documents (including ARIA attributes etc). There is more that happens for sighted users too - text becomes selectable in the SVG, links are clickable, etc. All that probably needs the context of a browsing context and DOM created in an <iframe> or <object> and not in an <img> and is specced in detail. I really don't blame browsers for implementing the spec.

> Accessibility software can use ML and OCR to provide a semblance of navigable semantics for visual-first media like images. See Project Naptha [1] for one such example of adding OCR-powered text detection to images encountered in your browser.

Hey, if we really work at it, I'm sure we can make it impossible for anyone to use the Web without sending all of their information to an untrusted third party who has every incentive to violate your privacy, but won't, because they say they won't.

> It's almost 2021.

Indeed. We should have gone a lot further down this slippery slope by now.

Just because the parent's example of in-browser OCR involves a SaaS API, doesn't mean in-browser OCR inherently has to involve a SaaS API. OCR runs just as well on your own computer. Heck, phones could run the original realtime WordLens software just fine, and that was 10 years ago.

(Offline) OCR models should really be everywhere now, just like offline speech-to-text models are. It's kind of surprising that it's not just "a thing" built into every OS.

The pattern I've noticed is:

1) New technology exists

2) Accessibility nerds tell everyone not to use it, because it's not supported by screen readers

3) Everyone uses it anyways

4) Screen readers support it

5) GOTO 1

It seems very similar to people who think they can fix climate change by yelling at enough people not to buy certain things.

I think anyone who cares about accessibility and uses this for something serious would instinctively put more information in the README.md, and most people who aren’t even accessibility-minded will too because an SVG is really unlikely to tell the whole story even if all the content is embedded in it (which is almost certainly impractical since it’s not actually scalable).

Your comment is 100% correct and valuable.

I think we need to embed accessibility and accessibility audits as a basic and essential aspect of all tooling and standards. It shouldn't be up to diligent people like yourself to notice these issues as a matter of expertise or personal interest, but something we notice by default because it hasn't complied with standards.

SVGs are a minefield for accessibility and tend to be either wrapped in a container with accessibility info or have nothing at all added. It's a mess.

For most badges it would probably work to hard-code a size. I think the badge's document could also adjust to the size of the frame (via viewport dimensions) with JavaScript. I'm pretty sure though that GitHub couldn't resize a third-party iframe to its content even with JS because of cross-origin restrictions preventing it from accessing the document.

It's totally possible to create accessible SVGs [1], you "just" need to provide a text alternative. The challenge is that there is not the _best_ implementation out there and it might be problematic for large contents wrapped in a single SVG.

[1] https://www.deque.com/blog/creating-accessible-svgs/

What about

1. Use of AIRA tags on the <img> like `aria-label`

2. `aria-labelled-by` pointing to a <desc> within the SVG?

3. Using the <title> element within the SVG

4. Adding role="group" to make the SVG traversable

5. role attributes on each <g>roup.

JAWS and NVDA will announce this.

How are you going to express a whole chart in an aria-label string? SVGs have an accessibility tree. An alt string is not enough.

I'd use <g>roups inside the SVG for grouping contexts with their own <title>s (or references to labels) and ARIA roles and attributes. I didn't suggest having a single string represent a chart.

Fun :D it remembers me when I did this index.svg page like 10 years ago: https://vik.io/index.svg

I then used svg animation, but still seems to work perfectly today !

SVG seems like a under-utilized method! ;)

What are your opinions on SVG Animation vs CSS?

Well you can do amazing things with svg animations; there are a lot of interesting examples here that would be hard to reproduce in CSS: https://css-tricks.com/guide-svg-animations-smil/ (like try to do the car following a line example in css ...) but I try to stick to css animations for better "reviewability" of the code. SVG animation is a niche thing :)

This is neat. I'm a little worried it'll get abused. Actually, I know it will.

However, when I do come across it being used well, it'll be neat!

I have to say though, the developer (sindresorhus) is got to be one of the most prolific NPM package maintainers of all time, they have hundreds (if not thousands) of actively maintained packages. I know a lot of them are single use modules, but still, thats quite something! And the quality isn't bad.

Where does one find the time!

You can use scripted SVG in combination with github pages HTML using:

I couldn't get it working with README.md, so tipping the hat to the author!

The only problem and with the experience I got trying using it, is that the concept of viewport is botched. I was hoping that the embedded JS would have working metrics for the viewed width/height, which it does not.

That means that mouse events and such have transformed coordinates, not matching the position of the cursor.

I have this small project demonstrating the ways embedded JS gets rendered. I think I'm going to revise it and see if both projects can be merged.

https://github.com/xyzzy/scripted-svg

The whole point is that SVG images are basically never loaded with the embed tag, which is the reason why this is innocuous.

Embed is basically like using iframe, so where one is blocked, the other one is too.

The author simply loaded the SVG via the image tag, which renders it inert.

True, I started optimistic seeding much potential in possibilities to extend HTML only to discover that embedded javascript only works when the SVG is the main URL target or wrapped in <object> or <iframe>. Sad actually.

For 2021 we need more CPU & power-up cooling system just to read `README.md`

Is it possible to make a cryptocurrency with a proof of work that CSS can execute? That way, you could fund your project without ads, and even for users who have disabled JavaScript. Win-Winning!

> ... and even for users who have disabled JavaScript. Win-Winning!

Nice try, but you would not get any fund from those users who already use Links2 or Lynx![0] ;P

    $ links2 -g https://github.com/sindresorhus/css-in-readme-like-wat

Only those users who use "modern browsers" or at least Netsurf/Hv3/Dillo/Browsh still may support you.[1,2,3]

[0] https://news.ycombinator.com/item?id=16191843

[1] https://www.informit.com/articles/article.aspx?p=600978&seqN...

[2] http://www.kompx.com/en/lightweight-web-browsers-for-linux.h...

[3] https://www.hanselman.com/blog/lynx-is-dead-long-live-browsh...

That's funny, I was just playing around with making popup-ads in README.md this weekend!

https://lock.cmpxchg8b.com/tektronix.html

Maybe to focus just on the content, for that special place of the web that Github is, made some sense as well.

Coincidentally, I have a project using the same technique that periodically regenerates animated SVGs based on changing data for use specifically on GitHub. The generated images are styled with CSS in imitation of the actual GitHub site.

Since I could "borrow" the CSS actually used on GitHub, it was possible to make the images look like a natural part of the real UI.

https://github.com/jstrieb/github-stats/

Please don't turn github into myspace

It's too late https://github.com/bdougie

That can be a better way to do terminal sessions in readmes instead of animated gifs.

There's already https://github.com/nbedos/termtosvg for that purpose

Sadly, SVG still doesn't let you pause the animation, let alone copy-and-paste embedded text.

Given the number of Github projects that want terminal "demonstrations", I'm surprised Github hasn't just provided first-party support for it (with e.g. a fancy renderer for script(1) code-embeds, that would play back the script session by writing regular DOM text nodes; and which would give you transport controls to pause, scrub through, skip around, etc.)

While they're at it, they could also allow embedding of some kind of slide-deck format. Using GIFs for slides has all the same problems. (Hopefully nothing as fancy/complex as PPT; more like a basic-PostScript-profile PDF renderer, that would auto-carousel through the PDF's pages, until you begin interacting with it.)

Does :focus or :hover apply to CSS in SVG in an <img/> tag? If so, you could use those to implement a sort of pause by combining with the next-sibling operator (actually I really really like the + operator in CSS selectors, because a lot of things that people think you need JS to do can be done with a combination of :focus and +).

> Sadly, SVG still doesn't let you pause the animation

Not even through `animation-play-state: paused;`? e.g:

    :hover {
      animation-play-state: paused;
    }

The termtosvg repo linked by another commentor seems to have a pausable example in their examples gallery, so it appears to be doable.

The difference there is that the pausable SVG is embedded on the page as an object element. There is Javascript inside the SVG document that is enabling the replay to be pausable.

Github readmes however only allow embedding SVGs as images, and Javascript won't work in that case.

EDIT: added a missing word

At the very least support videos. That would make a lot of people happy, from being able to pause and fast forward demos in READMEs to issue filers that record the issue with a screen recorder.

All I see is an embedded SVG (?) not actual CSS in the readme.

I mean for that matter I could just use an iFrame to embed a HTML file.

you need to look at the svg code, svg can embed html/css/js

https://dochost.me Shameless promotion of a tool for hosting fancy rendered CSS/HTML in Github as a permalink w/ comment box.

Neat, and quite fun, but that’s not what essential documentation is for.

Some useful information about SVG security here https://www.w3.org/wiki/SVG_Security

Let's see how many days it takes to Samy 2020 reborn

Reference: https://samy.pl/myspace/tech.html

https://darknetdiaries.com/episode/61/

great episode as usual!

Neat, but doesn't work in GitHub's Android app.

Ha, there seems to be no way to get github to show you the actual source of this SVB (of any SVG?)

https://raw.githubusercontent.com/sindresorhus/css-in-readme...

Do you mean this: https://github.com/sindresorhus/css-in-readme-like-wat/blame... ?

Yes! You had to do a `blame` view to get it? OK!

What do you want to do exactly? On the repo, click the SVG file and then “Source”

If anyone's interested, I've been doing something quite similar for some time now on GitHub's readme.md. See: github.com/say4n/

How long now until GitHub is the MySpace of source code?

can you escape the "sandbox" and alter CSS values from the github.com host itself?

i.e. make the "login" button invisible, hide some text, etc?

I love things like this. They're so clever and creative while at the same time pointing out the absurdity of not having normal CSS.

Isn't this a privacy issue? You can track when someone loads the readme.md on the browser with a remote background image/fonts.

You’ve been able to load remote images forever, that’s how badges work. Yes it’s a privacy issue but it’s worth it because when these backends go down (which they do, often) you get a readme full of broken images.

It’s not a privacy issue because GitHub proxies and caches the images probably since 2016

Myspace has come to GitHub.

This is supercool!

Broken on mobile.

Wow, you can even do media queries with this. Lots of ideas!

Good lord.

What have you done??

gotta love that repo name tho

> Not an animated GIF

Actually, an animated SVG. Sigh.

DOOM when?

clever and cool!

TLDR: <img src="header.svg" />

I've never understood people that spend so much time making their README pretty with emojis, fancy tables etc.

Don't get me wrong, documenting your work is very important, but do it efficiently.

Github Readme's are turning more and more into developer myspace.

Just keep it text, to the point, start with why someone should care, then once they care, show them how to use it.

When I see some kind of video embed, it's a huge turn off, I don't want to watch some animation of your typos at high speed, or your fish terminal.

"Show me the money".

Edit: my point is: spend your time making your code better, sorting, fixing and clear your issues and merge or reject decade old PRs /s

> developer myspace

I don't think a better description is possible

I feel like GitHub has been taking a direction of a "social network for developers" for a while now, so that description is probably accurate.

It’s been that 100% of its existence.

I’ve never understood hn fascination with boring and ugly plain text sites. Reminds me of the infamous Dropbox comment.

> Reminds me of the infamous Dropbox comment.

For reference:

https://news.ycombinator.com/item?id=9224

Because they are reliable and consistent. This isn't a place where novelty is appropriate, IMHO.

The IETF nails it with their RFCs, e.g.:

https://tools.ietf.org/html/rfc5545

RFCs have a terrible reading experience. Especially on mobile or on a wide screen.

You're entitled to your opinion regarding RFC readability, but factually, you can't grep through a video like you can with plaintext. You also can't print out a video and highlight things or write notes in the margins (or do the equivalent with a PDF). Scrubbing back multiple times to catch a quickly spoken word or quickly dismissed graphic is the bane of my experience with such video documentation. To me, that may be a fine superficial introductory experience in some cases, but is a universally terrible one for understanding and reference.

I don't think anyone would favor a video over a RFC.

But already a RFC reader makes it a more pleasant experience than just the raw RFC you linked

https://www.rfcreader.com/#rfc5545

I'm not a huge fan of text-only but I definitely find the original easier to read than this website's version from a contrast perspective. I can't think why they would choose gray text on a gray background.

Ironically, the fact that the reader is even POSSIBLE is because of the neutral format of the source RFC. You sorta shot yourself in the foot there.

It would be just as possible if RFCs were written in HTML, like most web standards are. You probably wouldn't even need a reader at that point, but you could easily customize the styling with CSS (even user CSS with a browser extension) or just use the reading mode of your browser.

Now that I consider this, you're right. Semantic HTML was designed exactly for this.

A couple things here:

1) that RFC reader is alright, but it still isn't good on a phone. If you view the PDF version of any RFC on ietf.org, it has a hyperlinked table of contents, so you don't need a javascript version of it like what rfcreader.com provides, and you can store that PDF offline. You can also hit the TXT version of any RFC and it's passable in Safari's Reader View, I'd say better than rfcreader.com (I also tried Reader View on rfcreader.com and it has other issues, so it's like trading one set of problems for another, but I see no clear winner, so for me the tie breaker goes to ietf.org);

2) the OP made the point that text is preferable to video–I happen to agree–and I was responding to the hyperbolic (and again, subjective) pushback regarding "ugly" text, explaining a way that it is still functionally superior to videos (which can have wildly diverse quality issues of their own);

3) I didn't link the RFC, that was someone else.

Who is using video as documentation in their README? I’ve seen them as a marketing introduction or maybe a conference talk the author gave about the project but certainly nothing like a doc site in a video format

I like lightweight minimal styles as much as anyone, but I figure they could have made the PDF a good deal more presentable.

I don't see why the PDF should use the Notepad look - one can be too spartan.

People who love boring and ugly plain text sites are bound to be over-represented on a forum with an absolutely bare-bones plaintext-like design.

Spittin' facts over here.

I agree with you in principle -- the "web sites should never do things like choose their own typefaces, line lengths and line spacing" crowd always makes me sigh.

However.

We're not talking about web sites here, we're talking about README files. They should be absolutely readable and understandable if you're displaying them in a console -- that's arguably one of the underlying tenets of Markdown as it was originally conceived (e.g., that its source be as easily readable as a plain text email or Usenet message is). I like that GitHub renders Markdown documents, but a lot of time when you're mucking around with source, you're looking at, well, the plain document.

I think this is a fun hack to demonstrate how you can do ridiculous things in technically-still-Markdown documents, but it's unequivocally not something anyone should actually do in their Markdown documents. :)

It depends on the project for me.

If it's a graphical tool a screenshot can help a lot in deciding it of does what I need.

If it's a library a quick code snippet can give me a feel of whether it'll be a good fit for my project

I do tend to agree about the "Developer MySpace" feel of a lot of repos though.

You're assuming it takes that long to make these things.

You're also assuming your perception of the README is how most people consume it. To that end, I'll offer a counter-anecdote, I very much want a README to convey to me how the project is: built, used, and what I should know about contributing to it. For usage, having images and videos for certain tools is priceless.

I have to disagree, for beginner programmers those videos are really help out, and if it's supported by a good text doc, it is a win-win right?

Since I develop addons for blender my readmes contain gifs, video embeds and all the things you undoubtedly hate because that's the most efficient way to communicate what the tools actually do and how to use them. Not everyone develops command line tools.

READMEs and markdown in general are supposed to be as legible in plain text form as it is when rendered. But that's something the kinds of people who hang out on GitHub don't seem to give two shits about. Any time a project hosted on GitHub is cloned, chances are high that if you try to open the README, it's going to be filled with line noise that effectively means you must use the rendered view. It's no wonder things like building native support for markdown rendering into apps like VSCode are so desirable. Project authors are treating it like an intermediate form that no one is really ever supposed to look at unless they're going into the markdown to add/fix/change something just before submitting a pull request.

Yes. And that’s not because people are abusing README.md, but because abusing README.md is the only way for most projects to improve most first impressions for their project.

First of all, even if that were true, it wouldn't matter. If a project author is participating in the culture that involves the compulsion "to improve most first impressions for their project", that's just the toxic culture associated with traditional social media projected into a different venue, except it has a facade of respectability that keeps people from calling it out in the way people call out Instagram bullshit.

Secondly, it's not true. Don't care about the deleterious effects that comes from overvaluing social media impressions? Want to take part in that messed up, Black Mirror-esque world anyway? Take all that junk you're shoving into the README and put it on a real landing page. No one is forcing anyone to link people to the GitHub repo for first impressions.

Wow. A little flourish on a GH repo front page (which is also a README, because it’s been both for years) is Black Mirror-esque?

One-liner strawmanning isn't hard.

EDIT:

> which is also a README, because it’s been both for years

What is this even supposed to be a response to?

This isn’t worth my time except to say so.

Right, it was clear by the previous comments that you've figured out that low-effort spurious remarks pay off double since they sap energy from anyone foolish enough to try to address them while costing almost nothing on your end to make.

Not at all. I responded candidly with my own perspective and you took the most uncharitable interpretation and twice (now thrice) treated me as if I was responding as venomously as you are. I have abusive family and exes for that, I don’t need it from strangers.

"Wow."

Yeah okay I’m sorry that I was astonished by that. I don’t know how you made the connection between putting a little style in a README and Black Mirror. You went there very quickly and I didn’t have much to contribute other than surprise. I meant no offense.

On the other hand, there's nothing lamer than a project that purports to be 20 kinds of awesome, but in order to see so much as a single screenshot, we're expected to spend hours screwing around figuring out how to compile it from scratch.

If the project is meant to be shared with the community, the README should contain at least enough rich content to convey what it does.

A lot of times README doesn’t adequately convey the value of (especially UI-oriented) libraries. And the UX of linking out to formats that do is also terrible (I’m saying this as someone who does a lot of library research on my porch using my phone, constantly forgetting my breadcrumb trail because I’ve been bounced back and forth between the GH app and a few dozen browser tabs).

There’s definitely a valid use case for more visually expressive walk up experiences for many code projects that could and IMO should be supported at the repository host level. It doesn’t have to be myspace but it could definitely support more embedded example cases and at least some personality.

Presumably people who use tables, videos, and emojis to communicate have reached for those tools many times over the years, so that the process is no more burdensome than you deciding "I should use a bulleted list here". They probably have macros and keyboard shortcuts to let them communicate fast this way.

Developer myspace sounds great

Reply on news.ycombinator.com