Custom Styles in GitHub Readme Files (2020)

28 points
1/20/1970
a year ago
by davikr

Comments


kelnos

Gross. That completely defeats the purpose of Markdown: still being human-readable[0] without a renderer step.

This takes a README and makes it not a README. If you want custom styles and to make something pretty, you want a webpage. And you can do that on GitHub Pages, so it's not like there's a huge barrier to having to set up a completely separate web host for your GH project.

[0] For the most part; you can of course still do some pretty unreadable things, especially with the Markdown extensions GH supports.

a year ago

yakshaving_jgt

Cool hack. It's no longer a README though. More of an INSPECTME.

a year ago

cxr

Definitely. One casualty of GitHub Flavored Markdown has been READMEs that aren't actually readable (as plain text).

Better than littering your README with useless* stylistic gewgaws: turn it into a form of "smart documentation"—

There is a way to write a plain text file so that it looks the same (i.e. appears as plain text) whether it has the .txt extension when it's opened in a text editor and/or Web browser versus whether you rename it to have a browser-associated file extension like .htm or .html and then re-open it in a Web browser. Documents opened Web browsers are programmable. A logical next step, then, is to write your README so that your build instructions say something like:

1. Open this file (README.txt.htm) in your Web browser

2. Drag and drop the project source directory onto this README (or click a button to select it from a file picker)

3. There is no step 3. The project will start automatically building in the background. You will be prompted with a ZIP containing all the build artifacts when the build completes, and you don't have to worry about installing any prerequisite tools or dependencies beforehand. (Wait, I lied—step 3 is, "Go figure out what you can do with all the extra time that this is going to save you.")

Related: <https://news.ycombinator.com/item?id=24495646>

* or worse

a year ago

NackerHughes

I'm not sure I'm following - unless this is the description of some concept, I must be missing something here.

> There is a way to write a plain text file so that it looks the same (i.e. appears as plain text) whether it has the .txt extension when it's opened in a text editor and/or Web browser versus whether you rename it to have a browser-associated file extension like .htm or .html and then re-open it in a Web browser.

What is this way? If you rename a plain text file to .htm(l) and open it in a web browser, none of the line breaks will be rendered, and of course there'll be no interactivity. If you add the necessary stuff to the .html file to allow for styling and compiling (more on this below), then when you open it in a text editor, you'll see all that extra markup that markdown tries to minimise (and GHFM somewhat brings back).

> Drag and drop the project source directory onto this README (or click a button to select it from a file picker) ... The project will start automatically building in the background.

How is this expected to work at all? AFAIK web browsers pretty much only use JS (or one of its 'transpiles to' analogues) for any sort of code you can execute in the browser (this also relates to your mention that "Documents opened Web browsers are programmable"), and are pretty heavily sandboxed to prevent running external binaries (e.g. gcc), so any project using any other language would be SOL.

a year ago

cxr

> none of the line breaks will be rendered, and of course there'll be no interactivity

Not sure what you mean by no interactivity, but yes, you'll need to add stuff to README.txt.htm to make the content (incl. linebreaks) render ~identically to the way it renders when you view it as README.txt, but that's not a big deal. It's < 8 lines of CSS, and you can "hide" it in plain sight if you're clever about it. In reality, though, you won't need to worry about hiding it, because once something becomes convention, people will just scan past it—just like elements on any other Web page that has a familiar layout (e.g. a GitHub repo), or the frontispiece and recto in a book, for that matter.

> all that extra markup that markdown tries to minimise

You don't need a lot of extra markup. Just the `<script>` and `<style>` blocks will suffice. (And, again, only a brief one in the case of the latter. You want to aim for everything to be either readable prose in the vein of Markdown or readable code that intersperses the prose in the vein of the sort of code blocks that you get to use in programming notebooks.)

I have, in fact, already written programs like this. Here's an example of one written in that style (although it's not a README.txt.htm):

<https://www.colbyrussell.com/LP/debut/plain.txt.htm>

The trick is to remind yourself that you're writing for a technical audience who wants a thorough (but succinct) specification of the internal workings of the machine. Here's another example of writing in that style (although not using the "plain.txt.htm" trick):

<https://crussell.ichi.city/gpe.html>

(And there's actually nothing stopping you from writing a "plain.txt.htm"-style program that looks that way when you first open it, but also accepts some command or key sequence that lets you toggle between the plain and the "rendered" form that looks something like that Google Podcasts exporter example.)

> web browsers [...] are pretty heavily sandboxed to prevent running external binaries (e.g. gcc)

Welp, definitely don't expect to be able to (easily*) do this for projects that have GCC as a development dependency, but this article was posted by the web developer Chris Coyier on a site for other web developerscalled CSS Tricks. The long-tail of packages on NPM and other bundling tools that are such a mess and can't be expected to reproducibly build because they adhere to what are poor-but-typical development practices in that world? Very good candidates for this style. (It's almost inconceivable that that community managed to create an ecosystem that is as frustrating—if not more—as the experience that you encounter with trying to wrangle traditional/"native" toolchains—and yet they did.)

Moar on that topic can be found here:

<https://www.colbyrussell.com/2019/03/06/how-to-displace-java...>

* I will say, though, that I have managed to use a similar trick to write cross-platform build scripts that are able to compile Wirth's Oberon system, including the ability to produce a disk image for Peter De Wachter's Oberon RISC emulator

a year ago

perpil

If this is what you're looking for you might checkout Speedrun. Markdown to build tools right into your GitHub readme's, runbooks and documentation. https://speedrun.nobackspacecrew.com

a year ago

cxr

I've seen Speedrun before (surprised?), but I'm not a fan, sorry. I can elaborate on my original comment and show you how to do it the right way (check out my followup to the sibling comment), but I'll warn you: this is a hard thing to productize. It's like trying to come up with a way to turn the idea of putting page numbers at the bottom of pages (and getting everyone else to do it, too) into a product. Or trying to turn not performing surgery without washing your hands into a product. The successful execution of this idea also pretty much necessarily obviates what would otherwise even remotely resemble a source of service- or sales-related revenue. Consulting is basically the only viable way, but I haven't even bothered trying to do that.

a year ago

perpil

I am surprised. I've only posted it in a comment once before and have zero SEO. How did you stumble upon it? Is your "right way to do it" your article on how to displace js? FWIW I'm not trying to monetize the extension to GitHub markdown.

a year ago

cxr

I tried tracking that down before my last comment. It definitely wasn't the other comment. Not sure when you added the link to your HN profile, but it's likeliest that I chanced up on it after clicking through from an unrelated comment/submission in another thread—maybe this one (if the time window fits): <https://news.ycombinator.com/item?id=33718850#33729686>

a year ago

jwilk

Discussed in 2020:

https://news.ycombinator.com/item?id=25349068 (195 comments)

a year ago

MilStdJunkie

Reminder that Blender3d Freestyle supports pure SVG animation as well. You could get some boss stuff in that splash page.

EDIT Provided you can get Freestyle to behave, obvs

a year ago