grunt-strapdown
grunt task for strapdown.js
What Is This
This grunt task does a very stupid thing: it takes a set of markdown files and inserts each of them into a html template, where strapdown.js takes care of all the rest (the parsing and the styling).
For example, this markdown file xxx.md:
# I Am So Hungry
I am so hungry i can eat an elephant.will be converted into a xxx.html:
<!DOCTYPE html>
<html>
<title>a</title>
<body>
<xmp theme="cyborg" style="display:none;">
# I Am So Hungry
I am so hungry i can eat an elephant.
</xmp>
<script src="http://strapdownjs.com/v/0.2/strapdown.js"></script>
</body>
</html>(Something looks different about that </xmp> closing tag, see FAQ below.)
Drop this xxx.html into any static web server and open it from the browser, and strapdown.js will parse and style the markdown text for you.
Usage
Install this plugin:
npm install --save-dev grunt-markdownThen enable it in your gruntfile, e.g.:
# example gruntfile in coffeescript:
module.exports = (grunt)->
grunt.initConfig
strapdown:
default:
src: ['path/to/*.md']
dest: 'output_dir'
change_theme:
src: ['path/to/*.md']
dest: 'output_dir'
theme: 'slate'
custom_template:
src: ['path/to/*.md']
dest: 'output_dir'
options:
template: 'path/to/your/template.html'
templateData:
charset: 'utf8'
version: '1.0'
whatever: 'you want'
grunt.loadNpmTasks 'grunt-strapdown'You can then run this task with grunt strapdown.
Options
Follow the example gruntfile above, these are the options that the strapdown task accepts:
-
src: required, pattern(s) to match markdown files. -
dest: required, the directory where generated html files will be stored in. -
theme: optional, defaults to 'cyborg'. See here for strapdown's bulitin themes and see bootswatch for more. -
options.template: optional, path to html template. Copy and modify grunt-strapdown's default template from here to make your own template. -
options.templateData: optional, data to be passed into the template. We use lodash.template().
FAQ
-
So what my markdown file didn't get parsed, it's just inserted right into the middle of a html template?
Yes.
-
And then when I open the html from the browser, that
<script src="http://strapdownjs.com/v/0.2/strapdown.js">tag is gonna get downloaded, and it's gonna do the parsing and styling for me?Yes.
-
So i have to download a js file from somewhere else, that sounds weird and slow, why can't i just host that js file on my own server?
You can, but it's a little bit more complicated, because strapdown.js is not just a js file. In order to parse and style the markdown text, this js file will dynamiclly load some other js/css files from strapdownjs.com. So you can't just host that single js file, you need to host all those other js/css files on your server, i.e. you need to clone this repo github.com/arturadib/strapdown.
(Use the
templateoption to do this.) -
Oh, what about that
</xmp>tag in the example? The 'x' looks different.It's not the letter 'x', it's the multiplication sign '×'(wiki). Quote from strapdown.js:
Limitations:
It's an unlikely scenario, but since Strapdown uses the
<xmp>tag to wrap your Markdown (so that users don't have to escape special HTML characters), your text can't contain the string</xmp>.That's why the 'x's in
</xmp>s are replaced by grunt-strapdown before the insertion into html. -
So i read your test code, it's even longer than your task code, why do that?
I don't know why.
-
What's your favorite number?
License
MIT license, see LICENSE.