Skip to content
Snippets Groups Projects
  • Peter Mosses's avatar
    457dce36
    Improve build time of navigation panel (#956) · 457dce36
    Peter Mosses authored
    Fix #863.
    
    The current Liquid code to generate the navigation panel involves the inefficient extraction of a list of pages from a list of page groups (identified by @captn3m0 in his original [explanation of the performance issue](https://github.com/just-the-docs/just-the-docs/issues/863)). 
    
    The optimisation implemented by this PR generates navigation links directly from the list of page groups, thereby avoiding the extraction of a list of pages from it. The Liquid code is now a bit tedious, but I don't see a simpler solution. 
    
    The need for grouping pages arises because Jekyll doesn't provide a filter to sort a list of pages on the value of an arbitrary expression.
    
    Using Jekyll v4.2.2 (macOS 12.5, M2 MacBook Air, 16 GB memory), building https://github.com/endoflife-date/endoflife.date using https://github.com/pdmosses/just-the-docs/blob/fix-nav-performance/_includes/nav.html produced the following profile extract:
    
    Filename                                                    | Count |    Bytes |   Time
    ------------------------------------------------------------|-------|----------|-------
    | just-the-docs-0.4.0.rc1/_layouts/default.html                    |   130 |  3792.04K |  5.160 |
    | _includes/nav.html                                               |   130 |  1405.20K |  4.054 |
    | just-the-docs-0.4.0.rc1/_includes/head.html                      |   130 |   617.82K |  0.495 |
    | _layouts/product.html                                            |   127 |  1014.38K |  0.413 |
    | _includes/head_custom.html                                       |   130 |   427.83K |  0.393 |
    | assets/js/zzzz-search-data.json                                  |     1 |   149.31K |  0.050 |
    
    @nathancarter has tried adding the new `nav.html` to [a site with over 300 pages](https://nathancarter.github.io/how2data/site/), and reported that it improved the build time of more than 3 minutes to about 30 seconds.
    
    Further optimisation of navigation might be possible (e.g., using [Jekyll include caching](https://github.com/benbalter/jekyll-include-cache)), but the current optimisation should be sufficient for v0.4.0.
    
    To test that this PR does not appear to affect the navigation panel generated by v0.3.3:
    
    1. Clone https://github.com/just-the-docs/just-the-docs-tests.
    2. Update `_config.yml` and `Gemfile` to use this PR branch.
    3. Run `bundle update`.
    4. Inspect the rendering of the entire collection of navigation tests.
    
    (Many of the differences reported in the GitHub visualisation of the changes are due to shifting much of the code 2 spaces to the left, in connection with moving the first `ul` element to be close to its first item.)
    Improve build time of navigation panel (#956)
    Peter Mosses authored
    Fix #863.
    
    The current Liquid code to generate the navigation panel involves the inefficient extraction of a list of pages from a list of page groups (identified by @captn3m0 in his original [explanation of the performance issue](https://github.com/just-the-docs/just-the-docs/issues/863)). 
    
    The optimisation implemented by this PR generates navigation links directly from the list of page groups, thereby avoiding the extraction of a list of pages from it. The Liquid code is now a bit tedious, but I don't see a simpler solution. 
    
    The need for grouping pages arises because Jekyll doesn't provide a filter to sort a list of pages on the value of an arbitrary expression.
    
    Using Jekyll v4.2.2 (macOS 12.5, M2 MacBook Air, 16 GB memory), building https://github.com/endoflife-date/endoflife.date using https://github.com/pdmosses/just-the-docs/blob/fix-nav-performance/_includes/nav.html produced the following profile extract:
    
    Filename                                                    | Count |    Bytes |   Time
    ------------------------------------------------------------|-------|----------|-------
    | just-the-docs-0.4.0.rc1/_layouts/default.html                    |   130 |  3792.04K |  5.160 |
    | _includes/nav.html                                               |   130 |  1405.20K |  4.054 |
    | just-the-docs-0.4.0.rc1/_includes/head.html                      |   130 |   617.82K |  0.495 |
    | _layouts/product.html                                            |   127 |  1014.38K |  0.413 |
    | _includes/head_custom.html                                       |   130 |   427.83K |  0.393 |
    | assets/js/zzzz-search-data.json                                  |     1 |   149.31K |  0.050 |
    
    @nathancarter has tried adding the new `nav.html` to [a site with over 300 pages](https://nathancarter.github.io/how2data/site/), and reported that it improved the build time of more than 3 minutes to about 30 seconds.
    
    Further optimisation of navigation might be possible (e.g., using [Jekyll include caching](https://github.com/benbalter/jekyll-include-cache)), but the current optimisation should be sufficient for v0.4.0.
    
    To test that this PR does not appear to affect the navigation panel generated by v0.3.3:
    
    1. Clone https://github.com/just-the-docs/just-the-docs-tests.
    2. Update `_config.yml` and `Gemfile` to use this PR branch.
    3. Run `bundle update`.
    4. Inspect the rendering of the entire collection of navigation tests.
    
    (Many of the differences reported in the GitHub visualisation of the changes are due to shifting much of the code 2 spaces to the left, in connection with moving the first `ul` element to be close to its first item.)