There are a number of issues I'm already seeing and changes I want to make.
My links with text fragments still don't work, neither in Safari (Edit: Uh no, it's supposed to work in Safari!) nor Chrome. I also realized Firefox doesn't quite support this feature yet in version 130 but it is set to support it in 131. I just opened firefox and it self-updated to 131, so as of today this feature is good across all browsers. (Might be time to introduce a playwright test for this feature into this repo!) Maybe the reason for this failure is just that the Markdeep frontend rendering might not be handling the page load event properly.
This leads to me to the next realization about this blog system which is to really just pre-render out the page and serve plain HTML. This would definitely be a form of SSR which is all the rage nowadays. We have all those inefficiently built React pages burning up people's phones to thank for that. As someone who finds frameworks like React to be distastefully overcomplicated, although this does make me feel vindicated, hopping in a time machine to go back to the 1990s stone age also seems about equally silly. Anyway though, in this case, where I am hosting static content, and where I have plenty of reason to prefer the fastest possible render speeds for the site, this is a practical approach.
Although it's nice to get the automatic sections and stuff from Markdeep, I do find that it's a bit rigid. Certainly for many in-depth ones it would even be a big feature, but I have little interest in laying out ALL my blog posts like a textbook with hierarchically numbered sections. The text fragment based linking capability we already explored is a much more flexible and powerful way to target any specific location, and besides that I can always still fall back to ad-hoc HTML elements with assigned ids and make #-links to those. Before ditching this approach of grouping together Markdeep based pages to render them together, though, especially since I'm about to switch to running Markdeep as a process instead of relying on its frontend autorendering behavior, it will give me a lot of freedom to add my own twist on navigation and other aspects. Plus, I could also start to tweak these Markdeep css templates.
In terms of bringing the markdown rendering process into the build script, once I build up enough content it will make this script more sluggish to perform the work of re-rendering every page each time I run it. Once that becomes an issue I would just put a simple cache system in place so that this script can skip every document that hasn't been changed since the last run.
So it was a bit of a random way (exploring the Markdeep built-in TOC features) that I ended back up with assembling multiple blog post files into single longer pages. My original blog page i started 10 years back actually also was rendering out like this, but it gets quite long after a while. I think it does make sense to organize it so that we have mostly individual webpages that represent "sagas" that I update with individual files on a periodic basis, to capture the evolution of significant projects. These I could organize into individual folders. This is also sort of related to the notion of tagging posts with different labels to categorize them. But also, there are going to be many blog posts that are going to be me rambling about a topic unconnected or only loosely connected to anything else that I'm writing about. Those posts would just belong in the main blog/ folder.
This doesn't seem like a big deal but it definitely is an unclean interface and an issue I have with the Markdeep structuring for the folder to take the highest level heading (<h1>). I do want a firmer boundary around the markdown document when I author posts, so that they render "as intended" in standard markdown semantics. It otherwise feels a bit like going down a path where I would need to tiptoe around lots of different rules about markdown or other features that I can or cannot use depending on circumstances. Extra cognitive load there. An indicator of poor design. Of course, Markdeep was made by Dr. McGuire for his personal needs and surely excels at that, there is of course no implication along that direction. It feels like for now, one way to address this would be to establish two more higher levels of "header hierarchy" on my end to capture the file and folder boundaries. I would bring overall TOC/outline and navigation structure management under my control instead of delegating it to Markdeep.
Related to this, once I can establish converting each markdown file into HTML content for assembly into post pages in whatever structure I deem fit, this means I can also mix and match markdown dialects across these files. That's another pretty significant benefit.