trailpack-markdown-doc
v2.0.0
Published
Trailpack for creating markdown documents with markdown-doc-bundler
Downloads
24
Maintainers
Readme
trailpack-markdown-doc
Trailpack for viewing markdown documents as html with metadata. Set your doc directory folder and the trailpack automatically creates routes for the directory and renders the parsed markdown into your layout file using meta-remarkable. Perfect for a documentation website or flat file CMS.
Cool Features
- Trailpack-markdown-doc will automatically blend with your existing routes. For example, if you have a view controller for the route
/docs/hello/world
and you have an markdown file at/docs/hello/world.md
then trailpack-markdown-doc will add the content and metadata to the route without altering the rest of your configuration. - This blending also does a "Fuzzy Lookup", so if you have a route that points to
/docs/hello/:world
and a markdown file at/docs/hello/Readme.md
then it will apply the content and metadata to all routes that match that pattern. - Trailpack-markdown-doc also resolves the children and siblings for each route in your markdown doc file stucture.
- Trailpack-markdown-doc also creates a js sitemap of all your markdown routes.
- Trailpack-markdown-doc uses Fuse.js for searching content and routes.
Install
With yeoman:
$ yo trails:trailpack trailpack-markdown-doc
With NPM:
$ npm install --save trailpack-markdown-doc
Configure
// config/main.js
module.exports = {
packs: [
// ... other trailpacks
require('trailpack-markdown-doc')
]
}
// config/markdowndoc.js
'use strict'
module.exports = {
// Directory containing docs
path: 'docs',
// Prefix to be used for routes
prefix: 'docs',
// The layout page to embed the doc
layout: 'index.ejs',
// The Settings for Remarkable
remarkable: {},
// The Settings for Searching the Routes
search: {
shouldSort: true,
threshold: 0.6,
location: 0,
distance: 100,
maxPatternLength: 32,
keys: [
'title',
'content'
]
}
}
Markdown
trailpack-markdown-doc supports YAML style Metadata in markdown documents (.md)
---
Title: My awesome markdown file
Author: Me
Scripts:
- js/doStuff.js
- js/doMoreStuff.js
---
## Header
Regular text and stuff goes here.
This way, a nice table is also created at the header of the page on sites like Github which makes this flatfile approach even more powerful.
Examples
// views/index.ejs (or your view engine) using MarkdowndocController
<!doctype html>
<html lang="en">
<head>
<title><% if ( meta && meta.Title ) { %><%= meta.Title %><% } else { %>Opps, no Title<% } %></title>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
</head>
<body>
<ul>
<% for(var i=0; i < sitemap.length; i++) { %>
<li>
<a href="<%= sitemap[i].path %>"><%= sitemap[i].title %></a>
<% if ( sitemap[i].children.length > 0 ) { %>
<ul>
<% for(var r=0; r < sitemap[i].children.length; r++) { %>
<li>
<a href="<%= sitemap[i].children[r].path %>"><%= sitemap[i].children[r].title %></a>
<% if ( sitemap[i].children[r].children.length > 0 ) { %>
<ul>
<% for(var rr=0; rr < sitemap[i].children[r].children.length; rr++) { %>
<li>
<a href="<%= sitemap[i].children[r].children[rr].path %>"><%= sitemap[i].children[r].children[rr].title %></a>
</li>
<% } %>
</ul>
<% } %>
</li>
<% } %>
</ul>
<% } %>
</li>
<% } %>
</ul>
<%- content %>
</body>
</html>