Skip to main content

Markdown Validator

Create software that detects errors in markdown documents.

Resulted in accelerated development (from hours to minutes), dramatically cut down on errors (from 1,000+ to almost zero), and created a better customer experience (more professional looking documents and no link errors).

Overview​

Markdown documents are the basis for IBM Cloud customer documentation.

Customer documentation starts out as markdown files with enhancements to support IBM-specific formatting and functionality.

Markdown documents are converted into HTML, which is published on IBM Cloud.

The problem​

The only way to validate markdown documents is to convert it to HTML and view the results. There are a few problem with this approach:

  • The HTML conversion process assumes you have pristine markdown documents, takes hours to run, has minimal error detection, and results in development delays. It often takes 4 hours to convert markdown documents to a HTML documents.

  • An error or omission in a markdown document is often difficult to detect in the on-line documentation.

  • Some errors result in entire blocks of documentation not being visible. This is a poor developer and customer experience.

  • Creating pristine markdown documents, across hundreds of documents, is tedious and too demanding to result in a professional product.

The solution​

Document developers need tools that validate markdown files and detect errors, without inducing a 4-hour delay.

The tool should detect invalid formatting, check for broken links, validate syntax, and hundreds of other problems.

The software​

Wrote a Go program to validate IBM-specific markdown files and report errors.

The software has hundreds of validation rules.

My software validates links across hundreds of IBM documentation projects, which are all cross-linked.

A "small" document repository may contain a 1,000 markdown errors. And there are hundreds of IBM Cloud documentation projects.

The software accelerated developed, dramatically cut down on errors, and created a better customer experience.

Technology​

The software was written in Go.