Convert "Deterministic builds with clang and lld" to Markdown #63
Conversation
Fixes llvm#52 Sort of. Articles pre-sometime in 2020 are in HTML form and with https://github.com/JohannesKaufmann/html-to-markdown they convert pretty well but not enough to mass convert them. But since I put the effort into trying it I figured I would clean up this one that had been noticed. I used a script to reformat the header, html2markdown to convert and then added back some plain text/monospace/code markers where they had been missed, and removed some escapes that got added because those plaintext bits weren't marked properly. Now that it's Markdown, Hugo's theme will apply and produce the right colours for light and dark mode. The URL of the post will be the same.
|
The orginal author is Nico Weber and I can't add reviewers here, or @ them, so I'll send them an email instead. |
|
Thanks for the PR! Is there a way to preview how the md file will appear on the blog? |
|
@nico Yes, you'd need to clone the repo, and then run the local hugo instance. |
I tried following that and got Maybe https://github.com/llvm/llvm-blog-www?tab=readme-ov-file#building-locally could mention which version of hugo should be used? Also, maybe some additional setup step is needed for that GoogleAnalytics error? (I'm using |
|
I got it working locally with this diff diffIt'd be nice if it worked without local tweaking, though. |
There was a problem hiding this comment.
Thank you very much for doing this! This looks good except for a few small things below, and for one larger issue: IIRC I added the yellow highlighting back then to highlight all the flags and important parts that one should use, so that it's easy to scroll quickly through the document and see the "what should I actually do" bits. I don't know if we have something for that.
I suppose markdown has **foo** for highlighting, and maybe hugo makes it possible to set background-color on whatever class strong in markdown generates, and that could be set depending on light or dark mode? I don't know how that's usually done. (e.g. "Do not use these flags" was marked for emphasis, as were a bunch of flags.)
More of a question than a comment: It looks like this does one line of text per paragraph. Is that how all the md files look in this repo?
Also, I've been meaning to update the post with some new things for a long time, but it's good to do a clean conversion without any other changes first.
content/posts/2019-11-07-deterministic-builds-with-clang-and-lld.md
Outdated
Show resolved
Hide resolved
content/posts/2019-11-07-deterministic-builds-with-clang-and-lld.md
Outdated
Show resolved
Hide resolved
content/posts/2019-11-07-deterministic-builds-with-clang-and-lld.md
Outdated
Show resolved
Hide resolved
I'm using Hugo v0.119.0 so I didn't see this issue. There hasn't been a change to the theme in a long time (https://github.com/avianto/hugo-kiera) so I think we'd be ok patching it in this repo instead. I can do that if you like, if you don't mind me starting from your diff?
We can use HTML tags in Markdown, as long as we choose one that will be readable in a dark theme. I see there is a
I think this is just what the converter decided to do. Markdown can be same line or multiple and it'll treat it as one either way. I can 80 column break it if you like, but perhaps I do that once I've fixed the other things? |
Sure, thanks :) That was just local hacks to get things building though. I'm guessing we might not want to remove GoogleAnalytics on the actual page? (Don't know though.)
No strong opinion, do whatever you think works best in this repo. Maybe git diffs look a bit better (including on github) if paragraphs are split over several lines, but up to you. |
I've done this, it works well for light and dark themes. Except for the ml.py link which comes out white link text on yellow background, so I've highlighted the text that follows it instead. There is also a note at the start so the reader knows why bits of the text are formatted this way (it was not obvious to me at least). |
I had a go at it but I think it comes down to what's best for the person editing it. An 80 column wrap is a waste of space on a wide screen and the rendered copy will be automatically wrapped anyway. You're the author so you can wrap it later if it helps you make changes. |
Fixes #52
Sort of. Articles pre-sometime in 2020 are in HTML form and with https://github.com/JohannesKaufmann/html-to-markdown they convert pretty well but not enough to mass convert them.
But since I put the effort into trying it I figured I would clean up this one that had been (rightly) complained about.
I used a script to reformat the header, html2markdown to convert and then added back some plain text/monospace/code markers where they had been missed, and removed some escapes that got added because those plaintext bits weren't marked properly.
Now that it's Markdown, Hugo's theme will apply and produce the right colours for light and dark mode. The URL of the post will be the same.