Markdown

Migrating documentation

Migrating documentation from one software platform to another can be painful. I remember the days when moving a Word document back and forth between Mac and Windows caused problems. I started working as a technical writer in September 2006, a month after the launch of Pandoc (the “universal document converter”), although I didn’t learn of its existence until many years later. It certainly would have helped with some of the migrations I’ve managed, but not all of them:

Bulk converting Markdown to HTML

Converting Markdown to HTML is easy. Just publish it with a static site generator (SSG). But maybe you’re using a cloud-based Markdown documentation solution, and you don’t have a local SSG. Then you probably don’t want to go to the trouble of setting one up just to do the conversion. There are free online converters, but I haven’t found any that do conversion in bulk. There are also plenty of code examples for languages like JavaScript and Python. But what if you just need your Markdown in HTML format now?

Component single-source multi-channel publishing with Markdown

This week, I finished work on the final beta of the classic BASIC interpreter I’ve been working on for the Chloe 280SE FPGA retro computer project. Like many home computers from the 1970s to the early 1990s, when you switch it on, you go straight into the BASIC editor. But unlike most home computers of the same period, it has effectively unlimited storage. And that means that it can include built-in help, a feature that Microsoft didn’t add to QuickBASIC until 1987.

Low budget developer portal

Back in 2019, I had to create a developer portal with no budget. I wrote up the experience and last year I published it here as a three part series. My requirements were that it would have the tri-pane view, with contents, endpoints and code examples, that developers would be able to contribute to it, and that it would support diagrams. My solution was to create a Markdown-based static site with Swagger APIs rendered by Redocly and diagrams provided by Mermaid. I must have been on to something because recently, Redocly had the same idea. It currently has a developer portal product in beta. If you want to check it out, the company is now running its own website on it. Now if you have no budget, you can still do it the way I suggested, but for US$3600 a year (at time of writing) there is an easier way that includes hosting.

Managing a ReadMe.io site from a Git repository

ReadMe.io is a popular user docs site. It has a Markdown editor, theme builder and Swagger / OpenAPI file import. It’s fast and responsive, and it looks nice. But the last time I checked, all your content goes in a bucket that you don’t have direct access to.

Creating diagrams with Mermaid

I’m a convert to writing docs in Markdown. Most of this website is written using it (displayed with Hugo). But sometimes you need to include a chart or diagram in your docs.