- Ready-made CSS stylesheets for Markdown, just copy the assets folder you want
- Bundled with
generate-md, a small tool that converts a folder of Markdown documents into a output folder of HTML documents, preserving the directory structure - Use your own custom markup and CSS via
--layout. - Support for relative paths to the assets folder via
{{assetsRelative}}and document table of content generation via{{toc}}. - Support for generic metadata via a meta.json file
Install generate-md via npm:
sudo npm install -g markdown-styles
Create a markdown file and then convert it to html:
mkdir input/
echo "# Hello world\n YOLO" > input/index.md
generate-md --layout mixu-gray --input ./input --output ./output
google-chrome ./output/index.html
Try out different layouts by changing the --layout parameter; screenshots at the bottom of this page.
If you want to make use of the bundled layouts stylesheets as a basis for your own site, copy the ./assets folder and point --layout to your own layout.
For example:
git clone https://github.com/mixu/markdown-styles.git ./markdown-styles
cp -Rv ./markdown-styles/layouts/mixu-gray ./my-layout
nano ./my-layout/page.html
Now edit the files ./my-layout/page.html and run:
generate-md --layout ./my-layout/page.html --input ./input --output ./output
v1.2.0: Code syntax highlighting has been reworked so that syntax highlighters have become pluggable. See the relevant section below on how to use the new system.
v1.2.1: added the bootstrap3 style, thanks @MrJuliuss!
v1.2.2: added the github style, based on sindresorhus/github-markdown-css.
Alternatively, if you just want the stylesheets for your own project, you can just copy the ./assets folder from the layout you want.
To preview the styles in the browser, clone this repo locally and then open ./output/index.html or run make preview which opens that page in your default browser.
This project also includes a small tool for generating HTML files from Markdown files.
The console tool is generate-md, e.g.
generate-md --layout jasonm23-foghorn --output ./test/
Here is an example of how I generated the project docs for Radar using generate-md, a Makefile and a few custom assets.
--input specifies the input directory (default: ./input/).
--output specifies the output directory (default: ./output/).
--layout specifies the layout to use. This can be either one of built in layouts, or a path to a custom template file with a set of custom assets.
--partials specifies the partials directory.
--helpers specifies the helpers directory.
To override the layout, simply create a directory, such as ./my-theme/, with the following structure:
├── my-theme
│ ├── assets
│ │ ├── css
│ │ ├── img
│ │ └── js
│ └── page.html
Then, running a command like:
generate-md --input ./input/ --layout ./my-theme/page.html --output ./test/
will:
- convert all Markdown files in
./inputto HTML files under./test, preserving paths in./input. - use the template
./my-theme/page.html, replacing values such as{{> content}},{{{toc}}}and{{assetsRelative}}(see the layouts for examples on this) - (recursively) copy over the assets from
./my-theme/assetsto./test/assets.
This means that you could, for example, point a HTTP server at the root of ./test/ and be done with it.
You can also use the current directory as the output (e.g. for Github pages).
generate-md supports syntax highlighting during the Markdown-to-HTML conversion process.
Supported:
To enable the syntax highlighting support, install the module (e.g. mds-hljs) and then use --highlight (e.g. --highlight mds-hljs) to activate the highlighter.
For example, to use highlight.js to highlight all code blocks:
npm install -g markdown-styles mds-hljs
generate-md --highlight mds-hljs ...
You will also need to include one of the highlight.js CSS style sheets in your assets folder/layout file CSS (e.g. by using a custom --layout file).
The handlebars.js template language is used to evaluate both the template and the markdown. Together with the meta.json, partials and helpers both template and markdown can be enhanced.
You can add a file named meta.json to the folder from which you run generate-md.
The metadata in that directory will be read and replacements will be made for corresponding {{names}} in the template.
The metadata is scoped by the top-level directory in ./input.
For example:
{
"foo": {
"repoUrl": "https://github.com/mixu/markdown-styles"
}
}would make the metadata value {{repoUrl}} available in the template, for all files that are in the directory ./input/foo.
Using handlebars.js we can go event farther. For example, you may add a tags array to the meta.json:
{
"foo": {
"tags": ["handlebars", "template"]
}
}While in the html you may:
<ul>
{{#each tags}}
<li>{{ this }}</li>
{{/each}}
</ul>Which will result in
<ul>
<li>handlebars</li>
<li>template</li>
</ul>Partials are html files that can be included via handlebars {{> partialName}} style. Usually they are .html files. For example, if footer.html resides in the partials directory, {{> footer}} will be replaced with footer.html's content. For more advanced topics, see handlebars partials documentation. Don't use content.html, it is reserved to the html generated from the markdown.
Helpers are functions that you can use throughout the template. See handlebars helpers .
For example, add linkTo.js to the specified helpers directory:
var Handlebars = require('handlebars');
module.exports = function(){
return new Handlebars.SafeString("<a href='" + Handlebars.Utils.escapeExpression(this.url) + "'>" + Handlebars.Utils.escapeExpression(this.body) + "</a>");
};In your meta.json
{
"foo": {
"links": [
{"url": "/hello", "body": "Hello"},
{"url": "/world", "body": "World!"}
]
}
}Somewhere in your template:
<ul>{{#links}}<li>{{linkTo}}</li>{{/links}}</ul>The result:
<ul>
<li>
<a href='/hello'>Hello</a>
</li>
<li>
<a href='/world'>World!</a>
</li>
</ul>You can use --highlight-<language> <module> to override the syntax highlighter for a specific language. <module> can also be a path to a file.
For example, you might use the mds-csv highlighter for csv code blocks. Input code block with language:
```csv
"EmployeeID","EmployeeName","PhoneNumber","ZipCode"
"1048","Jimmy Adams",5559876543,12345
```
Command:
generate-md --highlight-csv mds-csv ...
You can write your own syntax highlighter wrappers. Have a look at mds-hljs and mds-csv for examples. These come in two flavors:
Asynchronous (three parameters):
module.exports = function(code, lang, onDone) {
return onDone(null, result);
};
Synchronous (two parameters):
module.exports = function(code, lang) {
return require('highlight.js').highlightAuto(code).value;
};
--command <cmd>: Pipe each Markdown file through a shell command and capture the output before converting. Useful for filtering the file, for example.
--asset-dir <path>: Normally, the asset directory is assumed to be ./assets/ in the same folder the --layout file is. You can override it to a different asset directory explicitly with --asset-dir, which is useful for builds where several directories use the same layout but different asset directories.
I'd like to thank the authors the following CSS stylesheets:
- jasonm23-dark, jasonm23-foghorn, jasonm23-markdown and jasonm23-swiss are based on https://github.com/jasonm23/markdown-css-themes by jasonm23
- thomasf-solarizedcssdark and thomasf-solarizedcsslight are based on https://github.com/thomasf/solarized-css by thomasf
- markedapp-byword is based on the user-contributed stylesheet at http://bywordapp.com/extras/
- roryg-ghostwriter is based on https://github.com/roryg/ghostwriter
- github is based on sindresorhus/github-markdown-css (sorry, sindresorhus-github is too long to type as a layout name!)
Note: these screenshots are generate via cutycapt, so they look worse than they do in a real browser.
Create a new directory under ./output/themename.
If a file called ./layouts/themename/page.html exists, it is used, otherwise the default footer and header in ./layouts/plain/ are used.
The switcher is an old school frameset, you need to add a link in ./output/menu.html.
To regenerate the pages, you need node:
git clone git://github.com/mixu/markdown-styles.git
npm install
make build
To regenerate the screenshots, you need cutycapt (or some other Webkit to image tool) and imagemagic. On Ubuntu / Debian, that's:
sudo aptitude install cutycapt imagemagick
You also need to install the web fonts locally so that cutycapt will find them, run node font-download.js to get the commands you need to run (basically a series of wget and fc-cache -fv commands).
Finally, run:
make screenshots