Skip to content
This repository was archived by the owner on Aug 20, 2024. It is now read-only.

Conversation

Cleecanth
Copy link

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 added 3 commits July 17, 2015 10:19
Fixes issue where highlight.js incorrectly guesses the wrong language
Made starting template.html a better initial experience by adding
expected tags.

* Added `html`, `head`, `meta`, and `body` tags.
* HTML5 doctype included.
* Wrapped markup examples in `code` tags, allowing for more accurate
examples.
* pre > code styles added to allow overflow scrolling.
Exposing the marked node-module options to the user but enforcing
custom renderer.
@Cleecanth
Copy link
Author

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
Copy link
Owner

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
Copy link
Owner

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

Cleecanth added 4 commits July 20, 2015 17:50
This rolls back to commit c59de37.
Moved scripts to the end of template
@LibbyJane
Copy link

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!

Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants