[HN Gopher] Custom Styles in GitHub Readme Files (2020)
___________________________________________________________________
Custom Styles in GitHub Readme Files (2020)
Author : davikr
Score : 26 points
Date : 2023-03-31 14:21 UTC (8 hours ago)
(HTM) web link (css-tricks.com)
(TXT) w3m dump (css-tricks.com)
| MilStdJunkie wrote:
| 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
| jwilk wrote:
| Discussed in 2020:
|
| https://news.ycombinator.com/item?id=25349068 (195 comments)
| kelnos wrote:
| 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.
| yakshaving_jgt wrote:
| Cool hack. It's no longer a README though. More of an INSPECTME.
| cxr wrote:
| 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
| perpil wrote:
| 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
| cxr wrote:
| 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.
| perpil wrote:
| 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.
| cxr wrote:
| 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>
| NackerHughes wrote:
| 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.
| cxr wrote:
| > 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
___________________________________________________________________
(page generated 2023-03-31 23:02 UTC)