indoorvivants / subatomic

A bad mdoc wrapper nobody should use

Subatomic

Do not use this, it's terrible and still not ready :)

Are you a Scala developer, writing a Scala blog or maintaining a Scala project?

If so, do you want a static site generator that:

• Requires you to write a lot of Scala
• Doesn't have a built-in theme
• Doesn't come with a nifty SBT/Mill plgun
• Barely does anything
• Is not configured with JSON
• Doesn't use React
• Acts as a glorified file manager and mdoc wrapper

If you answered "yes" to all of those, please head over to the Website

subatomic's Issues

Fail the build if unknown yaml frontmatter parameters are used

I hit this myself with scala-mdoc and mdoc parameters.

Dogfood tastes awful

Speed up loading time

https://pagespeed.web.dev/report?url=https%3A%2F%2Fblog.indoorvivants.com%2F2022-06-11-smithy4s-fullstack-part-2&form_factor=desktop

Include paragraph number from nearest heading

So that the matches can go to a more precise paragraph location.

Cached D2 diagram rendering

It can be quite slow, especially in watch mode:

success: successfully compiled - to - in 368.286875ms
success: successfully compiled - to - in 387.339416ms
success: successfully compiled - to - in 445.833791ms
success: successfully compiled - to - in 561.883084ms
success: successfully compiled - to - in 721.253334ms
success: successfully compiled - to - in 51.769209ms
success: successfully compiled - to - in 352.959292ms

Search: section-aware indexing

Blog builder: don't show archive if there's no archive posts

Link relativisation is broken on invalid links

Text like this: [0.0, 1.0]

Will trigger the following exception:

java.net.URISyntaxException: Illegal character in path at index 21: http://localhost/0.0, 1.0
  java.net.URI$Parser.fail(URI.java:2974)
  java.net.URI$Parser.checkChars(URI.java:3145)
  java.net.URI$Parser.parseHierarchical(URI.java:3227)
  java.net.URI$Parser.parse(URI.java:3175)
  java.net.URI.<init>(URI.java:623)
  subatomic.RelativizeLinksExtension$Resolver.resolveLink(RelativizeLinksExtension.scala:62)
  com.vladsch.flexmark.html.HtmlRenderer$MainNodeRenderer.resolveLink(HtmlRenderer.java:599)
  com.vladsch.flexmark.html.renderer.CoreNodeRenderer.render(CoreNodeRenderer.java:757)
  com.vladsch.flexmark.html.renderer.NodeRenderingHandler.render(NodeRenderingHandler.java:16)
  com.vladsch.flexmark.html.HtmlRenderer$MainNodeRenderer.renderNode(HtmlRenderer.java:779)
  com.vladsch.flexmark.html.HtmlRenderer$MainNodeRenderer.renderChildrenNode(HtmlRenderer.java:798)
  com.vladsch.flexmark.html.HtmlRenderer$MainNodeRenderer.renderChildren(HtmlRenderer.java:790)
  com.vladsch.flexmark.html.renderer.CoreNodeRenderer.renderTextBlockParagraphLines(CoreNodeRenderer.java:256)
  com.vladsch.flexmark.html.renderer.CoreNodeRenderer.render(CoreNodeRenderer.java:317)
  com.vladsch.flexmark.html.renderer.NodeRenderingHandler.render(NodeRenderingHandler.java:16)

Add authors notion in Blog builder

1. Configured as part of the builder (no YAML!),
2. author id mentioned in the blogpost document frontmatter (yes YAML!),
3. Author's name rendered on top of blogpost, as a link to
4. author page, containing socials and description

Single Page Application

1. All of the mdoc machinery stays in place
2. Most of the site config stays the same
3. A Scala.js frontend is created

Site builder publishes the following artifacts:

