mixu / markdown-styles

Markdown to static HTML generator and multiple CSS themes for Markdown

markdown-styles

Converts Markdown files to HTML, with over a dozen builtin themes.

Looking for something to generate a blog from Markdown files? Check out ghost-render.

Looking to automatically render your Markdown site on git push? Check out markdown-styles-lambda

Features

• v3.2.0 drops support for Node versions older than v10.12.0, removes mkdirp in favor of the native recursive mkdir and upgrades all dependencies to recent versions.
• v3.1.10 fixes an issue with single file inputs, thanks @josimard!
• v3.1.9 adds support for Chinese characters in heading link ids, thanks @weihong1028! Also includes a fix by @csandor for metadata with Windows line endings.
• v3.1.8 fixes an issue with links that consist of internal anchors, thanks @a7madgamal & @nazrhyn!
• v3.1.7 fixes an issue with paths on Windows and a default font protocol in mixu-page, thanks @hakkanicko and wirmar!
• v3.1.6 fixes a compatibility issue with Node 6, thanks @maximumstock!
• v3.1.5 updates some dependencies to add YAML syntax highlighting, thanks @omnibs!
• v3.1.4 added linkification for relative links to markdown files, e.g. [link](./foo.md) -> <a href="./foo.html">link</a>.
• v3.1.3 added a few additional properties to the programmatic API.
• v3.1.2 added default classes that allow you to style headings in the table of contents. See the changelog for changes made in older versions.
• Includes 15+ ready-made CSS stylesheets for Markdown, see the bottom of the readme for screenshots.
• Reuse the stylesheets or use the generate-md tool to convert a folder of Markdown files to HTML using one of the built-in layouts or a custom layout.
• Completely static output is easy to host anywhere.
• Metadata support: Each file can include additional metadata in a header section, such as the page title and author name which can then be used in the layout.

Layout features

• Built in support for code syntax highlighting via highlight.js; all layouts include a Github-style code highlighting theme by default.
• Built in table of contents generation from Markdown headings, fully customizable by replacing the {{> toc}} partial in custom layout.
• Built in header id and anchor generation for headings written in Markdown; all layouts support revealing the URL via header hover links.
• Support for custom logic for rendering code blocks via --highlight-*; this can be used to implement custom blocks that render the content of the code block in some interesting way. For example, I used this in my CSS book to implement hidden spoiler texts.
• Automatically detects the document title from the first heading in the Markdown markup.

Features for creating your own layout

• To make it easier to get started, you can export an existing layout using --exports and use that as a starting point for your layouts.
• Create your own layout based on an existing layout via --layout with:
  • Full Handlebars support for layouts, helpers and partials
  • Fully customizable table of contents template via the toc partial
  • Support for relative path generation via the {{asset 'path'}} helper
• API support: markdown-styles now has a public API

For changes, see the changelog.

---

Quickstart

Install generate-md via npm (to get npm, just install Node.js):

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 github --input ./input --output ./output
google-chrome ./output/index.html

Try out different layouts by changing the --layout parameter; screenshots are at the bottom of this page.

generate-md CLI options

• --input <path> specifies the input directory (default: ./input/).
• --output <path> specifies the output directory (default: ./output/).
• --layout <path> specifies the layout. It can be:
  • The name of a builtin layout, such as github or mixu-page.
  • A path to a layout folder (full path, or a path relative to process.cwd).
  • A layout folder consists of:
    • ./page.html, the template to use in the layout
    • ./assets, the assets folder to copy over to the output
    • ./partials, the partials directory
    • ./helpers, the helpers directory
• --export <name>: Exports a built-in layout to a directory. Use --output <path> to specify the location to write the built-in layout. For example, --export github --output ./custom-layout will copy the github builtin layout to ./custom-layout.
• --highlight-<language> <module>: Specifies a custom highlighter module to use for a specific language. For example, --highlight-csv mds-csv will highlight any csv code blocks using the mds-csv module.
• --no-header-links: If this flag is passed, the HTML for header links will not be generated. The hover links are enabled by default.

The resulting output

The output HTML is fully static and uses relative paths to the asset files, which are also copied into the output folder. This means that you could, for example, point a HTTP server at the output folder and be done with it or push the output folder to Amazon S3.

For example, here is how I deploy one of my books: aws s3 sync ./output/ s3://some-s3-bucket/some-folder/ --delete --exclude "node_modules/*" --exclude ".git" (assuming credentials are in the necessary environment variables and that the AWS CLI is installed).

Syntax highlighting

v2.0 has syntax highlighting enabled by default. Every layout has also been updated to include a default highlight.js syntax highlighting theme, which means everything works out of the box. For more highlighter themes, check out this demo site - you can find the highlight.js CSS styles here.

To enable language-specific syntax highlighting, you need to specify the language of the code block, e.g.:

```js
var foo = 'bar';
```

