Home

What about including external content in documentation?

We recommend doing this as a pre-processing step. Why?

1. The Markdown files in content/ should be absolutely literally the content on your website
2. Our test suite is able to peer into Markdown files, extract JS, JSON, etc., examples and test them in-place, with good errors.

An example is in the partial example: it

• Has doc sources in content-template
• Includes lodash for templating
• Includes a short template.js file that reads content in content-test, templates it (which inserts JavaScript examples inline)
• You can template.js to template your content. To do this automatically, you can include it in the build task too or in the prestart command so it runs before you start the testing server.

See Also

Applications that are really similar to Docbox: they generate REST API documentation from Markdown documents.

• Slate - Ruby, similar architecture to Jekyll
• Silk - Go
• restdown

Applications that aren't REST API specific

• Sphinx

In-depth REST API specs. These don't use Markdown - they use supersets of Markdown or custom formats. These usually aim to do more than documentation - they can generate SDKs, tests, specs. These aim higher and are more complex, and one might say they aim for a different workflow than Docbox

• ReDoc
• RAML
• Swagger
• API Blueprint + Apiary