straker / livingcss Goto Github PK

When I use something like

* @code {sass}
* @include myMixin(); 
* @include myMixin(option);  

I'm getting this

@include myMixin(); 
@include myMixin(option);  

Only the first @ is getting replaced with the @ symbol.

Any ideas?

index.js

// add custom tags
for (var tag in options.tags) {
    if (!options.tag.hasOwnProperty(tag)) {
      continue;
    }

should be options.tags.hasOwnPropety.

loadPartials.js

return utils.readFileGlobs(partials, function(data, file) {
  // the name of the partial will be the name of the file
  var name = path.parse(file).name;

path.parse does not exist in node v0.10.x, use path.basename(file, path.extname(file)); instead

I get these messages section 'MySection' is not defined (style.css:68) If the section name has any white space on the end.

I would do the PR myself but slammed right now. Would you mind trimming the @section, @sectionof, @doc, and @page tags please?

Looking to add metadata to tags for cross app uses. Specifically, noting the name spaces used across components to detect potential collisions.

The tags: function seems to narrow the context to only the current tag. Any way to elevate information or would I have to extend this in the module?

tags.page.call({
        block: block,
        comment: comment,
        file: file,
        pages: context.pages,
        sections: context.sections,
        tag: {description: 'index'}
      });

Expecting to define an @section at the start of a comment section I was quite surprised that this is done at the very end. I was just curious what the reasoning behind this is. Personally I think it would make more sense to define it at the beginning, but maybe there's a good reason for it to do it differently.

I'm talking about:

/**
 * This is the bodytext
 * 
 * @section Some section
 * /

vs

/**
 * @section Some section 
 * 
 * This is the bodytext
 * /

Awesome library btw!!

I'm having a section Notifications and Form elements in my styleguide, with two subsections "alerts" and "form controls". Both are split into two separate files. In order of appearance, @section 1. Notifications and Form elements is defined inside form controls file. Is there any way of using @sectionof 1. Notifications and Form elements inside "alerts" file? Currently I'm getting ReferenceError: section '1. Notifications and Form elements' is not defined error.

this sounds promising, is there a demo to see a styleguide in action?

.livingcss-example element for me is having 1100px. I don't know where this value came from yet, but it is causing this block to overflow parent container. When I'm turning it off in dev tools, everything's perfectly fine.

Here's how it looks for me:

Also, as a result, horizontal scroll appears.

I'm generating app.css from an application *.scss structure. Class .text-bold is being properly preprocessed into a final app.css file. But when I try to apply this class to an example, styles are not being applied. Fun thing, is that applying next class .text-italic which is in a same file and right after .text-bold, styles are applied properly.

After briefly checking livingcss code, to find out where it renders app.css contents (contents of context.stylesheets), I've found a node <style scope="livingcss-example"></style> which contains my styles, but not all of them. On the other hand when I'm passing app.css into context.globalStylesheets it works, but is being applied globally, which's not good for me. Any ideas on what can cause such a behavior?

Node script which generates livingcss styleguide:

const livingcss = require('livingcss'); // eslint-disable-line import/no-extraneous-dependencies
const sass = require('node-sass');
const fs = require('fs');

const dirName = `${__dirname}/..`;
const options = {
  preprocess: (context) => {
    context.globalStylesheets = [
      `${dirName}/styleguide/styles/styleguide.css`,
    ];
    context.title = 'My styleguide';
    context.stylesheets.push(`${__dirname}/app.css`);
  },
};

fs.writeFileSync(`${dirName}/styleguide/app.css`,
  sass.renderSync({
    file: `${dirName}/app/src/_common/styles/main.scss`,
  }).css);

livingcss(`${dirName}/app/src/_common/styles/**/*.scss`, `${dirName}/styleguide`, options);

CSS of partial which is not being transferred into generated stylesheet:

/**
 * @section Bold text
 * @example
 * <div class="text-bold">Bold weight text letter-space: 0</div>
 */
.text-bold {
  font-weight: bold !important;
  letter-spacing: 0;
}

Btw, body styles like line-height or font-family are also not being applied.

Hi there,
So, I've been using your livingcss (which is awesome BTW) and it's been working locally without a hitch, but I've started trying to run it on my server and the livingcss gulp process doesn't seem to be working quite right...
I've stripped everything down to a single livingcss comment block and the gulp process only has a src > livingcss > destination, but still things are not as they should be.

The first issue is that when I look at the Devtools on server, it doesn't seem to be loading the shadow DOM and any Shady DOM Styles:

(The local file doesn't have this).

My gulpfile looks like this:

// Tell node.js about these modules.
var gulp         = require('gulp');
var include      = require("gulp-include");
var concat       = require("gulp-concat");
var sass         = require('gulp-sass');
var livingcss    = require('gulp-livingcss');
var autoprefixer = require('gulp-autoprefixer');

// CONCAT / SASS Compile into CSS file.
gulp.task('livingcss-sass', function(){
    return gulp.src([
            './resources/assets/sass/molecules/swatch.scss',
    ])
        .pipe(concat('styles.scss'))
        .pipe(sass())
        .pipe(gulp.dest('./public/livingcss/src/'))
});

//Run the Living Stylesheet creator.
gulp.task('livingcss',['livingcss-sass'], function () {
    gulp.src('./public/livingcss/src/styles.css')
        .pipe(livingcss())
        .pipe(gulp.dest('./public/livingcss/dist/'))
});

The swatch.scss file has the following:

/**
 * Swatch
 *
 * Everything to do with the combinations of Atom components into Molecules.
 *
 * @section Swatch
 * @page Molecules
 *
 * @example
 * <div class="rk-swatch">
 *  <div class="rk-swatch-col"></div>
 * </div>
 */

$rk-white :                    #f7f7f7;

.rk-swatch {

  // Display & Positioning

  // Box Model
  width : 150px;
  margin: 10px;
  padding-bottom: 5px;

  // Colour
  background: $rk-white;

}

.rk-swatch-col {
  display: block;
  // Box Model
  width: 100px;
  height: 150px;

  background: #990000;
}

This creates the result:

Which is not the result that should be displayed. The styling for the rk-swatch-col DIV is not applied and the shadow DOM is not present.

Not sure what's happening at all. I've got it all successfully running locally and the results are fine.

Is this an issue here?

How to set a sort order for a child sections of a given section? For page, it is obvious from a doc:

options = {
  sortOrder: [
    {
      index: [
        '1. Section A',
        '2. Section B',
      ],
    },
  ],
};

What if I have a few sub-sections: '2.2 Section C' and '2.1 Section Z', for '2. Section B'. How to sort them?

As discussed, might be fun to open up a space where people can post their templates, partials, helpers, or custom tags etc.

I'm creating a living styleguide from many stylus files, and each file is documented with JSDoc syntax (I am currently converting from documentcss). The files are preprocessed and bundled into a bundle file containing all relevant documentation. To actually preserve the comments through the preprocessor, I am forced to use exclamation marks to dictate which comments the preprocessor shall not remove. This results in livingcss not handling the JSDoc. Why?

To clarify, this works with livingcss:

/**
 * My Section
 *
 * A description of the section and how to use it.
 *
 * @section
 */

This does not:

/**!
 * My Section
 *
 * A description of the section and how to use it.
 *
 * @section
 */

How can I make use of this module without removing the exclamation mark?

Quick question regarding Custom Tags.

I'm attempting to create an accordion navigation for the sections. Ideally the @page would be the parent level of the @section.

Any ideas or direction you could send me in?

cheers

Hello again,

I'm interested in having multiple @code and @example blocks per section. Right now I'm trying to put both an HTML @code and a SCSS @code in one section. Support for multiple @example blocks would be useful to me as well.

It looks to me as if the comment parser has support for this.

Does this sound like a feature you'd be interested in having in this project? Happy to take a look and submit a PR, if so 😃

Steps to Reproduce

Create a directory structure such as:

• css/
  • main.css
• styleguide/
• index.js

var path = require('path');
var livingcss = require('livingcss');

// all of these fail:
livingcss('css/buttons.css', 'styleguide');
livingcss(path.join(__dirname, 'css/buttons.css'), 'styleguide');
livingcss(path.join(__dirname, 'css/buttons.css'), path.join(__dirname, 'styleguide'));
livingcss('css/buttons.css', path.join(__dirname, 'styleguide'));

Actual Behavior

Error: ENOENT: no such file or directory, open '../css/buttons.css'

Expected Behavior

• Styleguide generated in specified directory
• Stylesheets linked (if flag enabled)

One minor niggle I found out, you might want to fix at some point (not critical), or if someone else needs this.

When using options.template, the template.hbs relinks ok, but partials stay linked to livingCSS/template directory.
It's a minor hassle, but e.g. for me, the need to relink template comes from need to keep all source files (including templates) in one location.

I fixed this now on my install by throwing in this code:

  //Define path to Handlebars partials based on path to template
    //So defaultPartials is always always grounded on path of options.template
  var pathToTemplate = options.template.substring(0, options.template.lastIndexOf('/'));
  defaultPartials = path.join(pathToTemplate, '/partials/*.hbs')
  //console.log(defaultPartials)

Just after options.template is checked (on index.js, line 88). But, there is probably more elegant way to accomplish same :-)

I love using this to create a styleguide, but haven't been able to consistently create pages based on the documentation. Could you please add an example showing how to create several styleguide pages?
Thanks!

The import path in Windows uses backslash, which results in the following error.

I'm getting this error when I'm trying to preprocess the context to link my output css file (I'm running gulp-livingcss against a Sass codebase).

My task:

const livingcssConfig = cssFilePath => {
    return {
        loadcss: false,
        preprocess: (context, template, Handlebars) => {
            return livingcss.utils.readFileGlobs(cssFilePath, (data, file) => {
                context.globalStylesheets.push(file);
            });
        }
    };
};

// development
gulp.task('livingcss:dev', () => {
    gulp.src(`${config.sass.path}/**/*.scss`)
        .pipe(livingcss(livingcssConfig(`../../${config.css.path}/${config.css.output}`)))
        .pipe(gulp.dest(`./${config.styleGuide.path}/${config.styleGuide.info}`));
});

When I go to the URL http://localhost:3000/style-guide/info/ I see the SG output but with the default styling. When looking at the output index.html, nothing was written between the user styles comment block. If I add that file path in manually, it now picks up my styles:

<!-- user styles -->
<link rel="stylesheet" href="../../css/main.css">
<!-- /user styles -->

What am I doing wrong?

As an aside, when I did that (manually added the css path), it picked up most of my styles but, for instance, my bare ole a tag styles did not, for whatever reason, actually get used (though things like body copy color, spacing, etc were). Not sure about that one either but I guess lets take it one step at a time :)

Styleguide is slow and unresponsive with large styleguides

I'm currently experiencing that the generated styleguide is slow and sometimes unresponsive, especially at load. This makes it hard to use direct linking to sections.. Perhaps due to many examples and lots of components. I've split up the top sections into pages to test it out, but it hasn't improved as much as I'd like, so I was wondering if it's possible to make every section it's own page

Just to clarify, when using @page , the html file for that component or section is made, but if it's a sectionof, the file only contains the template, and not the documentation..

Hi,

How we can use tags in our styleguide?
In documentation we have examples how generating but I don't see example how to use.

Could you help?

Is there an alternative way to display an @ symbol in documentation text?

In a piece of documentation outside of a typical @example, I'm trying to demonstrate how to use a particular sass mixin, like:

/**
* Here's an example using the `theme()` mixin:
* ```css
* .my-selector {
*   @include theme() {
*     background-color: color('shade');
*   }
* }
* ```
*/

But the use of the @ here breaks the output.

Thanks in advance!

Apologies if this is the wrong place to ask this but I am attempting to implement the style guide myself, which may I add is great so far. I have a couple of questions which I am hoping you can clear up.

1. Creating a custom template appears to be relatively straightforward in that I have to use the template property in the options. I have copied over the templates that are originally used and am going to edit them, as far as the style guide styles, would removing the main style sheet and adding my own to the css that is copied over be sufficient? Or am I going about it the wrong way?

2. I would like to list the entire menu as a side nav but with child components as pages, not one long page with sections. For example:

   Overview
   - Introduction
   - Getting started
   - Design Principles
   

   I would like the three sub-nav items to be sectionsOf Overview but as links to their own page. I've not
   had too much experience with .hbs, how would I go about doing this?

   I know the below isn't correct but you can see what I mean

   /**
     * @section Design Principles
     * @sectionOf Overview
     * @page Design Principles
   **/
   
   /**
     * @section Getting Started
     * @sectionOf Overview
     * @page Getting Started
   **/
   
   /**
    * @page Overview
    */
   

Hello again,

I'm using the SCSS syntax highlighting from prism, and the following code block causes livingcss to choke:

@code {scss}
.example {
  @extend %placeholder-selector;
}

My guess is that the @extend is getting registered as a tag by the parser. I'm not sure exactly how to resolve this, since there are not "closing" tags. Perhaps a list of exclusions, or a way to escape tags?

Valid SCSS includes @include, @extend, @mixin, etc.

Let me know if I can provide any more info 😄

Yet another problem I have been struggling with. Issue or by purpose ? Or am I trying to misuse the tags system ?
Anyway. Section description gets nicely formatted in Markdown. However, text that is following a custom tag won't get formatted.

So, I have:

/**
 * SomeSectionTitle
 *
 * ##### Some section description with Markdown syntax (*like heading* for a title)
 * And some paragraphs of text with formatting (like `inline code`). This of course will get proper 
 * formatting.
 * 
 * But then I define a tag (that I use in hb template to allow some fancy layout).
 * @someRandomTag
 * #####Title
 * And it has a description following the tag. 
 * But it *won't get formatted* even if having **Markdown** syntax.
 * It's not a custom tag (as there is no callback defined for it, but I can simply rely on automatic parsing of 
 * tags (which is nice as itself) 

I think the issue is that block.description gets passed to marked (in tags.js) while tag.description in parseComments.js won't.

I can probably live with this, but it would be so much more easier to manage writing the style guide content if Markdown formatting would be available everywhere.

I'm piggy backing off of the generated JSON to create snippets for various editors for a team to use.

I'm using gulp-livingcss and wondered if there was a way to get just the JSON for the sections returned that I could then pipe into something else to generate the snippets. I'm currently just grabbing the context.sections from preprocess and saving it out to a file, but I'd rather not have this intermediate step of saving to a file then reading from it and do it the more correct way with streams.

Is there a way to do this currently?

By chance does livingcss work with LESS/SASS css pre-processors? Was hoping to do something like...

gulp.task('less', function () {
  gulp.src(['./less/app.less'])
    .pipe(less({
        plugins: [autoprefix]
    }))
    .pipe(livingcss())
    .pipe(gulp.dest('./patterns'));
});

Or something.

Thanks!

The generated from SASS to CSS styles for h1 are as follows:

h1 {
  font-family: "Helvetica Neue Light", "Helvetica Neue Regular", "Helvetica Neue", "Helvetica", "Arial", sans-serif;
  font-size: 2.25rem;
  line-height: 1.375em; }

But on a page, in styles section of devtools, font-family looks like this:

h1.livingcss-example {
    font-family: "
    font-size: 2.25rem;
    line-height: 1.375em;
}

Is there any legit way to include custom font files into styleguide? (Your default template is taken as base).

First of all, great package! Work like a charm!

However, there is a feature I really miss, and that is to be able to use markdown files for the documentation. This because the inline documentation with comments in the css files (or stylus/less what not) can be quite tedious to maintain, remembering to use the * and the correct indendation and no autocomplete/syntax highlightning in the comments. This feature would also allow the files to be more editable by github users (for those projects using it)

I would love to have something like this:

/**
 * @section Buttons
 * @doc Components.Buttons.md
 * @sectionof Components
 */

The *.md file can contain examples and code.

Is this doable and within the scope of this module?

I noticed that when a stylesheet implements something like:

.foo {
  color: black;
}
.bar {
  color: white;
}
.foo > .bar {
 color: blue;
}

.bar will always be blue, because .bar is treated as a separate selector without the child combinator before it.

To get around this I have a task to remove all child combinators in the stylesheet that's used with livingcss. This isn't ideal since it wouldn't cover cases where the styling should only affect immediate children of said selector.

I tried finding the root case, but ran out of time. If you point me in the right direction though to where the parsing takes place, I might be able to fix it. Perhaps it's part of Polymer?

Is it possible to use your library with SCSS files?

I spent some time updating our version of livingcss, took quite a long time to figure out why the examples weren't rendering with the styles. Turns out it was because I had style tags in some of the examples.

/**
* @example
* <style>p.example { backround-color: gray; }</style>
* <div class="flex-container">
*   <p>Example Text</p>
* </div>
*/

Maybe this should just be documented, maybe an error should be thrown or maybe style tags should be supported (they can be pretty handy sometimes, but there are other ways to achieve this of course).

need to copy sectionOrder from the page object into the new pageContext object in index.js:144.

context.pages.forEach(function(page, index) {
      // deep copy context for each page
      var pageContext = JSON.parse(JSON.stringify(context));
      pageContext.sections = page.sections;
      pageContext.sectionOrder = page.sectionOrder;

Hello,

Currently if a doc comment with, e.g. @section A gets parsed before a doc comment with, e.g. @sectionof A the styleguide will fail with ReferenceError: section 'A' is not defined. Would it be possible to implement a parsing scheme such as:

• Documentation with a single @section gets parsed before documentation with any @sectionof
• Documentation with a single @sectionof gets parsed before documentation with 2+ @sectionof
• etc...

I haven't thought this through 100% but it seems like a nice improvement (and would help my use case 😄 ).

I'm getting section X is not defined errors that I don't completely understand. (Less errors now that the fields are trim, thank you!)

fails

/** Typography
 * desc
 * @section
 */

 /** Text
 * desc
 * @section
 * @sectionof Typography
 */

works

/** Typography
 * desc
 * @section Typography
 */

 /** Text
 * desc
 * @section
 * @sectionof Typography
 */

Why do we have to repeat the section name for it to be available for children?

Hi,

I have a one more question

How we can change path to images in the styleguide?
The only way is to use ex. "/path"?

Thanks!

I'm able to make a custom tag easy enough following the documentation provided, but what I'd like to do when documenting colors, icons and other repeatable stuff, is create a custom tag that I can loop through in the template.

So ideally my styles file would look something like...

/**
* @section Color Palette
*
* @color {#F00} Brand Red ($brand-red) - Section Description
* @color {#F8F8F8} Foreground Shade ($fg-shade) - Used to shade foreground areas when needed.
**/

Then in a template I'd want to...

{{#each colors}}
  <p>{{color.name}}</p>
  etc...
{{/each}}

Is this possible?

Thanks in advance! Making my second pattern library with livingcss, such awesome stuff.

Hi again.

I'm looking to normalize my comments by explicitly naming sections:

* @section My Section
* @sectionof My Other Section
* @description 
* Some `markdown` code for a description

However this is breaking the markdown parsing for some reason.

I get these outcomes from the following.

EG1

* My Section
* Some `markdown` code for a description
* @sectionof My Other Section

Markdown parsed

EG2

* @section My Section
* @sectionof My Other Section
* Some `markdown` code for a description

Description is plain text and requires HTML tags.

EG3

* @section My Section
* @sectionof My Other Section
* @description Some `markdown` code for a description

Same as above regardless of the line @description

EG4

* @section My Section
* @sectionof My Other Section
* @description {markdown} Some `markdown` code for a description

Description is replaced with [object Object]

EG5

* Some `markdown` code for a description
* @section My Section
* @sectionof My Other Section

Markdown parsed but awkward as the section name is buried a bit in the comment.

EG6

* My Section
* Some `markdown` code for a description
* @section My Section
* @sectionof My Other Section

Markdown parsed but title is inferred and duplicated

What do you think is my best path here?

I have a requirement to add a namespace class for the @examples code to be styled correctly.
Best practice debates aside I think this would be a common requirement for existing projects and I would like to contribute it to this project.

I have 2 3 ideas:

1. Global 'namespace' option that gets copied into each context
2. A new 'namespace' tag that can be applied to individual examples
3. None.

What is your preference?

Hi,
if you have an experience with making livingcss work alongside webpack, could you help me providing a simple example of how this can be achieved?

So I want to retain most everything in the default template except the mainStylesheet partial (as it resets some of my global styles which I'd rather not do). In fact, I'd argue that only what is in that partial should be namespaced with .livingcss and anything that could possibly be global not include which would make this even easier, but alas.

What is the best way to replace only this portion? I don't want all the resets that happen there but I do want the rest of the styles for the style guide portions. The only thing I can think of is re-creating the templates directory/files in my code and ripping it out of there and pointing the template to my directory instead. The problem with that is updates to these files will no longer cascade to me and every time I update livingcss I'd have to do the copying over to my files, rip out styles i don't need from mainStylesheet partial, etc.

What is the best way forward for this?

First off, great project. Everything has been working great so far, with the one exception that we just ran across.

What we're trying to do is include a markdown file for non-developers to maintain, while leaving the scss files to our devs.

Version

[email protected]
[email protected]

Example

File structure

┬ dist
└- compiled.css
┬ src
└┬ atoms
 ├- button.md
 └- button.scss
┬ docs
├- atoms.html
├- molecules.html
└- ...

button.scss

/**
 * @doc button.md
 * 
 * @example
 * <button class="our-button">Button</button>
 *
 * @section Button
 * @page Atoms
 */

.our-button { ... }

button.md

# Button

Description blah blah blah

gulpfile.js

gulp.task('guide:build', () => {
  const sourceFiles = './dist/*.css';
  const destination = './docs';
  
  gulp.src(sourceFiles)
    .pipe(livingcss(destination))
    .pipe(gulp.dest(destination));
});

When running the guide:build task, the following pops up in the console and no new HTML is generated:

UnhandledPromiseRejectionWarning: Unhandled promise rejection (rejection id: 1): [object Object]

If we exclude the @doc button.md line from button.scss, the task works perfectly.

Is this functionality supported? Is there something wrong with our configuration?

Edit: Expanded on file structure; Simplified gulp task

Like others posting, this is a great app.

I'm trying to break out sections into separate pages. So I could have a category but then have sub-categories all be separate pages.

Components /components.html

• Buttons /components-buttons.html
• Banners /components-banners.html

When I try to create pages for the sub sections the components-buttons.html page is blank and since I'm referencing the sectionof those sub sections get displayed on whatever the parent section is.

Now that I've got pages generated (thank you!), I am fine tuning my page order and section order within pages.

The first issue I found was that arrays are not handled in this case:

// sort the pages organisms and templates in that order, but not any of
// their sections
['organisms', 'templates']

Arrays are not handled in utils.generateSortOrder, only strings and objects. I added this at line 53 of utils.js so I could keep moving forward on my project:

if (Array.isArray(value)){
for (var i = 0; i < value.length; i++) {
context.pageOrder.push(utils.normalizeName(value[i]))
}
return;
}

For section ordering within a page, I found this statement on https://github.com/straker/livingcss to be untrue:

Names are case insensitive.

Values within arrays are case insensitive, but if you use the object syntax the page name key is case sensitive.
For my page "Colors", the sections will not be sorted with this configuration:

{colors:["greys","oranges","blues","reds","yellows"]}

but the following configuration will sort the sections

{Colors:["greys","oranges","blues","reds","yellows"]}

That's because this test is case sensitive (line 66 after I added the above array code):

if (context.pages[prop])
The key is "Colors", not "colors", so the test is never true.

This is not high priority request as I can work around both issues with context.sortOrder configuration changes.

// file 1

/**
 * @page core
 * @section Components
*/
...

// file 2
/**
 * @page theme
 * @section Components
 */

Fails with Components section is already defined.

Hi,

Livingcss works in the IE11? I asking you beacuse I'm testing now and CSS is not loaded.

Thanks

PS. Could you update gulp-livingcss with the latest livingcss? :)

I get an error when trying to run a simple javascript file using living css
heres the repo:
https://github.com/aar0nwils0n/livingcss-test
after running node index.js I get the following error

Error: The partial mainStylesheet could not be found

macOs 10.13.4
node v 8.12.0

Looking to see if you are actively upgrading this to Gulp 4. The current package versions throw warnings and have a few issues that an upgrade fixed. If not, perhaps I can help as it only took a few changes on my local to get things running again.

Love this framework, been implementing it and love the flexibility of it.

I'm looking at making it a bit tighter as far as the HTML that is served up and I've noticed that in livingcss by default it inlines all the Polymer and included CSS files (including ours). But when I go to the Family Search style guide (actual served pages) there is no Polymer on it. Is there any chance of seeing those templates? The linked GitHub for that seems to just be the actual files that create the CSS style guide and not the files that make the online style guide.