This blog post is being created using CODEDOC. And more specifically, it's being created in response to the activation of my hosted blog, I've never used CODEDOC before and is in an alpha stage at the moment, so I thought it would be interesting to give some first impressions on using them both.


CODEDOC is supposedly meant to be a tool for generating "beautiful and modern" software documentation. Like most static site generators these days, it's built on top of Markdown. You put your Markdown source content in a particular directory and voila, you have HTML. There are two primary differences between CODEDOC and other, similar, tools that I can tell thus far:

  1. You use TypeScript files to create or modify themes and React for custom components.
  2. You get a lot of out-of-the-box features that enhance the final output beyond what most others offer by default.

Some of those features include automatic support for light and dark versions of a theme, a "burger menu" for navigation, embedded per-page content navigation to jump around to different sections, and enhanced Markdown features.

I personally love TypeScript, so I think using TypeScript and React for custom components is great idea. However, I don't like it for theming. I would rather see something like Sass being used but I understand why they did it this way. It's not necessarily for me but it's ultimately a small thing. I could get used to using TypeScript to create config maps for themes, I just don't want to because nothing else I do typically has that flow for generating styling assets.

I do really like the enhanced Markdown so far though. In other tools you typically get similar behavior by creating partial views and "rendering" them within another piece of content. In some tools you can't even do that: whatever you write in that file is all you get, for the most part, and you just have to be alright with duplicating components that can't go, or don't belong, in a layout template.

The installation process for CODEDOC, however, was fraught with complications for me.

linkNode, NPM, Docker, and Windows

I'm not ashamed to say that I do a majority of my work on my Windows desktop PC. Docker is ubiquitous these days and I comfortably do all of my programming in containerized environments. And my setup for every project I work on is roughly the same at a high level:

So far I've never had an issue with this flow. Until now.

For some reason, CODEDOC will not install properly when I use this flow. If I do not bind mount my local working directory to the container, then CODEDOC installs and runs successfully. But if I want to do that, I need to either rebuild my container with every change I want to preview - copying the files into the new container build - or somehow copy files from my local filesystem to the container's filesystem.

After some debugging, it seems NPM is likely the culprit. Even though I use NPM on almost all of my other (web-based) projects, I have never run into these errors before. But to test whether it was NPM specifically, or something else within the CODEDOC installation process, I did a bind mount while excluding the .codedoc/node_modules/ directory. And that worked. So long as the directory where NPM installs dependencies is not bound to my local filesystem, npm install will run successfully and then CODEDOC can be used without issue.

What does it look like to exclude a single directory for a bind mount volume? Like this:

1version: "3.8"


3 blog:

4 build: .

5 ports:

6 - 3000:3000

7 volumes:

8 - ".:/home/blog"

9 - "/home/blog/.codedoc/node_modules"

Notice that second volume entry. Typically, Docker wants two paths separated by a colon (:) with the first path being a local path and the second being a path within the container. If you do not specify two paths, and instead give it a single path, you can effectively "exclude" that path from being bind-mounted. It's not the most elegant solution but it's simple and it works.

So that's how I use CODEDOC for the foreseeable future. Not sure why that's a thing, but it is.

Personally, I blame CODEDOC for using Node. It's not a great language choice for most applications and I feel like this would have been significantly better as a Go or a Rust application. If you're going to use Node to create something it should be a client web application. Notice I said client, because even for server web applications there are significantly better technologies. But I love TypeScript, React, GraphQL, and a handful of other Node projects and I whole-heartedly think there's a good reason to use that technology. In the right situation. Requiring a Node developer environment to write some blog posts... not one of those situations.

And there's no need to remove all things JavaScript even if CODEDOC used something other than Node for its CLI program. For example, when I want to use Bootstrap or Foundation for Sites I have choices around whether I just want the end-result because I'm alright with the defaults (typically JavaScript and CSS) or I want the source files so that I can customize and "compile" them myself (typically JavaScript and Sass). CODEDOC could have gone a similar route: allow people to either use "compiled" custom components and themes or use the source files to customize their output more minutely. Then developing custom components and themes is a separate issue from being able to generate "beautiful and modern" documentation. Separation of responsibilities.

If you haven't seen it yet, although if you're here I'm assuming you have or will be soon, is meant to be a blog platform for developers. It's a blogging platform by developers, for developers, of developers kind of thing. The concept is simple enough: people are free to post and read content, but you can optionally pay a modest and transparent cost to received curated reading lists. Authors can receive tips through the platform, of which I assume takes a small piece to at least cover transaction fees. I'm not sure how authors might profit from the curation side of things, if maybe they get a small payout whenever someone reads their content from a curated feed or if you are bound solely to tips. Although if you're using as a way to make money, you're using the platform wrong; it's not designed for that.

You host your blog on a public git repo somewhere, anywhere. So long as it's a public git repo that can clone, you can publish content. I think the simplest way to do that is with GitHub using a post-push action on the master branch. Then receives a notification when your repo is updated, it grabs the latest version, generates your blog using CODEDOC, and finally publishes that for general viewing. It's simple and effective.

I'm not sure if I would consider replacing my personal blog for this. And, of course, there's an issue of posting to multiple destinations. If I maintain my own website with a blog as well as have this one and maybe also have an account with Medium where I like posting... how do you decide where content goes? I guess you could say "all things software go to" but maybe I want some of that to go to my personal website, so how can I deploy that content to both sites? Does that even make sense to do? I don't have the answers to these questions yet; I'm still trying to figure it out.

linkInitial Impressions

So far I don't dislike or CODEDOC. I'm not a huge fan of everything it does and it's a very different way of doing blogs compared to what I'm familiar with. Hugo, Jekyll, and others... they have similar ways of accomplishing the same thing but it allows you to easily switch between them because of that. With CODEDOC you have such a significantly different approach that it's hard to simply switch.

Converting themes seems like it would be a massive pain. If you want to bring over your content that's easy enough but you'll have all of your newer content with all that awesome custom component stuff CODEDOC brings in and your older stuff won't have any of it. You might even have to edit your old content because you're trading front-matter configs for a completely different system that can, e.g., use the git author of a commit to determine who created a piece of content. It's cumbersome.

But are any of these things deal-breakers? Probably not. I think people will be more likely to only put new content on and separate its purpose from any other blogs they might maintain. Which is probably the best approach, especially considering the early nature of the platform.

Hero image by Kaitlyn Baker from Unsplash

Hero image by Glenn Carstens-Peters from Unsplash

CODEDOCNode, NPM, Docker, and Windowscoding.blogInitial Impressions

Home Using