markdown-styles

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

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

New! Syntax highlighting support

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

To enable the syntax highlighting support, install highlight.js:

npm install --save highlight.js markdown-styles

Note that you need to install markdown-styles locally like shown above and invoke it as ./node_modules/.bin/generate-md, so that require('highlight.js') will find the module we just installed locally.

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

New! --command

--command <cmd>: Pipe each Markdown file through a shell command and capture the output before converting. Useful for filtering the file, for example.

New! --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 (new!)

mixu-bootstrap (new!)

mixu-bootstrap-2col (new!)

mixu-gray (new!)

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