Skip to content
This repository has been archived by the owner. It is now read-only.
Branch: master
Go to file
Code

Latest commit

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
bin
 
 
 
 
lib
 
 
 
 
 
 
 
 
 
 
 
 

README.md

node-markdocs

!!! PROJECT NO LONGER MAINTAINED !!!

simple docs for apps with markdown

Installation

$ npm install markdocs -g

Create a standalone docs app

$ markdocs create

Start the server:

$ node app

Create an embedded docs app

$ markdocs create docs -e

Initialize the docs app from your express app:

var express = require('express');
var app = express();

app.get('/', function(req, res){
  res.send('Hello World');
});

var markdocs = require('markdocs');
var docsapp = markdocs.App('/docs', app);

app.listen(3000);

Document Processors

Markdocs allows you to customize the processors that are used to transform your documents into HTML. By default Markdocs ships with two processors: Javascript and Markdown. However you can choose to replace these with your own processors or add additional processors. Note that the order of processors applied does matter.

Using cusotm processors

var options = {
  basePath: '/docs',
  useDefaultProcessors: false
};
var docsapp = markdocs.App(options, app);

// Add a custom processor
docsapp.addDocumentProcessor(function(context, text) {
  // Do your processing
  text = text.replace('!something', '<span>This is a wierd shortcut.</span>');
  return text;
});

// Add back the default processors after our first one
docsapp.addDocumentProcessor(markdocs.Processors.js);
docsapp.addDocumentProcessor(markdows.Processors.markdown);

External Consumption of Content

Markdocs supports the consumption of HTML content outside of the main side (for example embedding on a second site or using them in a SPA). You must set the options yourself from your host application as shown.

To return just the article HTML

Use embedded view: response.locals.embedded = true;

You must also provide a doc.embedded.jade template view in your theme. Typically this view looks like the following, but you may want to customize it.

!= sections.content

TO return the article data as JSON/JSONP

You must still provide the embedded view as shown above. In addition you can set the following.

response.locals.json = true or response.locals.jsonp = true.

Finally, in the JSON responses you can optionally include metadata by specifiying: response.locals.include_metadata = true;

The easiest way to use all of these in your app is to add a prerender middleware to your markdocs app as follows.

var embedded = function (req, res, next) {
  res.locals.embedded = false;
  res.locals.include_metadata = false;

  if (req.query.e || req.query.callback) {
    res.locals.embedded = true;
  }

  if (req.query.m) {
    res.locals.include_metadata = true;
  }

  if (req.query.callback) {
    res.locals.jsonp = true;
  } else if (!req.accepts('html') && req.accepts('application/json')) {
    res.locals.json = true;
  }

  next();
};

docsapp.addPreRender(embedded);

## Issue Reporting

If you have found a bug or if you have a feature request, please report them at this repository issues section. Please do not report security vulnerabilities on the public GitHub issue tracker. The [Responsible Disclosure Program](https://auth0.com/whitehat) details the procedure for disclosing security issues.

## Author

[Auth0](auth0.com)

## License

This project is licensed under the MIT license. See the [LICENSE](LICENSE) file for more info.

About

[DEPRECATED] simple docs for apps with markdown

Resources

License

You can’t perform that action at this time.