livingcss
livingcss copied to clipboard
straker
Every section a page?
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..
I wonder if it has something to do with the fact that the code still uses Polymer 1 and polyfills for v0 custom elements. I could try to look to see if that could be improved for performance of large styleguides.
If you don't use @sectionof does that let you make each section it's own page?
Yeah, removing polyfills and polymer 1 in advantage for polymer 3 or usage of another app that has scoping, will help.
I can do that yes (have to manually edit 100 lines though), but I will then have no hierarchy and no menu :( (or?)
The best way would be if I could keep the @section and @sectionof parts, use @page when I want a page, and still keep the menu and hierarchy. And the files could be named with the same naming convention: instead of #guidelines-components-modal -> guidelines-components-modal.html, when we're linking to a page
Another thing I've noticed is that the options.loadcss-option is not working as intended. From the code, it will load:
<!-- user styles -->
{{#each globalStylesheets}}
<link rel="stylesheet" href="{{this}}">
{{/each}}
<!-- /user styles -->
The source from the parsed css, but I have no such <link>'s in my generated styleguide. My css is looks like it's currently inline in the <body>-section , right after the polymer stuff.
The css is also not deduplicated. For example, all my components require core.styl which requires normalize.css. This results in over 30 instances of normalize.css in the inline css. Will this improve if every component is on its own page?
As of now, my styleguide is over 81 000 lines of html and css, not including some helper javascript stuff:
The index file is 4.4 megs:
To top it off, I have over 560 examples (as in, usages of the polymer example tag), so that might be better if I use pages to split things up
How interesting. That's a lot of things going on. I can see why there's massive scale problems with the library. Splitting up everything into its own page seems like it would help.
I'll look into what it would take to make everything it's own page, as well as improve the performance at scale.
Sorry, I've been so busy lately I completely forgot about this. Thanks for the reminder. I'll schedule some time to look into this.
I did do some initial looking into improving performance by upgrading the Polymer library, but wasn't able to find anything that looked Promising. The new version of Polymer requires a build step using their specific tooling to generate the web component output, so that didn't look like it would work. Other shadow DOM libraries do the same. Will continue to keep looking.
Alright, so I've got this working (I think), but would like your opinion on something. Now that each section is its own page, I've kept the page links at the top for primary pages, and then each primary section within the page is now it's own page. However, this leaves the primary page links without any content.
So for example, if I had 2 pages typography and buttons, and each page had a few sections
- typography
- headings
- paragraphs
- buttons
- primaryButtons
- secondaryButtons
Each section is now their own page (primaryButton.html, sectondaryButton.html, etc.) and the 2 top page links for typography and buttons are not even generated since all their sections are on different pages.
My question then is what should go in these top page links?
Hi! Back from the summer holiday @straker , let's see. What I have done is to manually create an index.html file that links to the documentation (the first top section), and have the same menu present for all pages (the four top sections that are pages for now). Kinda like this:
<aside class="sg drawer">
<a data-rel="{{navbar.0.url}}" href="/" class="sg homeLink"></a>
<nav id="menu" class="sg navigation">
<ul class="sg navigation list container" id="nav" role="tablist">
{{#each pages as |page pageKey| }}
{{#with page as |currentPage|}}
<li class="sg navigation item">
<a href="{{currentPage.id}}.html" class="sg navigation link">{{currentPage.name}}</a>
{{#if sections}}
{{#sections}}
{{#if children}}
<ul class="sg navigation list inner">
{{#children}}
<li class="sg navigation item">
<a href="{{currentPage.id}}.html#{{id}}" class="sg navigation link">{{name}}</a>
{{#if children}}
<ul class="sg navigation list inner">
{{#children}}
<li class="sg navigation item">
<a href="#{{id}}" class="sg navigation link">{{name}}</a>
{{#if children}}
<ul class="sg navigation list inner">
{{#children}}
<li class="sg navigation item">
<a href="#{{id}}" class="sg navigation link">{{name}}</a>
</li>
{{/children}}
</ul>
{{/if}}
</li>
{{/children}}
</ul>
{{/if}}
</li>
{{/children}}
</ul>
{{/if}}
{{/sections}}
{{/if}}
</li>
{{/with}}
{{/each}}
</ul>
</nav>
</aside>
If every section is a page, I would have the same menu everywhere, so it's easier to jump between the pages and sections.
I am so sorry for keeping you waiting on this once again. This has been a very busy year for me and I haven't quite yet recovered from it. I'll see if my code still outputs the single page, make the index a simple TOC, and try to get this released soon.
Alright, if you want to checkout the everySectionPage branch and then add allSectionPages: true as an option, that should make each top level section it's own page. Let me know if that solves the problem or if I need to figure out how to make child sections their own pages as well.
livingcss('path/to/file.scss', '.', {
everySectionPage: true
});
Hi! I've already, manually, added each top level section as an own page, and it does not leviate much. The documentation site we generate now is useless in chrome (chrome freezes/hangs).
Is there a way to do something with polymer to fix this?
Will test it out, but if it only make top level section (for my usage, it's 5 pages, and only two of them has examples), it will not do much.
Just tried it, and no effect (since I've already done it manually, but as I'm writing this, it needs to be tested without the manual @page -setting). Is it possible to only instantiate the example when it is close to the viewport, as in, lazy loading? or to look at polymer itself?
Removed polymer, and things are working better (note, better, not good or perfect) with Chrome. But still, it is remarkably slower than the other browsers.
I feel that I might have not explained clearly what I want. I not only want to have the top parent sections as pages, but I want to be able to say that for example:
I have 7 top parent sections, that has no parent. These are linked too from a custom index.html.
Each one of those pages has their childs. The navigation menu in these pages are only relevant for that page. linking between the 7 pages are done in a custom navigation. In one of these pages , components.html is the largest. I want to be able to say that each child of that page is a separate page, and that THAT page also have the same menu structure as the parent. I don't know if this makes sense for you, but I try :P
I believe so. Thinking about it more, does a structure similar to MDN docs make sense? They seem to have every section it's own page with a sidebar nav of every other section that shares the same parent. And they do this for as deep as the nesting goes. Sounds like what you are talking about. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/some