1. site.json - contains list of pages for navigation - it's the first file AJAXd from the server by the SPA
2. _pages/*.html - markdown pages (rendered to html) of the site
3. spa.js - bundled fully optimised SPA frontend

Navigation will need to be changed to:

http://site.github.io/#page/path?page-header

Which means it needs to be propagated into the search.

Watch mode and incremental rebuild

It's quite easy to hack

  def react(paths: Set[os.Path]) =
    def shouldReload(paths: Set[os.Path]) =
      paths.exists(_.ext == "md")

    if shouldReload(paths) then blog.main(args.toArray)

  os.watch.watch(
    Seq(blog.config.contentRoot) ++ blog.config.assetsRoot.toSeq,
    react
  )

What should versioned documentation look like?

This is a fun one.

Goals

1. As a library author (not me lol), I'd like to be able to have my documentation compiled against multiple versions of my project.
2. I'd like to have a unified UX for switching between versions
3. I'd like to be able to update and expand documentation for different versions independently.

Approaches

There are several ways of doing it that I know of, and they're orthogonal:

1. Weaver publishes all of its artifacts from the same branch, and the documentation for each version is built only once.

   • There's an Ammonite script that "freezes" the documentation for previous tag in the separate branch
   • This means that a) documentation for previous versions cannot be expanded (see cats-effect example to see why that's a problem) b) documentation is frozen statically - so whatever version of mdoc generated it at that time, that's what you get

2. Cats-effect takes a different approach - binary incompatible versions of the library are on separate branches, and so are the .md files for each version

   • This helps tremendously in the cognitive load of just being able to contribute markdown file changes to a branch and they'll be built against the version you have locally
   • The separate docs branch is updated asynchronously using dependabot - submodules point at CE3 and CE2 versions, which can build their markdowns
   • Any changes to documentation (even if they're not version-specific features, such as ecosystem documentation) need to be duplicated
   • There's great flexibility in how the site actually looks - you can structure the versioned parts statically, and only change the compiled markdowns.

Proposed solution

The landscape is changing. As often as the butterflies claps its wings, a new RC of Scala 3 is released, a new CE version emerges from the cocoon and all of that has to have a nice website go with it.

But we can't have nice things.

Stop using os-lib and upickle(?)

Unfortunately, it's a bit of a minefield when used with Ammonite, which brings in its own versions.

I had to to play a bit of Jenga with versions and still get a bincompat error during building a blog:

java.lang.NoSuchMethodError: 'boolean os.copy$.apply$default$7()'
  subatomic.Site.writeAsset(Site.scala:125)
  subatomic.Site.$anonfun$buildAt$1(Site.scala:85)
  subatomic.Site.$anonfun$buildAt$1$adapted(Site.scala:82)
  scala.collection.immutable.Vector.foreach(Vector.scala:1856)
  subatomic.Site.buildAt(Site.scala:82)
  subatomic.builders.blog.Blog$.createSite(Blog.scala:308)
  subatomic.builders.blog.Blog$App.main(Blog.scala:87)
  subatomic.builders.blog.Blog$App.main$(Blog.scala:75)
  ammonite.$file.blog$$anon$1.main(blog.sc:11)
  ammonite.$file.blog$.main(blog.sc:39)
  ammonite.$file.blog$$routes$.$anonfun$apply$1(blog.sc:48)
  ammonite.$file.blog$$routes$.$anonfun$apply$1$adapted(blog.sc:48)
  mainargs.Invoker$.$anonfun$invoke0$3(Invoker.scala:59)

Either shading it (undesirable), or relying on something with stronger bincompat guarantees, or just implementing your own for the small subset of operations that we actually need.

Probably the latter. Or better-files, if it's published for Scala 3.

Make library theme responsive

It's not amazing.

• Widescreen
• Narrow
• Mobile

Disqus integration

Unify Mdoc and MdocJS

The configuration is already unified, just needs a little bit more work.

Partial word matching in search

Currently we need a full match on a word for search index to be accessed.

Alternatively, at different levels of trie we could attach a list of candidates (top 10 by frequency?) so that they point directly at word nodes - which can be used immediately to render some search results.

Alternatively, look into research papers on partial matching, may be there's something better than just "top 10 by frequency" (IDF?)

Add mdoc and mdoc.js example to dev blog

So that integration runs on CI and I can make I don't break it again.

Add integration with trackers

Tracking is bad, but site analytics are useful.

• Google Analytics
• Matomo?

Probably implement them as first class concepts, similar with HighlightJS

Add Opengraph definitions to pages

Titles, URLs, site names, descriptions (when applicable)