skeemas-markdown-validation

Easily write tests to validate json code blocks in your markdown documentation. This utility is a plugin for the skeemas validation library.

Install

npm install skeemas-markdown-validation --save

This will install skeemas-markdown-validation, and also install skeemas as a peerDependency if you haven't already installed it.

Usage

From within your markdown files you can provide relative links to schemas above each json code block:

./docs.md:

Add the plugin to skeemas and then validate your markdown files:

var skeemas = require('skeemas'),
    skeemasMarkdownValidation = require('skeemas-markdown-validation');

skeemas.use(skeemasMarkdownValidation);

// Use any test harness, validateMarkdown just throws errors on invalid json
describe('API Documentation -', function() {
    it('main documentation should have correct JSON', function() {
        // Validate your markdown
        var validator = skeemas();
        validator.validateMarkdown('./docs.md');
    });
});

For more examples look at the docs in our tests.

Running Independent Code Block Validations

If you use skeemas.validateMarkdown then an error will be thrown on the first case of invalid json. If you would prefer to see all the errors you have the option of running a test for each code block yourself:

var skeemas = require('skeemas'),
    skeemasMarkdownValidation = require('skeemas-markdown-validation');

skeemas.use(skeemasMarkdownValidation);

// Use any test harness, validateMarkdown just throws errors on invalid json
describe('API Documentation -', function() {
    // Get an array containing test details for each json code block
    var validator = skeemas(),
        tests = validator.markdownTests('./docs.md');

    tests.forEach(function(test) {
        // Create a test case for each schema-linked json block
        it('docs.md:' + test.json.line, test.execute.bind(test));
    });
});

Using References

If you want to use $refs in your schemas you will need to create a schema validator instance and add your references to it:

var skeemas = require('skeemas'),
    skeemasMarkdownValidation = require('skeemas-markdown-validation');

skeemas.use(skeemasMarkdownValidation);

var validator = skeemas();

// Add a reference
validator.addRef('/foo-base', require('./schemas/foo-base.schema.json'));

// Validate your markdown
skeemas.validateMarkdown('./docs.md');