Show HN: Pimp My Readme | Hacker News Reader

Show HN: Pimp My Readme

pimp-my-readme.webapp.io

97 pointsjoshdsouza70 comments

I've noticed a lot of projects in the past few years put a lot of stuff like this in their READMEs, with the (presumable) end goal of making their repository really "pop" on GitHub. That's perfectly fine! But sometimes it goes so far as to actively impede reading the README in a text editor, since it's now full of tables and Markdown abuse aimed at making it render correctly on GitHub. It also has a tendency to break other sites (think package management indices) that tend to consume READMEs, as they're now being fed all kinds of weird GitHub-specific Markdown. That leads to an overall worse user experience, e.g. when I'm selecting a package from PyPI or crates.io.

Given that projects are now using their READMEs as de-facto `index.html` pages, we really ought to just have an `INDEX.md` or similar convention for presenting all the cute stuff.

Ideally those tools would render a file called README.md as readable HTML.

For example, w3m renders this project's README cleanly - https://ibb.co/WPDDL0d

That would be ideal, yeah. But I don’t begrudge them for failing to do so: GitHub-flavored Markdown is a significantly more complicated beast than “common” Markdown, which is itself somewhat fragmented.

Being slightly cynical here, I'd presume that's not a bug, but rather the intended outcome, and this phenomenon with markdown is just a canary for M$'s impeding extinguish phase (after having embraced and extended git forges like github).

Microsoft might be steaming ahead on it, but I think GitHub’s extensions to Markdown predate their acquisition by a few years.

Correct on the latter.

GFM (Github-flavored Markdown) - "In 2017, GitHub released a formal specification of their GitHub Flavored Markdown (GFM) that is based on CommonMark." (https://en.wikipedia.org/wiki/Markdown)

Microsoft acquired Github in 2018.

README or INSTALL (no extension) files should be plain text, folded at 72 columns. You should assume the people actually trying to build your software are working in a shell in a terminal and using less(1) or maybe vi or some other text editor to read the README file.

Even markdown is too much, though it's tolerable if named README.md so I at least can know to run it through a filter.

Including icons, emojis, animations in such a file is right out.

72-column lines are important because the IBM 709 vacuum tube computer(1958) could only read 72 columns from an 80-column punch card. (Due to its 36-bit word size.) Thus, FORTRAN only used 72 columns and this became a standard. 60 years later, this limitation is still affecting people.

Why can’t your editor or terminal support emoji? They’re just normal plain-text standard Unicode characters like letters, numbers, and punctuation.

I don’t know about these restrictions — they feel pretty excessive in a world where every engineer I know uses a terminal that can render Unicode and (at least) 256 colors. Plus, they usually have more than 72 (or 80) columns available.

In my mind, the thing that makes Markdown a nice format (in contrast to something like ReST) is that it decomposes gracefully — the formatting indicators correspond pretty closely to the conventions that email and other plain-text mediums use. The fact that it converts to HTML is just a cherry on top.

The 72 (or 80) column standard is one that is guaranteed to be accessible in virtually any circumstances.

Such as, say, just for the sake of argument, when you've been awakened at 2 am by a pager, have travelled an hour to the colo, have a multi-switch KVM wired to a cabinet of otherwise headless boxen, several of which are embedded / dedicated devices with no package installation or updates possible, several of which support only serial terminal access (possibly given an equivalent access over TCP/IP or USB), and for which the output standard is an 80x24 terminal.

This might include ILOM, IPMI, or similar protocols.

There's too much RF in the colo itself to make a phone call, let alone support wireless or mobile data.

In such a circumstance, relying on anything but 7-bit ASCII text becomes really dicey.

Unicode has over 144,000 characters presently supported with more being added constantly. Systems without ongoing OS support (such as the six year old Android tablet I'm typing this on) simply won't have the new hawtness^Wcuteness installed, and I'll be looking at some variant of ▯▯▯▯▯▯▯▯. Which in context won't be especially useful.

Documentation in MS Word, DOCX, PDF, PS, or ePub will be simmilarly opaque.

Documentation in strict HTML ... without dependencies on images, CSS, or JS, may be useful, if I can aim w3m or lynx at it. (And I can always simply view the source.)

Documentation, like lifeboats, fire-extinguishers, and aircraft emergency slides, is intended for use in the least favourable, not most favourable conditions.

Your high-powered, graphical, UTF-8 / Unicode lastest-motherlovin-codeset Retina-display monitor should have no issues in taking 72-character-wrapped text and unfolding it to longer line lengths.

That 15 year old bit of embedded kit corporate's been too fucking cheap to replace or swap out when the universe is melting down, not so much.

72 character lines is very annoying in a modern world. My display is 3440px wide and can easily fit 120 chars if I split it in thirds, the rest is just wasted space. Every terminal and text editor has word wrap now, this isn't a problem anymore. Even on a 1080p screen split it half, 72chars is too few.

No. "The arbitrary limitations that I have voluntarily put on myself and my system should be adhered to by everyone in the world, despite great detriment to anyone else who uses at rhis point decades old technology to its full capabilities." Are you hearing yourself?

There are so many other minorities out there that deserve being catered to a billion times more than you. People with real issues that they can't just turn off with a "startx" command.

Just because you code like it's the 90s doesn't mean everyone else has to. But I'm pretty sure even in the 90s everyone had word-wrap, so the 72 columns thingy never really made sense for texts that don't have indentation.

Nothing prevents README or README.txt from also being present.

Thank you for sharing! For those using this service, please keep in mind that screen readers are not able to access text in images. Since the markdown output does not contain `alt` text, use care when copypasting this into your `README.md`; someone who is visually impaired will not be able to perceive it.

Further reading: https://www.w3.org/TR/WCAG20-TECHS/H37.html

Thanks for catching this! I'll make an update adding the alt text as default when copy & pasting

Hey, I'm Josh & I wanted a way to add some customization to my readme, so I made this at my company hackathon last week.

This is an open source project so if you want to contribute just add your component and put up a PR. Thanks for your feedback!

GitHub repo here: https://github.com/joshdsouza8/pimp-my-readme

Awesome hackathon project. The font scroll is great 90s website nostalgia.

Thanks! 90s web nostalgia is what I was going for :P

It looks like a fun project.

However, I like a more subdued and less "pimped" look. I am a fan of https://shields.io/, e.g. my github profile: https://github.com/phaedryx/

I previously used something like that to add number of visitors on a repos Readme. Now it shows a broken image icon only because that service has been shut down.

Best option to use it continously is to host your own version and use that instead of the one you are providing.

Thanks for the feedback! I got permission to host the project on my company’s website after the hackathon, so it will be up indefinitely ;)

There’s also the option to just clone the repo, run, and host the server on your own as well, up to you.

Love the 90s nostalgia. Could also add something like…

  <blink>&#x1f3d7; This page is under construction. &#x1F6A7;</blink>

Haha that’s a great idea! Let’s bring the blink tags back, I’ll add it in tomorrow.

Also project is open source as well so if you have any ideas, you can open an issue for it (which I will get to) or just add it in whenever you can :)

