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
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.
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.
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...
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.
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!
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.
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.
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
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.
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.
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 :'(
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.
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.
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.
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.
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.
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.
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.
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.
> 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 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.
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.
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.
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.
> 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.
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.
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.
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 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.
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.
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.
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).
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).
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'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.
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.
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.
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.
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!
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.
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.)
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.
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 +).
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.
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.
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.
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.
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.
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.
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);
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.
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.
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 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. :)
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.
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.
https://github.com/boemska/create-sas-app