Publish the Make a README post

astro.config.mjs

@@ -22,7 +22,6 @@ export default defineConfig({
         mdx(),
         sitemap({
             filter: (page) =>
-                !page.includes("blog/making-make-a-readme") &&
                 !page.includes("blog/software-engineering-manager-tactics") &&
                 !page.includes("blog/building-a-hyper-key-tree") &&
                 !page.includes("blog/debates-as-competitions") &&

src/pages/blog/making-make-a-readme.md → src/pages/blog/making-make-a-readme.mdx

@@ -2,19 +2,20 @@
 layout: ../../layouts/BlogPostLayout.astro
 categories:
   - programming
-date: "2024-01-15"
-unlisted: true
-tags:
+date: "2024-03-06"
+tags: side-project
 title: Making Make a README
 ---
+import Video from "../../components/video.astro";
 
 My side project with the highest gratification-to-effort ratio is a simple
-website called [Make a README](https://www.makeareadme.com) (the code is [hosted
-on GitHub](https://github.com/dguo/make-a-readme)). I made it in 2017 on a whim.
-I was trying to use a third party library that had an anemic README, and it
+website called [Make a README](https://www.makeareadme.com) (the source is [on
+GitHub](https://github.com/dguo/make-a-readme)). I made it in 2017 on a whim. I
+was trying to use a third party library that had an anemic README, and it
 reminded me of all the other frustrating times I've run into inadequate
-documentation and wished that [Stripe](https://stripe.com/docs) could write all
-the software documentation in the world.
+documentation and wished that [Stripe](https://stripe.com/docs) could
+[write](https://mintlify.com/blog/stripe-docs) all the software documentation
+in the world.
 
 I thought of [Keep a Changelog](https://keepachangelog.com) and decided to make
 a similar website for READMEs that explains what they are and suggests what to
@@ -26,36 +27,74 @@ I [started](https://github.com/dguo/make-a-readme/pull/1/files) with a simple
 `index.html`. I used [Bulma](https://bulma.io/) for styling and
 [Netlify](https://www.netlify.com/) for hosting. I
 [added](https://github.com/dguo/make-a-readme/commit/4673555488b77348a10371622470e03beca4b853)
-a Markdown template with a live preview and some more content over the next few
-days, and I was done! I posted the website to a couple of subreddits, it got a
-few thousand hits, the traffic died down, and I mostly forgot about the
-project.
+a [Markdown](https://en.wikipedia.org/wiki/Markdown) template with a live
+preview and some more content over the next few days, and I was done! I posted
+the website to a couple of subreddits, it got a few thousand hits, the traffic
+died down, and I mostly forgot about the project.
 
-But about a year later, I noticed in Google Analytics that traffic was
-consistently increasing. Google Search had started highly ranking the website
-for searches like "readme" and "readme template". Today, Google still drives the
-vast majority of traffic. Here are the top ten queries for the past month:
+But a year later, I noticed in Google Analytics that traffic was consistently
+increasing. Google Search had started highly ranking the website for queries
+like "readme" and "readme template". Today, Google still drives the vast
+majority of traffic. Here are the top ten queries for the past month:
 
 ![Google Search queries](https://i.imgur.com/JLUu8bj.jpg)
 
-I've tweaked the content a bit over the years, but the website is largely the
-same as it started. I did
+I've tweaked the content over the years, but the website is largely the same as
+it started. I did
 [migrate](https://github.com/dguo/make-a-readme/commit/090671b329ec998965f8fc9cc898a9c9c4386ab0)
 the styling to [Tailwind](https://tailwindui.com/), and I
 [started](https://github.com/dguo/make-a-readme/commit/58acff6f9335c86d12d037c347c9d4958ce0de26)
-using [Next.js](https://nextjs.org/) in preparation for some future enhancements
-if I ever carve out the time to do them.
+using [Next.js](https://nextjs.org/) in preparation for some future
+enhancements if I ever carve out the time to do them.
 
 For analytics, I started using [Plausible](https://plausible.io) after Google
 [shut down Universal
-Analytics](https://blog.google/products/ads-commerce/upgrade-to-google-analytics-4-before-july-1/),
-which made it a particularly good time to find something new. One reason I
-picked Plausible is that it allows me to make the analytics for a website
+Analytics](https://blog.google/products/ads-commerce/upgrade-to-google-analytics-4-before-july-1/)
+with [no way](https://webmasters.stackexchange.com/a/135975/93213) to migrate
+historical data into Google Analytics 4, which made it a particularly good time
+to find something new. One reason I picked Plausible is that it allows me to
+make the analytics for a website
 public, which I [did for Make a README](https://plausible.io/makeareadme.com/).
 As anyone can see, the website has had about two million visitors all time.
 
 ![Plausible screenshot](https://i.imgur.com/fDVtnRq.jpg)
 
+## Editable Template
+
+The only aspect of the website that isn't just text is the editable README
+template in Markdown. For the editor, I use
+[react-textarea-autosize](https://github.com/Andarist/react-textarea-autosize),
+which provides a
+[textarea](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)
+that automatically resizes based on the content.
+
+For the renderer, I use
+[react-markdown](https://github.com/remarkjs/react-markdown) in conjunction
+with [github-markdown-css](https://github.com/sindresorhus/github-markdown-css)
+to make the output have GitHub's Markdown styling.
+
+I also pass in a custom renderer for [code
+elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/code) in
+order to use
+[react-syntax-highlighter](https://github.com/react-syntax-highlighter/react-syntax-highlighter)
+for syntax highlighting. It was a little tricky to figure out how to set this
+up with Next.js and [TypeScript](https://www.typescriptlang.org/) because I
+wanted to use the async version of `react-syntax-highlighter`. The end result
+is that the renderer can do syntax highlighting for most languages, but the
+syntax file for a particular language will only be downloaded if the visitor
+actually chooses the language.
+
+In this video, you can see that when I change the code block's language from
+[Python](https://www.python.org/) to [Rust](https://www.rust-lang.org/), I get
+a `react-syntax-highlighter` file that's just for Rust. I do also get a file
+for [R](https://en.wikipedia.org/wiki/R_(programming_language)), since that's a
+valid language.
+
+<Video imgurId="4aIjsYb" />
+
+Most visitors will probably never get to the point of using a different
+language, so I'm happy to have avoided making them download unnecessary code.
+
 ## Monetization
 
 The website costs me virtually nothing to run, considering it's a static
@@ -68,27 +107,29 @@ to experiment with monetization, even as just a learning experience. I added
 developer-focused ads with [Carbon](https://www.carbonads.net/). I was okay with
 doing it because Carbon only adds a single display ad that has a decent chance
 of being relevant to the intended audience. Plus I never minded Carbon ads on
-other websites. I made a total of $153.36 from Carbon over about five months.
+other websites. I made a total of $153.36 from Carbon over about five months
+(about $30.67 per month).
 
 Then I moved to the now defunct
 [CodeFund](https://github.com/gitcoinco/code_fund_ads) platform, which had
-higher payouts in my testing. I made a total of $443.73 from CodeFund over about
-11 months.
+higher payouts in my testing, didn't use cookies, and was open source. I made a
+total of $443.73 from CodeFund over about 11 months (about $40.33 per month).
 
 After CodeFund shut down, I eventually switched to
 [EthicalAds](https://www.ethicalads.io/), which is a part of [Read the
-Docs](https://readthedocs.com/), doesn't use cookies, and is [open
+Docs](https://readthedocs.com/), also doesn't use cookies, and is also [open
 source](https://github.com/readthedocs/ethical-ad-server/). I made a total of
-$442.27 from EthicalAds for over 200,000 views over the course of a year. That's
-about $2 in revenue per thousand views.
+$442.27 from EthicalAds for over 200,000 views over the course of a year (about
+$36.86 per month). That's about $2 in revenue per thousand views.
 
 ![EthicalAds dashboard](https://i.imgur.com/FGukMy1.jpg)
 
-There was also a two year period where I [uninstalled the ad
-network](https://github.com/dguo/make-a-readme/pull/31/files) because
-[ReadMe](https://readme.com/) (e.g. documentation as a service) sponsored the
+There was also a two year period where I [uninstalled
+ads](https://github.com/dguo/make-a-readme/pull/31/files) because
+[ReadMe](https://readme.com/) (documentation as a service) sponsored the
 website. I have [Hacker News](https://news.ycombinator.com/) to thank for that.
-I saw a post asking about side projects that are making money. I
+I saw [a post](https://news.ycombinator.com/item?id=23438930) asking about side
+projects that are making money. I
 [commented](https://news.ycombinator.com/item?id=23443428) about Make a README
 and got a reply from [Gregory Koberger](https://gkoberger.com/), the founder of
 ReadMe:
@@ -98,26 +139,27 @@ ReadMe:
 > Really, though, your site is awesome. I just emailed you about sponsoring it,
 > if you're interested :)
 
-I laughed out loud when I read that because I had noticed before that Make a
-README would sometimes show up in search results ahead of ReadMe, so I knew who
+I laughed out loud when I read that because I had noticed that Make a README
+would sometimes show up in search results ahead of ReadMe, so I could guess who
 the commenter was even before I saw the username and profile.
 
 It was an easy decision to take the sponsorship offer because I was already a
 fan of ReadMe. I've done plenty of third party integrations at work, and when I
 open a company's documentation page for the first time, I can immediately
 recognize if they are using ReadMe. That's a positive sign for me that the
-documentation will be pretty comprehensive, relative to documentation by
-companies that build their own systems from scratch.
+documentation will be pretty comprehensive and useful, relative to documentation
+by companies that build their own systems from scratch.
 
-Lastly, I've received a couple of acquistion offers to buy the website. I turned
-them down because it's more gratifying to keep the website as a side project. I
-never intended to make any money off of this anyway, though it has been nice to
-earn a bit of essentially passive income from the advertising and sponsorship.
+Lastly, I've received two acquistion offers (four digits each) to buy the
+website. I turned them down because it's more gratifying to keep the website as
+a side project. I never intended to make any money off of this anyway. Though it
+has been nice to earn a bit of largely passive income from the advertising and
+sponsorship.
 
 ## Gratification
 
 Way more than money, the biggest source of gratification is just learning when
-people find the site to be useful. I have a monitor set up for with
+people find the site to be useful. I have a monitor set up with
 [F5Bot](https://f5bot.com/). It checks Reddit, Hacker News, and
 [Lobsters](https://lobste.rs/) for mentions of "makeareadme" and sends me an
 email when it finds something. I also occasionally [search
@@ -140,6 +182,6 @@ English. Adding translations would make the website more accessible to more
 people.
 
 I also want to add an interactive README generator. I think the current
-editable template is a good educational starting point, but it'd be nice if the
-website was more useful for experienced engineers who don't need the educational
-aspect but are making new READMEs.
+template is a good educational starting point, but the website could be more
+useful for experienced engineers who don't need the educational aspect but are
+making new READMEs.