v2.0 also supports additional language specific syntax highlighters - check out mds-csv for an example of a syntax highlighter for a specific language.

To enable additional language-specific syntax highlighters, install the module (e.g. mds-csv), then add --highlight-{languagename} {modulename} to the command line. For example, generate-md --highlight-csv mds-csv ... to enable the CSV highlighter for csv code blocks.

Table of contents

The following built in layouts include the {{~> toc}} partial:

• mixu-book
• mixu-bootstrap-2col
• mixu-gray
• mixu-radar

These are mostly templates that have a sensible place to put this table of contents, such as a sidebar. I didn't want to default to putting a table of contents into the layouts that had no sidebar, but you can add it quite easily.

The {{~> toc}} partial generates a table of contents list. The list contains links to every header in your Markdown file. In addition, every Markdown header is automatically converted to a linkable anchor (e.g. #table_of_contents) when the page is generated.

You can customize the table of contents markup by overriding the ./partials/toc.hbs partial in your custom layout. By default, it looks like this:

<ul class="nav nav-list">
  {{#each headings}}
    <li class="sidebar-header-{{depth}}"><a href="#{{id}}">{{text}}</a></li>
  {{/each}}
</ul>

Note that by default (since v3.1.2), each heading list item has a class that depends on the level of the heading (.sidebar-header-1, .sidebar-header-2, ...). Thanks @mixinmax!

The headings metadata is an array of objects with:

• an id field (the HTML anchor id),
• a text field (the heading text) and
• a depth field (the depth of the heading, e.g. the number of # characters in the heading).

Header hover links (v2.1)

If you are reading this on Github, hover over the header above. You'll see a link appear on the side of the header. The same feature is supported by all of the layouts. The feature is implemented purely with CSS, and you can find the details in pilcrow.css in each layout's assets folder. To disable the feature, pass the --no-header-links flag.

v2.4 added support for having unique links for duplicated header names (e.g. using the same header text multiple times in the same file). The header id for the first occurrence stays the same as earlier (#header-text), but the second and subsequent headers get a counter appended (e.g. #header-text-1, #header-text-2). Thanks @xcv58!

Metadata sections

Each markdown file can have metadata associated with it. To set the metadata, start your markdown file with a metadata block that looks like this:

title: Page title
---
# Hello world
YOLO

There must be at least three - characters that separate the header from the rest of the content (on a single line).

You can reference the metadata values in your template by name. The default layouts only make use of the {{title}} metadata value, but your custom layouts can refer to any additional fields you want.

{{title}} is used as the page title. If you do not set the value explicitly, it is automatically detected from the first heading in the markdown file.

The metadata can also be written using JSON syntax or YAML syntax. This makes it possible to add arrays and hashes in the metadata. Using handlebars.js you can go even further. For example, you can add a tags array into the metadata section:

title: Page title
tags: ["handlebars", "template"]
---
# Hello world

... which can then be iterated over using the standard Handlebars {{#each}} iterator:

<ul>
{{#each tags}}
    <li>{{ this }}</li>
{{/each}}
</ul>

which will result in:

<ul>
    <li>handlebars</li>
    <li>template</li>
</ul>

If you take a look at the {{~> toc}} built in partial, you can see that it is actually iterating over a metadata field called headings using the same syntax.

Writing your own layout

v2.0 makes it easier to get started with a custom layout via --export, which exports a built in layout as a starting point. Just pick a reasonable built in layout and start customizing. For example:

generate-md --export github --output ./my-layout

will export the github layout to ./my-layout. To make use of your new layout:

generate-md --layout ./my-layout --input ./some-input --output ./output

If you look under ./my-layout, you'll see that a layout folder consists of:

• ./page.html, the template to use in the layout
• ./assets, the assets folder to copy over to the output
• ./partials, the partials directory
• ./helpers, the helpers directory

See the next few sections for more details for how these features work.

Template Evaluation (page.html)

The handlebars.js template language is used to evaluate both the template and the markdown.

Here is a list of all the built in features:

• {{~> content}}: renders the markdown content
• {{asset 'asset-path'}}: renders a specific asset path
• {{~> toc}}: renders the table of contents
• {{title}}: renders the title from the metadata section

Any metadata fields you have defined in the page's metadata section can be referenced in page.html by name. For example, {{title}} is replaced with the value of the title metadata field when the template is rendered.

You can include your own helpers and partials in your custom layout as shown below.

Assets folder (./assets)

All files in the assets folder are copied from the layout folder to the output folder.

To refer to files in the assets folder, use the {{asset 'path'}} helper. For example, {{asset 'css/style.css'}} will be replaced with a relative path to the file in ./assets/css/style.css. Take a look at the built in layouts for some examples.

Partials

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. You can override the toc partial by adding ./partials/toc.html as a partial in your custom layout, e.g.

<h1>My Table of Contents</h1>
<ul class="nav nav-list">
  {{#each headings}}
    <li><a href="#{{id}}">{{text}}</a></li>
  {{/each}}
</ul>

Helpers

Helpers are functions that you can use throughout the template. See handlebars helpers. For example, add linkTo.js to the ./helpers directory in your custom layout:

var Handlebars = require('handlebars');
module.exports = function(){
  return new Handlebars.SafeString("<a href='" + Handlebars.Utils.escapeExpression(this.url) + "'>" + Handlebars.Utils.escapeExpression(this.body) + "</a>");
};

Next, in ./my-layout, run npm install handlebars (since we're requiring handlebars) in the code.

In your metadata heading:

links:
  - url: "/hello"
    body: "Hello"
  - url: "/world"
    body: "World!"
---
# Hello world

or:

links: [ { url: "/hello", body: "Hello"},
         { url: "/world", body: "World!" } ]
---
# Hello world

and somewhere in your template:

<ul>{{#links}}<li>{{{linkTo}}}</li>{{/links}}</ul>

Note the usage of the "triple-stash", e.g. {{{ here. The technical reason for this is documented in this issue in Handlebars and will be apparently fixed in Handlebars 3.0. For now, use triple-stash to invoke any helpers that generate HTML.

... will result in:

<ul>
  <li>
    <a href='/hello'>Hello</a>
  </li>
  <li>
    <a href='/world'>World!</a>
  </li>
</ul>

meta.json (new behavior in 3.x)

If you want to apply additional metadata to all Markdown files in a particular folder, you can add a file named meta.json to the root of the input folder.

For example, if you run generate-md --input foo, the meta.json file should be located at ./foo/meta.json.

(Note: in v1.x, meta.json was read from process.cwd(), e.g. the folder from which you ran generate-md).

Metadata handling has changed in v3.0.0. The metadata is now applied by sequentially merging keys which represent paths. This allows you to set default values for all of the files and then override those values for each subdirectory in meta.json

The keys in meta.json represent file paths relative to the root of the input directory. Each file will be rendered with the merged metadata.

Here are a couple of quick examples:

meta.json content	{{key}} is available in:
{ "*": {"key": "value" }}	all input files
{ "foo": {"key": "value" }}	./input/foo.md
{ "foo/*": {"key": "value" }}	./input/foo/* and subdirs
{ "foo/bar": {"key": "value" }}	./input/foo/bar.md
{ "foo/bar/*": {"key": "value" }}	./input/foo/bar/* and subdirs

More specifically, the merge proceeds as follows:

• Start with an empty object
• Read the * key in meta.json
• Take split the pathname of the current file relative to the input directory by the path separator (/ in Linux/OSX and \\ in Windows; note that the key lookup will always use / on all platforms). For example, if the filename is ./input/a/b/c.md and the input directory is ./input, then the path components would be a, b.
• Concatenate the components one by one and look for keys that end with the concatenated path + /*. For example, for ./input/a/b/c.md, the keys will be a/*, a/b/*.
• Merge the metadata values from the keys in order of specificity, e.g. starting with the values under the * key, then a/*, then a/b/*.
• Look for a key that matches the full relative file name without the extension. e.g. a/b/c, and merge that in.
• Read the file, and overwrite the metadata values with the values set in the file.
• Finally, if the title property is still not set, automatically set using the first heading in the markdown file.

For example, a ./input/meta.json file like this:

{
  "*": {
    "repoUrl": "DEFAULT"
  },
  "foo/*": {
    "repoUrl": "MORE SPECIFIC"
  }
}

would make the metadata value {{repoUrl}} available in the template for all input files to DEFAULT except for input files in ./input/foo/. For ./input/foo/* and all subdirectories, repoUrl would be set to MORE SPECIFIC.

If any markdown file in ./input/foo/ defines a metadata value called repoUrl, then that value will override the value from meta.json.

API

• .resolveArgs(argv): given a hash containing command line args, returns the fully resolved arguments. This does two things: it takes care of relative paths and loads the modules passed via highlight-* so that they can be invoked as functions when highlighting a specific language.
• .render(argv, onDone): given a hash of resolved arguments, it processes every file just like the command line tool; this includes copying files.
• .pipeline(argv): given a hash of resolved arguments, it returns a writable object mode stream that accepts objects with the following keys:
  • path (an absolute path to the input file name),
  • stat (the fs.stat object associated with the input file),
  • contents (a string with the content of the input file).
• Since v3.1.3, the pipeline function supports a couple of arguments that are not exposed on the CLI (in addition to all the CLI args):
  • meta: a hash of JSON (the contents of a meta.json file if you prefer to set that explicitly)
  • asset-path: a full path to the /assets folder, defaults to ${output}/assets.

The writable stream returns objects with the same properties, plus any metadata. The pipeline updates path to be the output path that generate-md would write the file to, and updates contents to be a string of HTML.

To plug the equivalent of generate-md into your grunt/gulp etc. task, use the following code:

var mds = require('markdown-styles'),
    path = require('path');

mds.render(mds.resolveArgs({
  input: path.normalize(process.cwd() + '/input'),
  output: path.normalize(process.cwd() + '/output'),
  layout: path.normalize(process.cwd() + '/my-layout'),
}), function() {
  console.log('All done!');
});

See bin/generate-md and test/api.test.js for details.

Acknowledgments

I'd like to thank the following people for contributing new features:

• @mixinmax for adding default class names to the table of contents
• @parmentelat for adding the cascading meta.json logic
• @AaronJan for contributing a patch that adds support for Windows
• @joebain for a fix related to using markdown-styles with grunt
• @xcv58 for dealing with the case where the same header text is used multiple times in the same file
• @iamdoron for contributing the initial implementation of the Handlebars templating integration

I'd like to thank the following people for making CSS stylesheets available with a permissive open source license:

• the witex style is based on AndrewBelt/WiTeX
• the github style is based on sindresorhus/github-markdown-css
• the bootstrap3 style was contributed by @MrJuliuss
• 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!)

Screenshots of the layouts

Thanks to electroshot, the screenshots now look about right (e.g. web fonts render correctly).

github

witex

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

bootstrap3

Contributing new styles to markdown-styles

Add new layouts to ./layouts/name. To regenerate the pages, you need to run:

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

If you have phantomjs installed, run:

make phantomjs

which will use a phantomjs script to capture the screenshots.

markdown-styles's Issues

Hide render console message?

I want to hide 'console.log('Copy asset file', filename, '=>', target);' message in the shell, may I have an extra parameter to hide? Or have another method to render

Sometimes I print the messages to confirm it works and sometimes I also need it not to print for a report. :)

code: https://github.com/mixu/markdown-styles/blob/master/lib/render.js

how to highlight another language

I have a simple DSL, very C like, but it has its own keywords and pre-defined functions, how can I syntax highlighting them?

thanks

Markdown files with UTF8 with BOM can lead to incorrect renedering

I had some files encoded as UTF8 with BOM and my heading # Heading was not converted to h1.

Changing the encoding o UTF8 w/ BOM fixed it for me.

Provide attribution.

Thank you.

File contents deleted

I ran this rather naively today in a directory and noticed it copying non-markdown files to themselves, which seemed odd, so I hit CTRL+C to stop and take a look. It had deleted the contents of all files it had a chance to access before I stopped it with CTRL+C and left them with 0 filesize. Luckily the files were checked into git and I was able to retrieve them with a quick reset, but this seems like a rather scary issue.

The command I ran was:

generate-md --input . --output . --style github

The current directory had a few markdown files to convert, but subdirectories underneath had code files.

Entirely possible that I read the documentation incorrectly. In general though you probably don't want to modify existing files in the --input directory or any of its subdirectories.

Unwanted comma concatenated on highlight

When running more than one highlight command the style tag blocks are separated with unwanted comma within the generated HTML output

I coded my custom highlight module that exported the css:

module.exports.css = function() {
    return '<style>' + require("fs").readFileSync(__dirname + '/override.css') + '</style>';
};

I added my custom highlight to the cmd:
generate-md --layout mixu-page --input ./core --output ./core/ --highlight-hljs mds-hljs --highlight-cathl ./cathl.js

In the HTML output I got the first mds-hljs style tag block and after that my custom style tag block but separated with unwanted comma.

EJS is not working in Markdown files

Hello!

Thank you for this great library!

However, I'm trying to use EJS in my Markdown files, but it's not working. The EJS code is not processed at all, it's just outputted to the resulted HTML file as is.

I've exported github layout and trying to add some partials to it in order to reuse them later, but I can't include partial to the Markdown file.

Here's my index.md:

{{> mypartial }}

It is rendered as <p>{{> mypartial }}</p> in HTML.

And the partial is located here: /src/layout/partials/mypartial.html. It's also not clear from the documentation what extension to use for the partial file: .html or .ejs. I've tried both with the same results.

Any suggestions will be highly appreciated. Thanks!

Lack of license

The code is lack of license

Config

Is there any way to set up parameters I want to be used anytime I just run generate-md in project root folder?

Each time writting --input, --output etc is not the best option.

using meta.json

Hi there

First off, many thanks for putting this together ! Looks like a really cool idea and I got my micro website up and running in an eye blink :)

I'm at the point where I'd need to leverage this meta.json business.
It first took me some time to figure I had to install it inside the input/ directory
after I instrumented the code I can see now that my file is read all right, but the corresponding {{foo}} replacements do not take place, and I am trying to figure out what it is that I do wrong

I guess there is some confusion in my mind as to what is expected in that dictionary. The doc at https://github.com/mixu/markdown-styles#metajson explains how to define variable repoUrl for files under input/foo; what about files at the toplevel right in input/ ?

I have tried various tricks for defining 'bar' like
{
"" : { 'bar' : 'value'},
"." : { 'bar' : 'value'},
'bar' : 'value',
'input' : { 'bar' : 'value'},
}

but apparently to no avail, the occurrences of {{bar}} all come up empty;
I can feel there is something I do just wrong but I can't spot it, can you please help ?

---

Besides, given this scoping mechanism, I would fancy there should be a means to define a given variable at different levels of the filesystem tree, with the most precise (the longest prefix) taking precedence, is it the case right now ?
I have net yet taken the step of splitting my inputs into subdirs, but if that feature was working as I describe I might go down this road later on.

Thanks again in any case

.md partials or how to build TOC for whole project

I have toc.md in src root and some basic CSS custom styles which generates nested numbering for <ol> and would like to use this table of contents in sidebar in all other pages, however, as I can see only html files in layout partials folder can be used and not .md files in src.

Is there any way right now in one .md file insert another .md file and in layout's page.html include multiple md files? If not, what would be your suggestions, short algorithm, how I would make it myself using your tool?

Or may be you have another option to automatically build toc for whole project from all .md files?

P.S. thank you for this simple and great tool. It is closest to what I was looking looking for, simple to install and use out of the box with GitHub syntax highlighting support for most languages. Probably you also started making this tool because didn't find any simple ones. If you need some help in contributing, give me some guidelines about used technologies and architecture. I see there are many features and imporvmenets could be made. You also may contact me on twitter

`Could not parse metadata from` by adding 3+ dashes

If I add this with not render:

This is where is goes wrong

---

This will not work {{path}}

Metadata handling weirdo

I have this in my index.md:

title: "some title"
version: "2.0.0"
authors: "xy"
locationref: "place"

---
# my markdown
positive

My template like this:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, minimal-ui">
    <title>{{title}}</title>
    <link type="text/css" rel="stylesheet" href="{{asset 'css/github-markdown.css'}}">
    <link type="text/css" rel="stylesheet" href="{{asset 'css/pilcrow.css'}}">
    <link type="text/css" rel="stylesheet" href="{{asset 'css/hljs-github.min.css'}}"/>
  </head>
  <body>
    <article class="markdown-body">
      {{title}}
      {{version}}
      {{authors}}
      {{locationref}}
      {{~> content}}
    </article>
  </body>
</html>

Rendered html like this:

<!doctype html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1, minimal-ui">
    <title>locationref: &quot;place&quot;</title>
    <link type="text/css" rel="stylesheet" href="assets/css/github-markdown.css">
    <link type="text/css" rel="stylesheet" href="assets/css/pilcrow.css">
    <link type="text/css" rel="stylesheet" href="assets/css/hljs-github.min.css"/>
  </head>
  <body>
    <article class="markdown-body">
      locationref: &quot;place&quot;


      <p>title: &quot;some title&quot;
version: &quot;2.0.0&quot;
authors: &quot;xy&quot;</p>
<h2 id="locationref-place-"><a class="header-link" href="#locationref-place-"></a>locationref: &quot;place&quot;</h2>
<h1 id="my-markdown"><a class="header-link" href="#my-markdown"></a>my markdown</h1>
<p>positive</p>
    </article>
  </body>
</html>

It seems I'm not getting the idea of embedded metadata on the page. I tried also JSON format, but it did not care about it at all, but inserted it directly into the html.

Asset helper produces backslashes in Windows

This line in my layout template:
<link href="{{asset 'css/bootstrap.min.css'}}" rel="stylesheet">
Becomes this when generate-md is used on Windows:
<link href="..\assets/css/bootstrap.min.css" rel="stylesheet">

Shouldn't URLs always use forward slash?
Culprit seems to be lib/set-output-path.js

Feature request -> Input file without folder

I would like to be able to generate html based on one file without putting it in a input folder.

Relative URLs to other markdown files

GitHub has [somewhat] recently started supporting relative URLs to other MD files. This is awesome on GitHub, but painful elsewhere because those links aren't usually fixed up in the converted HTML. It'd be awesome if there was a way for generate-md to support fixing up relative links to files in the input folder to the converted file in the output folder.

Generated HTML has self-closing tags

Just noticed my <head> contained

<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<link type="text/css" rel="stylesheet" href="assets/style.css" />
<link type="text/css" rel="stylesheet" href="assets/pilcrow.css" />
<link type="text/css" rel="stylesheet" href="assets/hljs-github.min.css"/>

Erm... pretty sure self-closing tags are poor html practice.

Can we disable the generation of self-closing tags?

Can not resolve the Chinese title！

Chinese title will be resolved as "-"

Links to internal anchors (or implicit anchors) cause error

In convert-md.js, when the renderer.link function is called on a link that looks like this:

1. [Connections](#connections)

Its call to url.parse produces something like this (assigned to parsed):

{
  protocol: null,
  slashes: null,
  auth: null,
  host: null,
  port: null,
  hostname: null,
  hash: '#connections',
  search: null,
  query: null,
  pathname: null,
  path: null,
  href: '#connections'
}

parsed.pathname is then passed to path.extname which fails with the following because pathname is null.

TypeError: Path must be a string. Received null

I use links like that to link to the implicit anchors provided by the ids generated for heading elements. Changing line 58 to...

if (!parsed.protocol && parsed.pathname) {

...fixes the problem. Not sure if that's more shotgun than you'd want, though.

Help please for any feature to highlight some lines of code ?

Like this will produce,

Is it possible ?

$" will be parsed to {{content}}quot;

Markdown

This is a Test: $"

Expected result

This is a Test: $"

Actual result

This is a Test: {{content}}quot;

tables look unreadble in the default mixu-bootstrap-2col layout

When using mixu-bootstrap-2col (which otherwise is a very good layout), the tables output looks extremely unreadable. By adding the following lines (taken from the github layout) to the style.css, I was able to resolve it:

table {
  display: block;
  width: 100%;
  overflow: auto;
  word-break: normal;
  word-break: keep-all;
}

table th {
  font-weight: bold;
}

table th,
table td {
  padding: 6px 13px;
  border: 1px solid #ddd;
}

table tr {
  background-color: #fff;
  border-top: 1px solid #ccc;
}

table tr:nth-child(2n) {
  background-color: #f8f8f8;
}

Enhancement ideas

First, thanks for this tool. I've been trying to create a portfolio and i stumbled upon this after fighting with premade templates, bootstrap & co.

I've been customizing a theme of mine and the more i worked on this the more i thought it would be cool to give a bit more power to the meta.json.

I'll give a few of the ideas i got, more as a todo list that anything if i find the time, but also in the case someone want to have an eye on this.

Parsing the css looking for meta.json variables
It would be great to give the layout user a way to customize a few things without diving into the css itself (or the layout folder).

e.g. "background" : "red" and using a background-color : {{background}} in the css.

Allowing a default meta.json in the layout folder
In my theme i use the meta.json to set my profile image and a few contact links. If i can give a default meta.json in my theme and if it's copied into the markdown project itself it would be easier for a user to understand what's possible to do with the theme.

Adding an if operator
Maybe, by design, you want to keep things simple and i like the idea that a layout doesn't need more than just the default command without necesarily looking into the meta.json - but a {{if variable equals value}} and/or {{if variable exists}} would allow for a more dynamic theme without requiring the user to edit/add anything into the meta file. It would be possible to create more powerful themes as well. In my theme above i have a {{github}}, {{twitter}} and {{email}} variable which are links associated to the little icons but i can't hide them depending on if the variable exists or not.

e.g. {{if github exists}} <a href="{{github}}">My github repo</a>{{endif}}

Adding a sample command
Since my two last points are not entirely compatible a --sample command would create a dummy project with a default meta.json showing all the features the theme can offer. A normal markdown parsing would still work giving the simple version of the theme. (without the profile image and the contact links in mine)

Add support for maths mode?

Can I render expressions like

$$
f(x)=\int_a^b\cos x\, dx
$$

using generate-md?

Add viewport to all layouts

The github layout already have this.
I suggest that add viewport to all layouts:

  <meta name="viewport" content="width=device-width, initial-scale=1.0">

So that all layout can be responsive.

About Metadata Definition

Awesome work on this project. I love it.

I downloaded the project yesterday and spent a few hours trying to make a few things work for me. So, I would like to make a couple of recommendations to improve documentation in the following precise aspects:

About the meta.json file

The documentation explains how to set a simple property, but does not deal with nested directories. In my case I have distributed my markdown files in multiple nested directories. So, showing an example like this might be really useful:

{
    "foo/bar": {
        "title": "Welcome to FooBar!",
    }
}

This would make the title property available within the templates inside foo/bar directory.

About Highlighting Support

The documentation in the official website is slightly different than that provided in Github.

This latter seems a bit better, but yet, no clear enough about how to enable syntax highlight. Perhaps having a couple of examples of really simple templates in the Github repository would be awesome.

I am not sure if I did right, but I managed to make it work.

I cloned one of the layouts I liked under a different name, and edited the page.html file to include the hightlight.js library and a theme.

<link rel="stylesheet" href="{{assetsRelative}}/css/{{theme}}.css">
<script type="text/javascript" src="{{assetsRelative}}/js/highlight.pack.js"></script>
<script>hljs.initHighlightingOnLoad();</script>

And since the theme is a variable here, I configure it in my meta.json file.

{
    "foo/bar": {
        "title": "Welcome to Foo Bar!",
        "theme": "googlecode"
    }
}

I also copied all highligh.js themes into my layout assets directory and also copied there the highlight.pack.js file I downloaded from the Highlight.js Website

I also had to remove the {{styles}} tag from the template to avoid these styles overwrite those from highlight.js.

Finally, I ended up running the generate-md command as specified in the Github site, and not as specified in the official website.

./node_modules/.bin/generate-md --highlight mds-hljs --layout customized --input ./input

I am not even sure if this is the right way to do it, but if not it would be awesome to have a few examples of how to do it right to guide users like me.

Thanks for the great tool.

Incorrect Parsing of SML Code

I was writing an article yesterday in markdown and then I tried to convert it to an html page using your tool and I found a bug.

The following is a piece of code I wrote:

fun get_all_even_snd xs = filter((fn (_,v) => v mod 2 = 0), xs)

This is incorrectly parsed as:

fun getall_even_snd xs = filter((fn (,v) => v mod 2 = 0), xs)

You can see that the _ (underscore) character was misinterpreted.

Can't find generate-md command

I run the following:

sudo npm install -g markdown-styles

and then, run the following:

generate-md --layout

the terminal show:

-bash: generate-md: command not found

My computer is MacBook Pro with OSX10.11

Differentiating between different headers (h1, h2, h3, etc)

Is there a way to differentiate between the different headings so that I have can smaller headers indented in the sidebar via css? Right now all headings render to an anchor in a list item for the sidebar. Would it be possible to add a unique class to each type of header so that they can be styled?

If no one has time to do this, I can make the change as long as someone points me in the right direction.

Metadata in the actual MD files

Introduction

Hi There

I am not sure if this is intended (so by design) or rather a bug. For now I have been using my custom meta data tags in my own defined layout.

Working usage

For example I have a partial header.html like

<div>
    <a href="{{myExternalLink}}">CLICK HERE</a>
</div>

My meta.json looks like

{
  "*": {
    "myExternalLink": "http://www.helloworld.com",
    "myName" : "Ian"
  }
}

This works fine as expected.

Issue

Now I would like to have within my MD file, my meta data tag myName. So if I look at my file index.md:

    Some random text, but this was written by {{myName}}

When I compile/parse now my index.md file, my value is not prefilled. It is just treated like the simple text "{{myName}}".

Question

So now my question is, was this the intention ? So that you can only use meta data tags in your html files from your layout and not within the MD files that contain the actual content. For me this is not totally clear from the documentation but it seems to work like that. If this is the expected behavior then case closed and I will live with it :)

Or can I try to resolve this using helpers or anything like that.

Foot Note

This myName meta data tag is just an example, I know with ghost render I can do more of a blog approach and such meta as author are present (if I am not mistaken). So just wanted to point it is just a fictive example.

github style: Bold not preserved with code

Hiya.. minor style suggestion.. to preserve bold in this case: **`myFunction()`**

Currently, in the github style, the full font specification for code is overriding the bold. Suggest to use family specifically, to preserve bold when applied. Suggest to change lines 195-197 of github-markdown.css from

.markdown-body code {
  font: 12px Consolas, "Liberation Mono", Menlo, Courier, monospace;
}

to

.markdown-body code {
  font-family: Consolas, "Liberation Mono", Menlo, Courier, monospace;
}

I also removed the overriding size here because the size is already set to 85% on line 421. And, that's good because if you were to have a ## `MonospacedHeading` you wouldn't want a fixed 14px size anyway. 😸

Not working on win7/64bit

I have tried using cli commands in example and it does not generate any .html file?

Question/feature request

I would like to use this tool to generate a static documentation site. I have a bunch of md-files in a folder:

file1.md
file2.md
...
...

Now I execute generate-md and get the corresponding site:

assets/
file1.html
file2.html
...
...

It would be really nice if the tool could generate an index page for me so that I don't have to maintain links from a landing page to all sub pages. Is this possible? Could it be possible to extend this tool to do this?

"include" feature

First, thanks for markdown-styles. It is a very nice tool, stands out as a high quality choice even among the (at least) hundreds of static site generator tools. A feature request though:

Currently there appears to be no way to include one markdown file in another. That is a very common and frequently useful feature in static site generation. Issue #37 asks for something close to this, but it seemed worth having an issue dedicated to just this specific feature.

GitHub style ignores “text” code block formatting

From what I understand, if I just use a code block without specifying the language, GitHub style attempts to guess the language and apply appropriate syntax highlighting.

[1, 2, 3, 4]

To avoid that and present raw text without highlighting, a “text” keyword exists.

[1, 2, 3, 4]

But whenever I use this option I always get the same formatting as if I didn’t use it.

EDIT: After publishing this issue it seems that even GitHub doesn’t highlight anything in this snippet while the script does.

Same titles need different id

For example:
https://maybe.xcv58.me/README.html

There're three POST as titles, they should be

<h3 id="post"><a class="header-link" href="#post"></a>POST</h3>

<h3 id="post-1"><a class="header-link" href="#post"></a>POST</h3>

and

<h3 id="post-2"><a class="header-link" href="#post"></a>POST</h3>

The same README.md in GitHub doesn't have such issue:
https://github.com/xcv58/backend/blob/meteor/README.md

Could you solve this issue?
If no, could you please tell me which function do the conversion of markdown to html? I can try to solve this.

Thanks!

Error: Cannot find module 'yargs'

I used npm first but failed. It said "In most cases you or one of your dependencies are requesting a package version that doesn't exist. It was specified as a dependency of 'miniq'." I tried to install miniq and failed either.
So I turn to building it by myself, however it said as the title shows... : (
Help, please!

Can you provie an example of how to use markdown-styles with gulp?

Links and special characters

When using special characters in headings, links to the heading don't work.

Including :
[ ] ! ( ) :

In markdown, the code below navigates to the heading

 [Two way binding [(ngModel)]](#two-way-binding-ngmodel)

## Two way binding [(ngModel)]

but when converted to html, the link doesn't work

<a href="#two-way-binding-ngmodel">Two way binding [(ngModel)]</a>

<h2 id="two-way-binding-[(ngmodel)]"><a class="header-link" href="#two-way-binding-[(ngmodel)]"></a>Two way binding [(ngModel)]</h2>

Programmatic usage?

Hi, is there a programmatic API?

I generate my markdown docs using gulp, and your library seems perfect for giving them a little colour. But spawning command line programs is against the spirit of gulp.

I'd be happy to write a gulp plugin for your library when I have some time – if you document the programmatic API.

Different color of same format

I found a strange issue. Same format cause different font-colors, like this:

They have same indentation.

Output only a html file ?

It would be nice to have an option on the generate-md command to have only one html output file with css styles packed in.

The css files should be concatenated and put it in a <style> tag in the header of the html file.

This allows to have only one file as output (if all the assets are css files, which is often the case).

How to disable syntax highlighting by default

I am using .md's and markdown-styles to document my own language and am wanting no specified language on the ``` to produce no syntax highlighting what so ever. I am getting what appears to be randomized highlighting on random words. How do I go about disabling highlighting on the case of no specified language on the language blocks. Should this not be the default case anyway ?

For example of random highlighting occuring :-

I would still like to be able to use the ```js for example, but want normal code blocks to be unhighlighted the same as I am getting in GitHub.

generate-md fails when input is inside user's Documents directory on Windows 7

I got the same issue as dart-atom/dart#402 when trying to use a .md file which sits in my Documents directory: Error: EPERM: operation not permitted, scandir 'C:\Users\THauk\Documents\My Music'

Wrong separator when copying non-markdown files

Problem: Asset folders, pictures and other non-markdown files are not copied due to the input path formed with wrong file separator

See problem in this message when copying for example assets:

Copy non-markdown files C:\development\doc_generation\my-custom-skin\assets/\css\my-custom.css => C:\development\doc_generation\static\docs\assets\css\my-custom.css

Problem separator is added by the generation code and is between the assets and css, it should be assets\css not assets/\css like in ouput.

Command used to generate this: generate-md --layout my-custom-skin --input .\docs --output .\static\docs

Operating system Windows

Current project status

Hi, what is the current status of this project? Is it still maintained?

How can I write some custom-style base on the generate-html file?

It is recommended that you can include an empty custom-style.css that somebody can write some custom-style in the assets/css/custom-style.css.

Question mark(?) is replaced by hyphen(-) in the header links in the conversion process

Hi,

Firstly, thanks for this awesome tool!

I am facing an issue with header links, when the markdown(.md) files are converted into HTML, the question(?) mark in the header links is replaced with a hyphen(-). This is causing problem for me since, I am using DocToc to create a Table of Contents for the document and the DocToc, removes question mark while generating links inside Table of Contents.

As per my understanding, this is happening due to the following line in renderer.heading function inside markdown-styles/lib/convert-md.js file.

var id = this.options.headerPrefix + raw.trim().toLowerCase().replace(/[^\w]+/g, '-');

Is there a way to configure markdown-styles to simply remove any special character like question(?) mark when header links are generated.

Though, I am not sure whether this is intended or a bug. Any help would be highly appreciated!

Option to ignore unknown files

Hi!

I've upgraded markdown-styles and noticed that it copy unknown files to output.

Perhaps some option to ignore unknown files could be added?

Change output html filename?

Hello, @mixu. First of all, thank you for a great CLI md-to-html tool.

I've been using it for quite a while, and I have a question - is there any way of naming the output html differently via CLI commands?

Wouldn't it be a good addition if there isn't any now?