From 84f2638c2fec1a71dd4ac29384aef3a2eb23346f Mon Sep 17 00:00:00 2001 From: Cleecanth Date: Fri, 17 Jul 2015 10:19:09 -0500 Subject: [PATCH 1/7] Force html highlighting Fixes issue where highlight.js incorrectly guesses the wrong language --- index.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.js b/index.js index dd50fbd..8e11860 100644 --- a/index.js +++ b/index.js @@ -279,7 +279,7 @@ function convertHTMLtoJSON(html) { curSectionData.code = $section(this).html().replace(/^\s+|\s+$/g, ''); }); - curSectionData.markup = hl.highlightAuto(curSectionData.code).value; + curSectionData.markup = hl.highlight("html", curSectionData.code).value; curSectionData.id = makeUrlSafe(curSectionData.section + '-' + curSectionData.heading); $section('h1.main-section-' + sgUniqueIdentifier).remove(); From c59de37b20a963d73e5f933bc992581fc5ca8b11 Mon Sep 17 00:00:00 2001 From: Cleecanth Date: Fri, 17 Jul 2015 10:38:14 -0500 Subject: [PATCH 2/7] Improve initial template 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. --- template/template.html | 164 +++++++++++++++++++++-------------------- template/theme.css | 18 ++++- 2 files changed, 101 insertions(+), 81 deletions(-) diff --git a/template/template.html b/template/template.html index 8b0e2c0..da47b52 100644 --- a/template/template.html +++ b/template/template.html @@ -1,87 +1,95 @@ -{{> theme}} -{{> highlight}} -{{> jquery}} + + + + + + + + StyleGuide + {{> theme}} + {{> highlight}} + + +
+
    + {{#each menu}} +
  • + {{#if headings.0.name}} + {{name}} + + {{/if}} + {{#unless headings.0.name}} + {{name}} + {{/unless}} +
  • + {{/each}} +
+
- + {{#if code}} +
+ {{{code}}} +
+ {{/if}} -
-
    - {{#each menu}} -
  • - {{#if headings.0.name}} - {{name}} - - {{/if}} - {{#unless headings.0.name}} - {{name}} - {{/unless}} -
  • - {{/each}} -
-
+ {{#if markup}} +
+
{{{markup}}}
+
+ {{/if}} -
- {{#each sections}} -
+
+ {{/each}} +
+ {{> jquery}} + + + diff --git a/template/theme.css b/template/theme.css index e96dd6f..9b3f153 100644 --- a/template/theme.css +++ b/template/theme.css @@ -11,7 +11,7 @@ box-shadow: 2px 2px 5px 0px rgba(50, 50, 50, 0.43); } -#styleguide .result, +#styleguide .result, #styleguide .comment { padding: 1em; border: 1px solid #ddd; @@ -33,7 +33,20 @@ #styleguide .markup { border: 1px solid #ddd; - border-top: none; + border-top: none; +} + +#styleguide .markup pre { + overflow: auto; + padding: 0; + width: 100%; +} + +#styleguide .markup code { + display: block; + word-wrap: normal; + white-space: pre; + padding: 1em; } #styleguide code, @@ -120,4 +133,3 @@ #styleguide-menu a.on { background-color: rgba(0, 0, 0, 0.1); } - From c78ed926fc0e69d3e3edf64ffb1b43adf8082a25 Mon Sep 17 00:00:00 2001 From: Cleecanth Date: Fri, 17 Jul 2015 11:23:09 -0500 Subject: [PATCH 3/7] Add marked options Exposing the marked node-module options to the user but enforcing custom renderer. --- README.md | 70 ++++++++++++++++++++++++++++++------------------------- index.js | 13 +++++++---- 2 files changed, 47 insertions(+), 36 deletions(-) diff --git a/README.md b/README.md index 90866b7..230b7c1 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ In contrast to other style guide generators, this tool generates **a single file Style guides generated by this tool do not contain any css style! -The style guide simply contains HTML markup exemplifying how to use your css rules. That means that the generated html file will not do any good on it's own. Instead the intended use is to upload the generated HTML to your site where it will inherit your site's css. This also means that if you change your css - the look of the styleguide will change aswell. This way **the styleguide will always tell the truth**. +The style guide simply contains HTML markup exemplifying how to use your css rules. That means that the generated html file will not do any good on it's own. Instead the intended use is to upload the generated HTML to your site where it will inherit your site's css. This also means that if you change your css - the look of the styleguide will change aswell. This way **the styleguide will always tell the truth**. If you're using a CMS(-like system), this usually means that you create an article somewhere only accessible by developers and paste the content of the generated html file into that article (usually you'll have a `source` mode in your article editor). @@ -77,7 +77,7 @@ Example:

``` */ - + a [class^="icon-"], a [class*=" icon-"] { text-decoration: none; @@ -106,7 +106,7 @@ This will be rendered as: * ??? * profit -## Syntax +## Syntax Best described by going through the example above line by line. ##### Line 1 @@ -130,8 +130,8 @@ Every style guide comment **must** have a heading. `#` is the Markdown syntax fo You may resize and change the colors of the icons with the `glyph-`-classes. Available sizes and colors listed: - - + + The comment will be shown in the style guide. Describe your css rules! Feel free to use [Markdown syntax](https://help.github.com/articles/markdown-basics/). The comment is optional but be nice to your developers! @@ -184,50 +184,56 @@ Easiest way to create a `.styleguide` file is to run `styleguide init` which wil ```javascript { - "sgComment": "SG", // If you want to begin a style guide comment + "sgComment": "SG", // If you want to begin a style guide comment // with something else than default: "/* SG" - - "srcFolder": "", // Folder with your css files. Will search all subfolders. + + "srcFolder": "", // Folder with your css files. Will search all subfolders. //Default: current working directory. - - "outputFile": "", // Where to output the style guide? + + "outputFile": "", // Where to output the style guide? // Default: "styleguide/dist/styleguide.html" - + "highlightStyle": "", // Syntax highlighting style. - // Syntax highlighting relies on highlight.js. + // Syntax highlighting relies on highlight.js. // See available styles here: https://highlightjs.org/static/demo/ - // and their internal names here: + // and their internal names here: // https://github.com/isagalaev/highlight.js/tree/master/src/styles // Default: "github" - + "highlightFolder": "",// folder to look for highlight stylse in. + // Default is highlight.js folder which is installed as + // a dependency to this package + "templateFile": "", // Path to custom Handlebars template - - "themeFile": "", // Path to custom CSS file to be included in the style guide - + + "themeFile": "", // Path to custom CSS file to be included in the style guide + "excludeDirs": [""], // Array of folders not to search for css files. // default: ["target","node_modules"] - + "fileExtensions": {}, // File extensions to search for style guide comments // default: {scss: true, sass: true, css: true, less: true} - + "customVars": {} // Holds an object with custom variables which will be - // available in the handlebars template. e.g: + // available in the handlebars template. e.g: // customVars: { sampleVar: 'Hi there' } // 'Hi there' will be printed if you request // {{customVars/sampleVar}} in the handlebars template. - + // ADVANCED - + "walkerOptions": { "followLinks": bool // Follow symlinks when searching for files? // default: false - // You may also add aditional walker options, + // You may also add additional walker options, // see: https://github.com/coolaj86/node-walk }, - "jqFile": "", // jQuery file, is included in package. - "highlightFolder": "" // folder to look for highlight stylse in. - // Default is highlight.js folder which is installed as - // a dependency to this package + "markedOptions": { // Options for marked markdown generator + "gfm": bool // Use Github-flavored markdown? + // default: true + // You may also add additional marked options, + // see: https://github.com/chjj/marked + }, + "jqFile": "" // jQuery file, is included in package. } ``` @@ -244,9 +250,9 @@ To create your own template/theme, copy the [template.html and theme.css](https: The Javascript object which you may use in your template file looks like this: ```javascript -{ - sections: [ - { +{ + sections: [ + { id: 'HTML safe unique identifier', section: 'Section Name (from the "# Section/Heading" Markdown)', heading: 'Heading Name (from the "# Section/Heading" Markdown)', @@ -261,7 +267,7 @@ The Javascript object which you may use in your template file looks like this: name: 'Section Name (one per unique "# Section")', headings: [ { - id: 'HTML safe unique identifier', + id: 'HTML safe unique identifier', name: 'Heading Name' }, {...} @@ -273,7 +279,7 @@ The Javascript object which you may use in your template file looks like this: ``` ## Run with gulp/grunt -If you want to re-create the styleguide automagicalle every time a stylesheet file is changed, you can run it with your favorite task runner. One way of running it with gulp would be using gulp-shell to execute the shell command `styleguide` when a file is changed. +If you want to re-create the style guide automagically every time a stylesheet file is changed, you can run it with your favorite task runner. One way of running it with gulp would be using gulp-shell to execute the shell command `styleguide` when a file is changed. Sample gulp script: ``` diff --git a/index.js b/index.js index 8e11860..62d9e2b 100644 --- a/index.js +++ b/index.js @@ -35,6 +35,9 @@ var options = { walkerOptions: { followLinks: false }, + markedOptions: { + gfm: true + }, customVars: { sampleVar: 'Hello from customVars!' }, @@ -141,6 +144,7 @@ try { * Custom renderer for marked. */ var renderer = new marked.Renderer(); + renderer.heading = function (string, number) { if (number === 1) { var header = string.split('/', 2); @@ -158,10 +162,11 @@ renderer.heading = function (string, number) { renderer.code = function (text, lang) { return '\n\n' + text + '\n\n'; }; -marked.setOptions({ - renderer: renderer, - gfm: true -}); + +//Force marked to use custom renderer (preventing user hijacking) +options.markedOptions.renderer = renderer; + +marked.setOptions(options.markedOptions); /** From 69ca979a110ecb615d66b8e13648db4bec17299f Mon Sep 17 00:00:00 2001 From: Cleecanth Date: Mon, 20 Jul 2015 17:50:21 -0500 Subject: [PATCH 4/7] Revert "Improve initial template" This reverts commit c59de37b20a963d73e5f933bc992581fc5ca8b11. --- template/template.html | 164 ++++++++++++++++++++--------------------- template/theme.css | 18 +---- 2 files changed, 81 insertions(+), 101 deletions(-) diff --git a/template/template.html b/template/template.html index da47b52..8b0e2c0 100644 --- a/template/template.html +++ b/template/template.html @@ -1,95 +1,87 @@ - - - - - - - - StyleGuide - {{> theme}} - {{> highlight}} - - -
-
    - {{#each menu}} -
  • - {{#if headings.0.name}} - {{name}} - - {{/if}} - {{#unless headings.0.name}} - {{name}} - {{/unless}} -
  • - {{/each}} -
-
+{{> theme}} +{{> highlight}} +{{> jquery}} -
- {{#each sections}} -
+ - // Show section in Styleguide - j('#styleguide .section[data-section="' + j('#styleguide-menu a').first().data('section') + '"]').show(); +
+
    + {{#each menu}} +
  • + {{#if headings.0.name}} + {{name}} + + {{/if}} + {{#unless headings.0.name}} + {{name}} + {{/unless}} +
  • + {{/each}} +
+
- // Click on link with subheadings - j('#styleguide-menu .submenulink').click(function(event) { - event.preventDefault(); - var jqCurSubmenu = j('[data-submenu="' + j(this).data('section') + '"]'); - var isCurSubmenuOn = jqCurSubmenu.hasClass('on'); - j('#styleguide-menu .on').removeClass('on'); - if (!isCurSubmenuOn) { - jqCurSubmenu.addClass('on'); - j(this).addClass('on'); - } - showSection(j(this).data('section')); - }); +
+ {{#each sections}} +
- // Click on link without subheadings - j('#styleguide-menu .sectionlink').click(function(event) { - event.preventDefault(); - j('#styleguide-menu .on').removeClass('on'); - j(this).addClass('on'); - showSection(j(this).data('section')); - }); +
+

{{section}}{{#if heading}}/{{heading}}{{/if}}

+ {{{comment}}} +
- // Show/Hide sections - function showSection(section) { - j('#styleguide .section').hide(); - var jqCurSections = j('#styleguide .section[data-section="' + section + '"]'); - jqCurSections.show(); - } - }); - - - + {{#if code}} +
+ {{{code}}} +
+ {{/if}} + + {{#if markup}} +
+
+{{{markup}}}
+
+
+ {{/if}} + +
+ {{/each}} +
\ No newline at end of file diff --git a/template/theme.css b/template/theme.css index 9b3f153..e96dd6f 100644 --- a/template/theme.css +++ b/template/theme.css @@ -11,7 +11,7 @@ box-shadow: 2px 2px 5px 0px rgba(50, 50, 50, 0.43); } -#styleguide .result, +#styleguide .result, #styleguide .comment { padding: 1em; border: 1px solid #ddd; @@ -33,20 +33,7 @@ #styleguide .markup { border: 1px solid #ddd; - border-top: none; -} - -#styleguide .markup pre { - overflow: auto; - padding: 0; - width: 100%; -} - -#styleguide .markup code { - display: block; - word-wrap: normal; - white-space: pre; - padding: 1em; + border-top: none; } #styleguide code, @@ -133,3 +120,4 @@ #styleguide-menu a.on { background-color: rgba(0, 0, 0, 0.1); } + From cc051e094bbb2d1a22858eb76f5850eb9cc6d25e Mon Sep 17 00:00:00 2001 From: Cleecanth Date: Mon, 20 Jul 2015 17:50:30 -0500 Subject: [PATCH 5/7] Revert "Revert "Improve initial template"" This reverts commit 69ca979a110ecb615d66b8e13648db4bec17299f. --- template/template.html | 164 +++++++++++++++++++++-------------------- template/theme.css | 18 ++++- 2 files changed, 101 insertions(+), 81 deletions(-) diff --git a/template/template.html b/template/template.html index 8b0e2c0..da47b52 100644 --- a/template/template.html +++ b/template/template.html @@ -1,87 +1,95 @@ -{{> theme}} -{{> highlight}} -{{> jquery}} + + + + + + + + StyleGuide + {{> theme}} + {{> highlight}} + + +
+
    + {{#each menu}} +
  • + {{#if headings.0.name}} + {{name}} + + {{/if}} + {{#unless headings.0.name}} + {{name}} + {{/unless}} +
  • + {{/each}} +
+
- + {{#if code}} +
+ {{{code}}} +
+ {{/if}} -
-
    - {{#each menu}} -
  • - {{#if headings.0.name}} - {{name}} - - {{/if}} - {{#unless headings.0.name}} - {{name}} - {{/unless}} -
  • - {{/each}} -
-
+ {{#if markup}} +
+
{{{markup}}}
+
+ {{/if}} -
- {{#each sections}} -
+
+ {{/each}} +
+ {{> jquery}} + + + diff --git a/template/theme.css b/template/theme.css index e96dd6f..9b3f153 100644 --- a/template/theme.css +++ b/template/theme.css @@ -11,7 +11,7 @@ box-shadow: 2px 2px 5px 0px rgba(50, 50, 50, 0.43); } -#styleguide .result, +#styleguide .result, #styleguide .comment { padding: 1em; border: 1px solid #ddd; @@ -33,7 +33,20 @@ #styleguide .markup { border: 1px solid #ddd; - border-top: none; + border-top: none; +} + +#styleguide .markup pre { + overflow: auto; + padding: 0; + width: 100%; +} + +#styleguide .markup code { + display: block; + word-wrap: normal; + white-space: pre; + padding: 1em; } #styleguide code, @@ -120,4 +133,3 @@ #styleguide-menu a.on { background-color: rgba(0, 0, 0, 0.1); } - From e7f6b1d6b1efceafe0106a1af8a839d4597ea502 Mon Sep 17 00:00:00 2001 From: Cleecanth Date: Mon, 20 Jul 2015 17:50:41 -0500 Subject: [PATCH 6/7] Revert c59de37..cc051e0 This rolls back to commit c59de37b20a963d73e5f933bc992581fc5ca8b11. --- README.md | 70 +++++++++++++++++++++++++------------------------------ index.js | 13 ++++------- 2 files changed, 36 insertions(+), 47 deletions(-) diff --git a/README.md b/README.md index 230b7c1..90866b7 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ In contrast to other style guide generators, this tool generates **a single file Style guides generated by this tool do not contain any css style! -The style guide simply contains HTML markup exemplifying how to use your css rules. That means that the generated html file will not do any good on it's own. Instead the intended use is to upload the generated HTML to your site where it will inherit your site's css. This also means that if you change your css - the look of the styleguide will change aswell. This way **the styleguide will always tell the truth**. +The style guide simply contains HTML markup exemplifying how to use your css rules. That means that the generated html file will not do any good on it's own. Instead the intended use is to upload the generated HTML to your site where it will inherit your site's css. This also means that if you change your css - the look of the styleguide will change aswell. This way **the styleguide will always tell the truth**. If you're using a CMS(-like system), this usually means that you create an article somewhere only accessible by developers and paste the content of the generated html file into that article (usually you'll have a `source` mode in your article editor). @@ -77,7 +77,7 @@ Example:

``` */ - + a [class^="icon-"], a [class*=" icon-"] { text-decoration: none; @@ -106,7 +106,7 @@ This will be rendered as: * ??? * profit -## Syntax +## Syntax Best described by going through the example above line by line. ##### Line 1 @@ -130,8 +130,8 @@ Every style guide comment **must** have a heading. `#` is the Markdown syntax fo You may resize and change the colors of the icons with the `glyph-`-classes. Available sizes and colors listed: - - + + The comment will be shown in the style guide. Describe your css rules! Feel free to use [Markdown syntax](https://help.github.com/articles/markdown-basics/). The comment is optional but be nice to your developers! @@ -184,56 +184,50 @@ Easiest way to create a `.styleguide` file is to run `styleguide init` which wil ```javascript { - "sgComment": "SG", // If you want to begin a style guide comment + "sgComment": "SG", // If you want to begin a style guide comment // with something else than default: "/* SG" - - "srcFolder": "", // Folder with your css files. Will search all subfolders. + + "srcFolder": "", // Folder with your css files. Will search all subfolders. //Default: current working directory. - - "outputFile": "", // Where to output the style guide? + + "outputFile": "", // Where to output the style guide? // Default: "styleguide/dist/styleguide.html" - + "highlightStyle": "", // Syntax highlighting style. - // Syntax highlighting relies on highlight.js. + // Syntax highlighting relies on highlight.js. // See available styles here: https://highlightjs.org/static/demo/ - // and their internal names here: + // and their internal names here: // https://github.com/isagalaev/highlight.js/tree/master/src/styles // Default: "github" - "highlightFolder": "",// folder to look for highlight stylse in. - // Default is highlight.js folder which is installed as - // a dependency to this package - + "templateFile": "", // Path to custom Handlebars template - - "themeFile": "", // Path to custom CSS file to be included in the style guide - + + "themeFile": "", // Path to custom CSS file to be included in the style guide + "excludeDirs": [""], // Array of folders not to search for css files. // default: ["target","node_modules"] - + "fileExtensions": {}, // File extensions to search for style guide comments // default: {scss: true, sass: true, css: true, less: true} - + "customVars": {} // Holds an object with custom variables which will be - // available in the handlebars template. e.g: + // available in the handlebars template. e.g: // customVars: { sampleVar: 'Hi there' } // 'Hi there' will be printed if you request // {{customVars/sampleVar}} in the handlebars template. - + // ADVANCED - + "walkerOptions": { "followLinks": bool // Follow symlinks when searching for files? // default: false - // You may also add additional walker options, + // You may also add aditional walker options, // see: https://github.com/coolaj86/node-walk }, - "markedOptions": { // Options for marked markdown generator - "gfm": bool // Use Github-flavored markdown? - // default: true - // You may also add additional marked options, - // see: https://github.com/chjj/marked - }, - "jqFile": "" // jQuery file, is included in package. + "jqFile": "", // jQuery file, is included in package. + "highlightFolder": "" // folder to look for highlight stylse in. + // Default is highlight.js folder which is installed as + // a dependency to this package } ``` @@ -250,9 +244,9 @@ To create your own template/theme, copy the [template.html and theme.css](https: The Javascript object which you may use in your template file looks like this: ```javascript -{ - sections: [ - { +{ + sections: [ + { id: 'HTML safe unique identifier', section: 'Section Name (from the "# Section/Heading" Markdown)', heading: 'Heading Name (from the "# Section/Heading" Markdown)', @@ -267,7 +261,7 @@ The Javascript object which you may use in your template file looks like this: name: 'Section Name (one per unique "# Section")', headings: [ { - id: 'HTML safe unique identifier', + id: 'HTML safe unique identifier', name: 'Heading Name' }, {...} @@ -279,7 +273,7 @@ The Javascript object which you may use in your template file looks like this: ``` ## Run with gulp/grunt -If you want to re-create the style guide automagically every time a stylesheet file is changed, you can run it with your favorite task runner. One way of running it with gulp would be using gulp-shell to execute the shell command `styleguide` when a file is changed. +If you want to re-create the styleguide automagicalle every time a stylesheet file is changed, you can run it with your favorite task runner. One way of running it with gulp would be using gulp-shell to execute the shell command `styleguide` when a file is changed. Sample gulp script: ``` diff --git a/index.js b/index.js index 62d9e2b..8e11860 100644 --- a/index.js +++ b/index.js @@ -35,9 +35,6 @@ var options = { walkerOptions: { followLinks: false }, - markedOptions: { - gfm: true - }, customVars: { sampleVar: 'Hello from customVars!' }, @@ -144,7 +141,6 @@ try { * Custom renderer for marked. */ var renderer = new marked.Renderer(); - renderer.heading = function (string, number) { if (number === 1) { var header = string.split('/', 2); @@ -162,11 +158,10 @@ renderer.heading = function (string, number) { renderer.code = function (text, lang) { return '\n\n' + text + '\n\n'; }; - -//Force marked to use custom renderer (preventing user hijacking) -options.markedOptions.renderer = renderer; - -marked.setOptions(options.markedOptions); +marked.setOptions({ + renderer: renderer, + gfm: true +}); /** From 84c5fe4da20142b73d03203d10e1dd626e14e984 Mon Sep 17 00:00:00 2001 From: Cleecanth Date: Mon, 20 Jul 2015 17:53:59 -0500 Subject: [PATCH 7/7] Move scripts to end Moved scripts to the end of template --- template/template.html | 157 +++++++++++++++++++---------------------- 1 file changed, 73 insertions(+), 84 deletions(-) diff --git a/template/template.html b/template/template.html index da47b52..2c1c9a7 100644 --- a/template/template.html +++ b/template/template.html @@ -1,95 +1,84 @@ - - - - - - - - StyleGuide - {{> theme}} - {{> highlight}} - - -
-
    - {{#each menu}} -
  • - {{#if headings.0.name}} - {{name}} - - {{/if}} - {{#unless headings.0.name}} - {{name}} - {{/unless}} -
  • - {{/each}} -
-
-
- {{#each sections}} -
+{{> theme}} +{{> highlight}} +
+
    + {{#each menu}} +
  • + {{#if headings.0.name}} + {{name}} + + {{/if}} + {{#unless headings.0.name}} + {{name}} + {{/unless}} +
  • + {{/each}} +
+
-
-

{{section}}{{#if heading}}/{{heading}}{{/if}}

- {{{comment}}} -
+
+ {{#each sections}} +
- {{#if code}} -
- {{{code}}} -
- {{/if}} +
+

{{section}}{{#if heading}}/{{heading}}{{/if}}

+ {{{comment}}} +
- {{#if markup}} -
-
{{{markup}}}
-
- {{/if}} + {{#if code}} +
+ {{{code}}} +
+ {{/if}} -
- {{/each}} -
- {{> jquery}} - - - + + // Click on link without subheadings + j('#styleguide-menu .sectionlink').click(function(event) { + event.preventDefault(); + j('#styleguide-menu .on').removeClass('on'); + j(this).addClass('on'); + showSection(j(this).data('section')); + }); + + // Show/Hide sections + function showSection(section) { + j('#styleguide .section').hide(); + var jqCurSections = j('#styleguide .section[data-section="' + section + '"]'); + jqCurSections.show(); + } + }); +