It looks good, especially on your side projects. It will make your readme looks fun to read.

The emojis in the "Hey, I'm Jellybear!" marquee line look more like "octopus-bear" (or "octobear", to compliment GitHub's "octocat"?). Not sure if there's a jellyfish emoji though...

Original project: https://github.com/Akshay090/svg-banners

I can't read your README; I can't scroll down. Sorry.

Hey, could you give me a little more detail on what you're seeing (i.e. what browser are you using), would love to fix it so you can check it out. Thanks!

It seems to have improved now - I can scroll fine.

This is still the same browser session.

I'm on a laptop running FF 93.0, with Noscript and Adblocker Ultimate, both enabled. FF is running full-screen. It's Win10.

I didn't record what I saw earlier. Now, I see a number of clickable placeholder images, and a bunch of "Try me" buttons. My impression is that the site is for making marketing-friendly tags. That's cool, just not my thing. I didn't click.

Using the Facebook social icon given current events is just a smidge tone deaf.

I would genuinely like to read the rebuttals from folks who've downvoted this. Please, share your perspective.

Downvotes unfortunately do often only indicate disagreement. What makes it's tone deaf?

I suspect the common observation people would make is similar to "Because you don't like it, other's shouldn't like it as well?"

My reply to a sibling comment addresses your question: https://news.ycombinator.com/item?id=28983525

Cool, you dislike Facebook, but does that add value to the discussion about this project?

I think it does. There's a litany of information out now about how bad Facebook is - for everyone. The author is soliciting feedback, and to feature a Facebook icon as the social link on the demo doesn't take that into account. It's not a matter of liking it or not.

I don't think it does. And the mob of HN seems to agree with me (there's a scary thought). You also didn't answer why it's tone deaf. What tone do you think it strikes that is unwelcome? that's why your first comment is now dead. And why this responder asserts that it's not constructive to the discussion. You're asserting FB is bad, but not why. You don't make any claims, arguments, or suggestions you merely assert everyone should obviously be in agreement that the only reasonable response is to pretend FB doesn't exist, and/or has no value for sharing content. Because for what I'm left to assume is because it's "bad for everyone". I guess that's so obvious no one might disagree with you.

The assumption that there's a « tone » to be aware of is irritating. Not everyone follows the latest developments of tech drama or cares about it.

Reply on news.ycombinator.com