About Metadata Definition

[edalorzo]

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.

[mixu]

Thanks for the feedback! I agree that getting the syntax highlighting to work is a bit too complicated as it stands. The way you've done it is correct, but I need to update the documentation to be more in line with this or preferably just make things easier by including a syntax highlighting template and the necessary markup with the base themes.

As for metadata management, I'll probably move towards more header-based metadata, like I did with my latest project - ghost-render - take a look if you have the time, the killer feature is compatibility with themes written for the Ghost blogging platform. I'll probably backport a bunch of the functionality from that repo into markdown-styles once I have some time.

[mixu]

Hi @edalorzo,

I've now finally addressed all of these issues with the new v2.0 release:

• the metadata inclusion mechanism has been documented in more detail
• you can also add metadata directly into the input markdown files
• highlight.js is now enabled by default
• every builtin theme ships with a highlight.js theme by default

Thanks again for filing the issue, and hope the v2.0 release meets your needs a bit better.

[edalorzo]

@mixu Awesome. I'll take a look over the week. Thanks a million!