Dev UX: How to preview docs/site in incremental mode

[bajtos]

Description / Steps to reproduce / Feature proposal

When making changes to documentation files in docs/site folder, I'd like to preview the changes I am making.

Current Behavior

I can run npm run build:site command to copy all sources and start Jekyll server.

However, this process does not support incremental updates. Whenever I make a change, all files have to be re-downloaded from docs/site and GitHub repositories.

Alternatively, it may be possible to combine npm run copydocs and loopback.io's npm start to speed the updates a bit, but it's still not ideal.

Expected Behavior

There should be a single monorepo-level npm script that will:

1. Perform the initial copy of docs/site, download any assets from other GitHub repos.
2. Either use symlinks or setup a filesystem watcher to automatically mirror changes from docs/site to local loopback.io clone
3. Start jekyll in a watching mode, preferably with --incremental flag, so that any updates in docs/site are quickly applied to the local website.

Alternatively, we may want to look for a different solution that will allow us to render the content in docs/site without the rest of loopback.io content. What's important: we need to configure Jekyll the same way as it's configured on loopback.io, including plugins, CSS stylesheets, etc.

See Reporting Issues for more tips on writing good issues

[bajtos]

While working on #3718, I found this issue is much worse than I thought. We are already running Jekyll in an incremental mode, but it does not seem to pick changes :(

I ended up doing a full restart whenever I want to preview my updates. Here is the command that works for me, execute it in sandbox/loopback.io directory:

$ cp -r ../../docs/site/* pages/en/lb4/ && cp -r ../../docs/site/sidebars/* _data/sidebars/ && npm start

[emonddr]

I encountered problems with this before. I enlisted the help of Biniam and Raymond. Raymond made changes somewhere (can't remember what PR it was). It seemed to work for him, but never for me.
Cannot remember the actual file that @raymondfeng updated in an attempt to fix the problem for me. It was in a program that copies documentation from one directory to another directory (I am assuming the sandbox directory).

[bajtos]

Few things we can try to speed up Jekyll build times in general: https://cloudcannon.com/tips/2017/12/08/speed-up-your-jekyll-builds/

[bajtos]

Top entries are reported by bundle exec jekyll build --profile:

_includes/sidebar_menu_list_items.liquid       |  2690 | 189959.23K | 72.797
_layouts/default.html                          |  3082 | 163866.01K | 56.138
_includes/sidebar.html                         |  3082 |  97788.82K | 46.391
_includes/sidebar_menu_list_items_trans.liquid |   392 |  39662.92K | 13.099
_includes/taglogic.html                        |    57 |   2291.83K |  8.105
_includes/custom/sidebarconfigs.html           |  3084 |     33.13K |  7.241
_layouts/page.html                             |  3081 |  24525.01K |  6.564
_includes/topnav.html                          |  3085 |  33682.15K |  5.970
_layouts/readme.html                           |   199 |   2451.83K |  3.352
posts.json                                     |     1 |   6819.10K |  2.627
sitemap.xml                                    |     1 |    279.15K |  2.129
_includes/head.html                            |  3085 |   6312.23K |  2.105
_includes/footer.html                          |  3082 |   1300.22K |  0.822
_layouts/navgroup.html                         |    79 |   1611.95K |  0.655
_includes/toc.html                             |  3075 |   3228.15K |  0.279

As mostly expected, a lot of time is spent in rendering the sidebar (139 seconds out of total 213 seconds). The article mentioned in my previous comment suggests the following optimization:

The easiest way to optimise this is to output static HTML and avoid using Liquid.
(...)
This is much faster but makes the site harder to maintain. We need the best of both worlds, the speed of static while having the flexibility of Liquid. We can achieve this with a Jekyll plugin. The plugin will generate the footer the first time it’s run then cache the result for subsequent requests.
(...)
The footer is easy to cache as is exactly the same on every page. Let’s look at something that isn’t the same on every page, the main navigation. _includes/navigation.html iterates over a data file, outputs a link and name then adds an active class if the link is the current page:
(...)
If we included this using include_cached the active class will be on the same link on every page as it will execute it once then use that version for subsequent includes. We need to move the active page logic outside the include so we can cache it properly:
(...)
From here we could rely on JavaScript/JQuery to add the active class
(...)
Or we could add a class to identify each nav item and a class to body in _layouts/default.html to identify the current page.

Considering the complexity of such solution, I think it's better to focus on previewing LB4 docs changes only and find a way how to exclude non-LB4 content from rendering.

we may want to look for a different solution that will allow us to render the content in docs/site without the rest of loopback.io content. What's important: we need to configure Jekyll the same way as it's configured on loopback.io, including plugins, CSS stylesheets, etc.