The worst, most feature-less most horrible documentation system ever, except
that it's not. Write your docs in multiple markdown files *.mdpp
. Weave
them all into a single *.md
by making use of !INCLUDE preprocessor directives.
Supports synthetically embedding youtube videos, LaTeX
, interactive process
diagramming with joint.js
... github flavored markdown, and a bunch of other
stuff.
Includes are evaluated recursively and rendered in place. Awesome. Only one external dependency: Markdown-PP.
npm install --save baddocs
var baddocs = require('baddocs');
var config = {
// port: 9000,
// env: 'dev',
};
baddocs(config);
Setup a header.html
and a footer.html
. And author your *.mdpp. Here's what
you can do:
Check the example folder in the repo for more information. The example outputs the following markdown and serves it over express at a specified port:
Proudly, the worlds worst document engine. Ever.
1. Our story unfolds
1.1. Links with references
1.2. Math
1.3. Code
1.3.1. baddocs/index.js
1.4. Joint
1.5. Tables
1.6. Images
1.7. Video
1.8. Recursive in place markdown includes
1.9. Stuff in between
1.9.1. Epic unordered list of ordered numbers
2. The End
2.1. Twist
2.2. The Real End
3. References
You need docs fast. Should be like github flavored markdown, but more files. You'll need images, video, any javascript you haven't thought of yet, interactive diagrams, links with a reference section for citations, and tables and lists. Uh... automatic table of contents thats recursively generated across included files...
So you head off in that exact order and what do you get?: :
module.exports = function(config) {
var express = require('express'),
http = require('http'),
path = require('path'),
marked = require('marked'),
fs = require('fs'),
exec = require('child_process').exec;
var app = express();
config = config || {};
config.port = config.port || Number(process.env.PORT);
config.env = config.env || String(process.env.ENV);
config.path = config.path || process.cwd();
config.markedOptions = config.markedOptions || {
renderer: new marked.Renderer(),
gfm: true,
tables: true,
breaks: false,
pedantic: false,
sanitize: true,
smartLists: true,
smartypants: false
};
app.set('port', config.port);
app.set('env', config.env);
app.set('path', config.path);
app.use(express.static(config.path, 'includes'));
// development only
if ('development' == app.get('env')){
app.use(express.errorHandler());
app.use(express.logger('dev'));
}
app.get('/', function(req,res) {
// write the head
fs.readFile('header.html',function(err,html){
res.write(html,'utf8');
// then write the markdown body
fs.readFile('views/index.md',function(err,md){
if(err){console.log(err);}
marked(md.toString(),function(err,html){
res.write(html,'utf8');
// then write the closing tags for the head
fs.readFile('footer.html',function(err,html){
res.write(html,'utf8');
res.end();
});
});
});
});
});
exec('markdown-pp index.mdpp views/index.md',function(err,stdout,stderr){
if (err) {
console.log(err.stack);
console.log('Error code: ' + err.code);
console.log('Signal received: ' + err.signal);
}
if (stderr) {
console.log('markdown-pp: ' + stderr);
}
console.log('markdown-pp: ' + stdout);
http.createServer(app).listen(app.get('port'),function(){
console.log('Server on port ' + app.get('port'));
});
});
};
Interactive process charting (click a box to start the animation). Drag the boxes around if want. Try and put them back again exactly right if you're OCD.
<style> #basic{ display: inline-block; border: 1px solid gray; } </style>First Header | Second Header |
---|---|
Content Cell | Content Cell |
Content Cell | Content Cell |
!VIDEO "http://www.youtube.com/watch?v=uk-CF7klLdA"
Everything thats been included gets picked up by the TOC. github.
- 1 (one)
- 2 (two)
- 3 (three)
The end.
Fight the boss twice.
The end.