[HN Gopher] CSS in GitHub Readmes
___________________________________________________________________
CSS in GitHub Readmes
Author : MH15
Score : 271 points
Date : 2020-12-08 18:05 UTC (4 hours ago)
(HTM) web link (github.com)
(TXT) w3m dump (github.com)
| retox wrote:
| Please don't turn github into myspace
| boomskats wrote:
| If anyone's interested, I'm particularly proud of my SVG
| animations in this readme:
|
| https://github.com/boemska/create-sas-app
| felixfbecker wrote:
| 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
| eins1234 wrote:
| This is really cool!
|
| Would be super helpful to have some example screenshots
| linked in the readme though, to help set expectations.
| felixfbecker wrote:
| 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.
| CharlesW wrote:
| 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...)
| chaorace wrote:
| Similar: emacs can take SVG screenshots of itself:
|
| https://gist.githubusercontent.com/alphapapa/65b0b9d4b3f5534.
| ..
| jrib wrote:
| what did you use to create them?
| arusahni wrote:
| Based on the SVG markup, termtosvg [1].
|
| 1: https://github.com/nbedos/termtosvg
| [deleted]
| notretarded wrote:
| Awfully laggy on slow machines.
| boomskats wrote:
| 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.
| conceptualspace wrote:
| ah i could have used this. my readme is a simulation of a
| github profile ;)
|
| https://github.com/conceptualspace
| tomwojcik wrote:
| Freezes mobile GH app on Android.
| ggerganov wrote:
| Cool idea, although with the new Dark mode on Github enabled
| it was very easy to see what is going on :)
| axihack wrote:
| Some useful information about SVG security here
| https://www.w3.org/wiki/SVG_Security
| rglover wrote:
| Wow, you can even do media queries with this. Lots of ideas!
| jrochkind1 wrote:
| 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...
| programbreeding wrote:
| Do you mean this: https://github.com/sindresorhus/css-in-
| readme-like-wat/blame... ?
| joshspankit wrote:
| Good lord.
|
| What have you done??
| keyle wrote:
| 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".
| voxl wrote:
| 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.
| krimpenrik wrote:
| 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?
| throwaway03857 wrote:
| 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.
| tenaciousDaniel wrote:
| > developer myspace
|
| I don't think a better description is possible
| godot wrote:
| 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.
| ulisesrmzroche wrote:
| I've never understood hn fascination with boring and ugly plain
| text sites. Reminds me of the infamous Dropbox comment.
| SoSoRoCoCo wrote:
| 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
| felixfbecker wrote:
| RFCs have a terrible reading experience. Especially on
| mobile or on a wide screen.
| wongarsu wrote:
| 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.
| judge2020 wrote:
| > Reminds me of the infamous Dropbox comment.
|
| For reference:
|
| https://news.ycombinator.com/item?id=9224
| sam_bristow wrote:
| 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.
| dheera wrote:
| 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.
| keithnz wrote:
| you need to look at the svg code, svg can embed html/css/js
| rhacker wrote:
| That can be a better way to do terminal sessions in readmes
| instead of animated gifs.
| derefr wrote:
| 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.)
| runarberg wrote:
| > Sadly, SVG still doesn't let you pause the animation
|
| Not even through `animation-play-state: paused;`? e.g:
| :hover { animation-play-state: paused; }
| uponcoffee wrote:
| The termtosvg repo linked by another commentor seems to
| have a pausable example in their examples gallery, so it
| appears to be doable.
| nitrogen wrote:
| 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 +).
| runarberg wrote:
| 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.
| Cloudef wrote:
| There's already https://github.com/nbedos/termtosvg for that
| purpose
| 2bitencryption wrote:
| 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?
| slmjkdbtl wrote:
| DOOM when?
| vikbez wrote:
| 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 !
| kdeldycke wrote:
| SVG seems like a under-utilized method! ;)
| pickledcods wrote:
| You can use scripted SVG in combination with github pages HTML
| using:
|
| <embed src="scripted-svg.svg" type="image/svg+xml" width="200"
| height="200">
|
| 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
| izgzhen wrote:
| https://dochost.me Shameless promotion of a tool for hosting
| fancy rendered CSS/HTML in Github as a permalink w/ comment box.
| nathell wrote:
| Neat, but doesn't work in GitHub's Android app.
| app4soft wrote:
| For 2021 we need more CPU & power-up cooling system just to read
| `README.md`
| mariopt wrote:
| Isn't this a privacy issue? You can track when someone loads the
| readme.md on the browser with a remote background image/fonts.
| pelasaco wrote:
| Let's see how many days it takes to Samy 2020 reborn
|
| Reference: https://samy.pl/myspace/tech.html
| ehsankia wrote:
| https://darknetdiaries.com/episode/61/
| remoquete wrote:
| Neat, and quite fun, but that's not what essential documentation
| is for.
| suyash wrote:
| clever and cool!
| felixfbecker wrote:
| 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.
| TooCreative wrote:
| 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.
| matt_kantor wrote:
| I'm on mobile and can't double check this right now, but
| couldn't you resize the frame until it no longer scrolls?
| bacondude3 wrote:
| 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/
| ancarda wrote:
| 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.
| felixfbecker wrote:
| 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).
| Sephr wrote:
| Accessibility software absolutely could read text from SVGs
| embedded using img tags. Just because none do so yet doesn't
| mean that it won't be done.
| SahAssar wrote:
| 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.
| firloop wrote:
| 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.
| kodah wrote:
| 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.
| guessmyname wrote:
| 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.
| bamboleo wrote:
| 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.
| jancsika wrote:
| 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?
| fractionalhare wrote:
| 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.
| porphyra wrote:
| 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 :'(
| frabjoused wrote:
| 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.
| bamboleo wrote:
| 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.
| NiekvdMaas wrote:
| 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
| buro9 wrote:
| 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.
| kebman wrote:
| Oh my! Never knew SVG was such a rabbit hole lol! Thanks
| for this info!
| wruza wrote:
| Ah svg, reminds me these fine windows metafile days.
|
| Seriously, can we stop inventing _formats_ that execute
| _arbitrary code_ under the hood?
| colejohnson66 wrote:
| 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
| gitgud wrote:
| Can svg's even do anything malicious with that capability?
| favorited wrote:
| One version of the SVG standard had raw socket support, which
| thankfully was removed.
|
| They basically wanted everything that Flash had.
| chrismorgan wrote:
| 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.
| inetknght wrote:
| > _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.
| mormegil wrote:
| 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.
| michaelmior wrote:
| My understanding is that things like this are one of the
| reasons GitHub moved GitHub Pages subdomains from
| github.com to github.io.
| [deleted]
| felixfbecker wrote:
| 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.
| Kiro wrote:
| See https://news.ycombinator.com/item?id=25350248
| antirez wrote:
| Maybe to focus just on the content, for that special place of the
| web that Github is, made some sense as well.
___________________________________________________________________
(page generated 2020-12-08 23:00 UTC)