Make initial setup simpler

Cleecanth commented 9 years ago

It makes sense to give this a sort of boilerplate treatment, so here's some things that should help:

Giving the base template standard html tags. Without them it is a little confusing after the first run of the generator. Considering how abstracted the process of this generator is (going from comments in markdown to JSON, to Handlebars templates, to HTML), and the fact that browsers automatically insert html, head, and body tags, it's not initially clear where that extra markup is coming from. When someone wants to include a link to their site's CSS, having a <head> makes this much more clear.
Moving the JS script to the bottom of the document is also standard practice, so why not.
Code example semantics should be

<pre><code> ... </code></pre>

...which also allows for horizontal scrolling on very long lines of code.

Cleecanth commented 9 years ago

Upon reviewing the readme of this project, this may go against the initial intention — html that you can copy into a cms WITHIN your site rather than being a standalone file.

I'll leave it up to you @emiloberg if you want to merge this change or not. I've found it useful to keep this style guide as a static, self-contained file, but that's just my use-case.

emiloberg commented 9 years ago

Really nice @Cleecanth!

Commit 84f2638 and c78ed92 are great. I'll gratefully accept them.

About the initial template (84f2638). Yeah my initial intention for this small tool is generate a style guide which lives within the cms/site/like. There are a bunch of tools which generates stand alone style guides (styledown being one which this project has drawn a lot of inspiration from).

Thing is, even if you include full html (<html>, <body> etc) you'll still need to insert a link to you css, right? So you'd still need to modify the template. Am I understanding you correctly if I say that you're saying it's easier to understand where you need to insert your css <link> if you've the full html structure?

As it goes against the intentions of the tool I don't really want to include it in the standard template. One way to go about it could be to include a template.full.html and let the template file be user configurable? But still let the partial html file be the default one, as that's where this tool is unique to other generators.

I propose this: If you want to, revert commit c59de37 (but feel very free to re-add the pre styling and javascript-at-end-of-file stuff) and I'll merge it as is. And if we come to any smart conclusions about the html file thing we handle that separate.

Again: Nice work! Thanks!

emiloberg commented 9 years ago

(I'll be out away from internet for a couple of days but I'll get back to you as soon as possible)

LibbyJane commented 7 years ago

This PR was really helpful for me just to have a better understanding of how everything works, so thank you anyway even if it's not merged!

emiloberg / markdown-styleguide-generator

Make initial setup simpler #6