Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Every section a page? #71

Open
phun-ky opened this issue Mar 26, 2019 · 18 comments
Open

Every section a page? #71

phun-ky opened this issue Mar 26, 2019 · 18 comments

Comments

@phun-ky
Copy link

phun-ky commented Mar 26, 2019 •
edited
Loading

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..
@straker
Copy link
Owner

straker commented Mar 26, 2019

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?

@phun-ky
Copy link
Author

phun-ky commented Mar 26, 2019

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?)

@phun-ky
Copy link
Author

phun-ky commented Mar 26, 2019

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

@phun-ky
Copy link
Author

phun-ky commented Mar 27, 2019

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:

image

The index file is 4.4 megs:

image

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

@straker
Copy link
Owner

straker commented Mar 28, 2019

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.

@phun-ky
Copy link
Author

phun-ky commented Mar 28, 2019

Just ping me if you want to check out the repository

@phun-ky
Copy link
Author

phun-ky commented Jun 26, 2019

Any progress on this?

@straker
Copy link
Owner

straker commented Jun 26, 2019

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.

@straker
Copy link
Owner

straker commented Jul 29, 2019 •
edited
Loading

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?

@phun-ky
Copy link
Author

phun-ky commented Aug 5, 2019

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.

@phun-ky
Copy link
Author

phun-ky commented Nov 18, 2019

Any progress on this?

@straker
Copy link
Owner

straker commented Nov 18, 2019

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.

@straker
Copy link
Owner

straker commented Nov 24, 2019

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
});

@phun-ky
Copy link
Author

phun-ky commented Nov 28, 2019

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.

@phun-ky
Copy link
Author

phun-ky commented Nov 28, 2019

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?

@phun-ky
Copy link
Author

phun-ky commented Nov 28, 2019

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.

@phun-ky
Copy link
Author

phun-ky commented Dec 6, 2019

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

@straker
Copy link
Owner

straker commented Dec 6, 2019

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

@straker straker mentioned this issue Dec 31, 2019
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@phun-ky @straker