atamanroman/markdown-styles

Markdown to HTML generator and multiple CSS themes for Markdown

Features

• 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

---

Quickstart

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

What's new in v1.2.x

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.

Just using the stylesheets

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.

Using generate-md

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.

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:

1. convert all Markdown files in ./input to HTML files under ./test, preserving paths in ./input.
2. use the template ./my-theme/page.html, replacing values such as {{content}}, {{toc}} and {{assetsRelative}} (see the layouts for examples on this)
3. (recursively) copy over the assets from ./my-theme/assets to ./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).

Syntax highlighting support (changed in v1.2.x)

generate-md supports syntax highlighting during the Markdown-to-HTML conversion process.

Supported:

• highlight.js via mds-hljs
• csv (using highlight.js css classes) via mds-csv

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).

Language-specific syntax highlighting and custom highlighters

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

--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

--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.

Metadata support

You can also 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.

This is rather imperfect, but works for small stuff, feel free to contribute improvements back.

Acknowledgments

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

Screenshots of the layouts

Note: these screenshots are generate via cutycapt, so they look worse than they do in a real browser.

roryg-ghostwriter

mixu-bootstrap

mixu-bootstrap-2col

mixu-gray

jasonm23-dark

jasonm23-foghorn

jasonm23-markdown

jasonm23-swiss

markedapp-byword

mixu-book

mixu-page

mixu-radar

thomasf-solarizedcssdark

thomasf-solarizedcsslight

Adding new styles

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