emiloberg/markdown-styleguide-generator

Will search all your (s)css files for comments and generate a single page html styleguide

markdown-styleguide-generator's Issues

Grunt?

How would you set this up in grunt?

Wrong Syntax Highlight applied

Hi y'all. Great lib and I'm loving it. Thanks for your work.

I have a small problem with some Syntax Highlighting not rendering text properly.

Here's a picture of what is rendered:

See how the text inside the code is rendered all different colors? And I would expect the H1 tag itself to not be white, similar to the Div.

Here's the SCSS and the comment that's generating this:

/* SG
# Content/Header

Creates a reversed section in a dark shade of the primary color
```
<div class="dyna-header">
  <h1>This is the header</h1>
  Some text in the header
</div>
```
*/
.dyna-header {
  text-align: center;
  padding: 20px;
  font-weight: 100;
  h1 {
    font-weight: 100;
    margin: 0 0 0.2em;
  }
}

Here is the contents of my .styleguide file. I have doctored it to use relative paths that reference a project above the doc project's root. Also to reference my local highlight.js and vs theme.

{
	"sgComment": "SG",
	"srcFolder": "..\\framework\\framework\\styles",
	"outputFile": ".\\src\\generated\\styleguide\\styleguide.html",
	"templateFile": ".\\node_modules\\markdown-styleguide-generator\\template\\template.html",
	"themeFile": ".\\node_modules\\markdown-styleguide-generator\\template\\theme.css",
	"highlightFolder": ".\\node_modules\\highlight.js\\styles",
	"highlightStyle": "vs",
	"excludeDirs": [
		"target",
		"node_modules"
	],
	"fileExtensions": {
		"scss": true,
		"sass": false,
		"css": false,
		"less": false
	},
	"walkerOptions": {
		"followLinks": false
	},
	"jqFile": ".\\node_modules\\markdown-styleguide-generator\\template\\jquery.js"
}

Here's the relevant lines from my package.json

  "dependencies": {
    "highlight.js": "^8.9.1",
    "markdown-styleguide-generator": "^2.0.4"
  }

Appreciate any help you could provide! 🍺

Is this project maintained?

This generator is quite nice and I would like to use this in my professional projects, but there are a few rough edges that need to be addressed for it to work well in those projects:

• At the moment there can only be one code block per SG comment, which is too limiting for how we can format our code samples.
• The tool doesn't allow for configuration to be defined in custom locations / with custom file names.
• The CLI is overly verbose - there should be a way to run it without having every single file listed.

I am more than happy to make PRs for all of those, but this is only worthwhile if there is a willingness to merge them. If not (and that's perfectly ok! 🙂 ), I'll just make my own fork with those changes.

Comments Output Twice

Hi! Nice plugin! I seem to be having an issue where the comment is being spit out twice. This is via the normal build running "styleguide" in terminal. Folder setup is simple, too. Just a sass and css folder. Running Node v 6.10.1 on OS X 10.11.5

Thanks in advance!

Not taking CSS after comment out

Hello,

First of all thank you so much for creating this beautiful style guide. I've followed your guidelines and created my own theme. However, I'm facing this issue with the CSS. Within a style guide comment, you have mentioned the css goes after */. Being said that I've implemented the following css code after the close css comment, but the styleguide doesn't reflect its css.

This is how it renders without CSS

when I add the following css like this...

<a href="mailto:[email protected]" class="btn btn-theme apply-mob-btn">Apply</a>

*/

.btn-theme {
background-color: #00796B;
font: 400 30px/32px robotoregular,sans-serif;
-moz-border-radius: 5px;
-webkit-border-radius: 5px;
border-radius: 5px;
-moz-box-shadow: #044f42 0 4px 0;
-webkit-box-shadow: #044f42 0 4px 0;
box-shadow: #044f42 0 4px 0;
min-width: 398px;
text-decoration:none;
padding: 17px 15px;
-webkit-transition: all .5s ease 0s;
-moz-transition: all .5s ease 0s;
-ms-transition: all .5s ease 0s;
-o-transition: all .5s ease 0s;
transition: all .5s ease 0s;
}

Please let me know how to fix this! Thanks a ton.

Not including styles.

I'm sure this is me doing something wrong, but the styles aren't rendering. The glyphs not showing up doesn't surprise me, the rest does though.

Here's a screenshot

Any help would be splendid :)

Demo

Is an online demo of the styleguide available please?

Feature request: ability to run w/o installing globally

This tool looks very promising, but documentation says I have to install it globally (npm install -g markdown-styleguide-generator). I would like to be able to distribute this across my team without making them do any special setup beyond npm install in our CSS package.

I have tried to make it work with an npm install local to the package, but I can't get it to run. Is there a way to make this happen? If so, can you document it? If not, why not?

Having multiple code examples on the same chapter

In the screenshot I noticed the pagination chapter in the styleguide contained two sections (Pagination and Pagination/alignment). I wonder what markup is needed to achieve this.

Till now i've only been able to have one code example per chapter. Would appreciate your help. Thanks in advance.

Custom handlebars variables

First, I just want to thank you. This is exactly what I was looking for (and came unbelievably close to trying to create on my own). So, thank you for this — you've saved me numerous hours and answered like 30 of my prayers.

That said, it would be nice to be able to define custom handlebars variables within the .styleguide file for use within the template.html.

As a very simple example, within the .styleguide, if you could do something like:

{
  //...config stuff
  "customVars": {
    "externalJs": "/my/script.js",
    "pageTitle" : "My Project Style Guide"
  }
}

and in template.html:

<title>{{customVars.pageTitle}}</title>
{{#if customVars.externalJS}}
  <script src="{{customVars.externalJs}}">
{{/if}}

You could obviously do a whole lot more. But the general idea is that you'd be making your template more portable (for use across projects).

question

Is there a demo page to play with, and how might one plug this into gulp?

Thanks

node_modules/highlight.js is installed in parent folder not under markdown-styleguide-generator/node_modules

when we install markdown-styleguide-generator its dependency (highlight.js) install on project node_modules but file which is generated by styleguide init contains highlightFolder path project/node_modules/markdown-styleguide-generator/node_modules/markdown-styleguide-generator/node_modules/highlight.js/styles and it throws error while executing styleguide with below message.

Could not read highlight file: {project path}/node_modules/markdown-styleguide-generator/node_modules/highlight.js/styles/github.css

Using npm 3.x

Looks like npm 2.x installs the dependency different compare to 3.x