Notes: This is a documentation-driven-development series I am currently experimenting. So most likely the code doesn’t exists yet before publishing this article. What I am hoping is that even if the project eventually can not be finished, the idea could still live in somewhere.🤞🏼

Static site generators are a blessing. Since Jekyll and Github pages, the world had been moving towards static sites in big strides. To say the least, personal blogs are among the majority of them.

Static site generators are great in so many ways, the best parts probably is the 1. endless customizability and 2. content first.

However, there comes a cost. Thinking about the process you writing a blog post:

1. Open iTerm
2. cd ~/sites/orchardlabdev-site
3. hugo new content/posts/i-have-something-to-share.md
4. code .
5. Locate the new file and start writing.

Not to mention the specialized tools we are using here, to start writing something, we would need to do 5 steps. Of course you can have some shortcuts to streamline this process. But then in the writing mode, if you want to put a picture, you would need to drag it drop to a certain folder then grab the name and link it correctly in the markdown file. So much frictions to write!

So I am wondering, can we have a little helper doing some of these (if not all of them) for us? Something can make us writes more, think more, instead of fiddling the tools and facing 10 options. I would love to have something like this:

1. open a link
2. start writing
3. Drag and drop will automatically put the images in the right folder and insert the image link as well
4. After all done I can publish (which commits with message provided and then push to remote).

Can we build something like this? So that’s my plan.

Shape of the tool

1. I would like the tool to be a small binary. Which I can fire up in the static site folder.
2. It can automatically detect the static site generator according to the folder structure (Hugo or Jekyll).
3. The main editing interface would be a web UI which we can:
   • Write
   • Edit
   • Publish
4. (Optional) Basic authentication of the web UI. This is not required at all at the beginning but would be nice later on if we want to deploy it to the cloud.

Choosing the tools

For the binary I would like to use Rust, cause that’s a good one if you want your tool to show up on the HackerNews front page :-). Kidding aside, I think Rust is great at building cross-platform binary tools, and it’s fast too.

For the Web UI, I will use Svelte.

High level design

• File based. It’s all file based, meaning the file on the disk is the single source of truth. There is no database evolved at all.
• Rust will read the local folder structure and convert them into domain models.
• Key domain models here would be posts which correspond to the local markdown files
• Each post will have the common metadata cross different static site generator tools
  • title
  • author
  • published at
  • content
  • layout (this can be configured / changed)
• Folders contains the markdown files will be called collection
• New posts will automatically goes into the collection (if there is only one), otherwise user can choose where the default writing goes to
• Rust exposed RESTful API for our Svelte Web UI to use
  • List collections
  • List posts among each collection
  • Create new post (markdown file)
  • Save/update new post (markdown file)
  • Delete a post (markdown file)
  • Publish (which will trigger local git commit)

Since I am currently using Hugo, so I would like to support Hugo first and then increase the scope of the tool to others like Jekyll or 11ty etc.

What’s next

Next we will be start building the core logics using Rust first. See you next post.