Implement live preview fully for site.json by jonahtanjz · Pull Request #1529 · MarkBind/markbind

jonahtanjz · 2021-03-30T11:06:31Z

What is the purpose of this pull request?

Overview of changes:
Resolves #48.

A follow up to #1514, which supported live preview for the pages attribute. This PR will support live preview for all the other attributes in site.json. A server restart is no longer required for these changes to be reflected when serving the site through markbind serve. Since most of the attributes in site.json (except baseUrl, pages and deploy) will affect majority of the pages, hence all pages will be regenerated when any of these attributes (except those listed above) is modified.

For the style attribute, if a bootswatch theme is specified/added, its bootstrap.min.css theme file will overwrite the existing file and all pages are rebuilt. Similarly, if a bootswatch theme is removed, the default bootstrap.min.css, which is located at core-web/asset/css will overwrite the existing file.

Anything you'd like to highlight / discuss:
Would appreciate if you can let me know if I missed any attributes or if any of the attributes (other than those listed above) that does not require all pages to be rebuilt when it is modified.

Testing instructions:

Serve a MarkBind site using markbind serve
Open and edit the any of the attributes in site.json
Live preview should be updated to reflect the latest changes

Proposed commit message: (wrap lines at 72 characters)
Implement live preview for site.json

When attributes other than pages in site.json are modified, a server
restart is required to reflect the changes on the live preview. This can
become a hassle to the user as they will need to frequently restart
the server when trying out different site configuration.

Let's support live preview for all the attributes in site.json so that the
latest changes can be reflected without restarting the server.

Checklist: ☑️

Updated the documentation for feature additions and enhancements
Added tests for bug fixes or features
Linked all related issues
No blatantly unrelated changes
Pinged someone for a review!

raysonkoh

Neat code! Would it be possible to add some tests for this?

…eload of site.json

raysonkoh · 2021-04-05T05:29:14Z

+  copyBootstrapTheme(toCopyDefault) {
    const { theme } = this.siteConfig;
-    if (!theme || !_.has(SUPPORTED_THEMES_PATHS, theme)) {
+    if (!toCopyDefault && (!theme || !_.has(SUPPORTED_THEMES_PATHS, theme))) {


Minor nit: would it be possible to remove the need for the toCopyDefault? It seems like if toCopyDefault is True and theme is defined, then it would copy the theme's file instead of the default file.

What do you think of the following flow:
If theme is undefined, then we will assume that the caller wants to copy the default bootstrap theme.
Else check if theme is a supported theme and copy over the relevant theme file.

What do you think of the following flow:
If theme is undefined, then we will assume that the caller wants to copy the default bootstrap theme.
Else check if theme is a supported theme and copy over the relevant theme file.

Hmm I think this will make a redundant copy of the default theme if no theme is specified in the initial build. Maybe I can rename toCopyDefault to isRebuild so that it is more concise. What do you think?

Hmm I think this will make a redundant copy of the default theme if no theme is specified in the initial build.

Hmm, I see. In that case, should we log a warning / throw exception for the case toCopyDefault = True && theme?

Maybe I can rename toCopyDefault to isRebuild so that it is more concise. What do you think?

I am fine with either name 😄 .

Sorry I think I wasn't too clear about this 😅. I think I should rename toCopyDefault as it is a little misleading. This parameter should only be True if it is a rebuild (site.json was modified).

What do you think about this check:

if ((!isRebuild && !theme) || (theme && !_.has(SUPPORTED_THEMES_PATHS, theme))) { return _.noop; }

It will be a noop during the first build if theme is not specified/theme is invalid. Else, if it is subsequent rebuild/theme is specified and valid, then, it will copy over the relevant theme's file (including default theme if !theme).

Yes that looks good! Can you also add a comment next to this check to indicate its purpose for future reference?

Alright I've updated this and also added the comment :)

ang-zeyu

Thanks! @jonahtanjz

Since most of the attributes in site.json (except baseUrl, pages and deploy) will affect majority of the pages, hence all pages will be regenerated when any of these attributes (except those listed above) is modified.

Hmm shouldn't baseUrl be included? ({{ baseUrl }} variable changes).
Although, there might not be much value in supporting this in serve mode (since baseUrl would really only change for deployment), we can document this exception if so.

Plugins would need some special handling as well like themes and ignore. (see PluginManager)

(optional) You can also consider implementing the fourth part of #1495 first as well to ensure all pages have the same updated copy of SiteConfig's properties

ang-zeyu · 2021-04-05T13:18:08Z

+        || !_.isEqual(oldSiteConfig.style, this.siteConfig.style)
+        || !_.isEqual(oldSiteConfig.externalScripts, this.siteConfig.externalScripts)
+        || !_.isEqual(oldSiteConfig.globalOverride, this.siteConfig.globalOverride)
+        || !_.isEqual(oldSiteConfig.ignore, this.siteConfig.ignore)


👀 what's this for?

This is to check if any of these configs have changed and if they have changed, would require a rebuild of all pages.

(ignore in particular) Shouldn't be necessary I think; ignore is only used down the line for link validation warnings

Ahh ok. I was under the impression that if a page is dependent on an asset that is later added to ignore, then that entire page will have to be rebuilt. Might have misunderstood the functionality of ignore here 😅

jonahtanjz · 2021-04-06T05:56:13Z

@ang-zeyu Thanks for review :)

Hmm shouldn't baseUrl be included? ({{ baseUrl }} variable changes).
Although, there might not be much value in supporting this in serve mode (since baseUrl would really only change for deployment), we can document this exception if so.

Since {{ baseUrl }} is a variable change then I supposed it would make sense to be included so that the behaviour would be consistent.

Plugins would need some special handling as well like themes and ignore. (see PluginManager)

For this portion were you referring to running collectBaseUrl() method? Since this is the only part where a new PluginManager is created and then subsequently assigned to all the new pages that will be rebuilt.

ang-zeyu

Since {{ baseUrl }} is a variable change then I supposed it would make sense to be included so that the behaviour would be consistent.

@jonahtanjz its common and ok to forgo supporting something if the use case is practically zero, especially since baseUrl needs extra special care.

I might be missing a use case though. Could get a user opinion from @damithc here. (would live-reload for baseUrl parameter in site config be useful?)

For this portion were you referring to running collectBaseUrl() method? Since this is the only part where a new PluginManager is created and then subsequently assigned to all the new pages that will be rebuilt.

Was thinking a more targeted approach that dosen't rerun the baseUrl collection. (can do a simple refactor / extraction of method here)
On that note (good catch), External/LayoutManager's copies in collectBaseUrl() should be refreshed as well.

ang-zeyu · 2021-04-06T06:11:51Z

+        || !_.isEqual(oldSiteConfig.style, this.siteConfig.style)
+        || !_.isEqual(oldSiteConfig.externalScripts, this.siteConfig.externalScripts)
+        || !_.isEqual(oldSiteConfig.globalOverride, this.siteConfig.globalOverride)
+        || !_.isEqual(oldSiteConfig.ignore, this.siteConfig.ignore)


(ignore in particular) Shouldn't be necessary I think; ignore is only used down the line for link validation warnings

damithc · 2021-04-06T06:26:27Z

I might be missing a use case though. Could get a user opinion from @damithc here. (would live-reload for baseUrl parameter in site config be useful?)

I think it is OK not support live preview support for changes to the baseUrl as it is a very rare case. Just need to specify it clearly.

jonahtanjz · 2021-04-06T09:42:09Z

@ang-zeyu @raysonkoh I've updated the PR to include the exception of not supporting live reload for baseUrl in the UG and refresh the managers when necessary. Let me know if I've missed out anything else :)

ang-zeyu · 2021-04-06T12:09:04Z

+      || !_.isEqual(oldSiteConfig.plugins, this.siteConfig.plugins)
+      || !_.isEqual(oldSiteConfig.pluginsContext, this.siteConfig.pluginsContext)
+      || !_.isEqual(oldSiteConfig.disableHtmlBeautify, this.siteConfig.disableHtmlBeautify)
+      || !_.isEqual(oldSiteConfig.intrasiteLinkValidation, this.siteConfig.intrasiteLinkValidation)) {


missing timeZone / locale / style as well - should / could we just remove the checks here as well?
I feel there's not much value in further narrowing it down since buildManagers isn't very costly

I feel there's not much value in further narrowing it down since buildManagers isn't very costly

Alright since there's not much value for the checks as it is not costly, then buildManagers will be called for every full rebuild and whenever ignore is modified. I've updated the PR accordingly.

jonahtanjz · 2021-04-06T14:54:30Z

@ang-zeyu Thanks for the catch and suggestions. I've updated the PR to remove the further checks for buildManagers and also moved the isGlobalConfigModified method into handlePageReload.

ang-zeyu · 2021-04-07T08:09:45Z


+<box type="warning">
+
+Note: `baseUrl` does not support live reload as it should not change in `markbind serve` mode.


Let's update the definition here as well with this https://deploy-preview-1529--markbind-master.netlify.app/userguide/glossary

Minor wording nit:

Suggested change

Note: `baseUrl` does not support live reload as it should not change in `markbind serve` mode.

Note: `baseUrl` does not support live preview as there is no use case for changing it in during `markbind serve`.

Otherwise, Lgtm! 👍

Let's wait and see if @raysonkoh has anything to add

ang-zeyu · 2021-04-07T08:13:28Z

+    if (isGlobalConfigModified() || !_.isEmpty(addedPages) || !_.isEmpty(removedPages)) {
      await this.removeAsset(removedPages);
+      this.buildManagers();
      await this._rebuildSourceFiles();


Additional remark (no action needed):

EDIT: After looking around at the other handlers (addHandler and removeHandler), it seems all pages should be rebuilt if the added/removed file is a page/dependency of page.

This has been existing behaviour for a long while already but can probably be made into an issue 🙂

Per #1514's comment, the number of dependent pages generated / regenerated can be improved later as well.

Alright. I'll open an issue for this and the previous discussion.

jonahtanjz · 2021-04-07T10:51:28Z

@ang-zeyu @raysonkoh I've updated the PR accordingly :)

ang-zeyu · 2021-04-10T05:27:01Z

 **_Live preview_** is:
 - Regeneration of affected content upon any change to <tooltip content="`.md`, `.mbd`, `.mbdf`, `.njk` files ... anything your content depends on!">source files</tooltip>, then reloading the updated site in the Browser.

- Regeneration will also occur upon any modification to attributes in `site.json` with the exception of [`baseUrl`](siteJsonFile.md#baseurl-no-live-preview).


I've re-added this portion

raysonkoh · 2021-04-11T07:12:46Z

LGTM 👍

jonahtanjz added 2 commits March 30, 2021 00:24

Add live reload for ignore attribute

c935a84

Implement live reload for all attributes in site.json

072a669

raysonkoh reviewed Apr 4, 2021

View reviewed changes

Comment thread packages/core/src/Site/index.js

Comment thread packages/core/src/Site/index.js Outdated

Modify copyBootswatchTheme method to copy default theme during live r…

15f5fd5

…eload of site.json

raysonkoh reviewed Apr 5, 2021

View reviewed changes

jonahtanjz added 2 commits April 5, 2021 16:06

Update after review

7dba59d

Update comment

3cd5628

ang-zeyu reviewed Apr 5, 2021

View reviewed changes

Comment thread packages/core/src/Site/index.js

ang-zeyu reviewed Apr 6, 2021

View reviewed changes

Update after review

4de7de5

ang-zeyu reviewed Apr 6, 2021

View reviewed changes

jonahtanjz added 2 commits April 6, 2021 22:46

Update after review

2a33660

Fix paramter for handleIgnore

a4b3a7a

ang-zeyu reviewed Apr 7, 2021

View reviewed changes

jonahtanjz added 3 commits April 7, 2021 18:36

Update after review

d0d7da2

Update definition of live preview

c20a5b3

Remove empty line

b51eca3

ang-zeyu reviewed Apr 10, 2021

View reviewed changes

Add site.json live preview in glossary

7052df0

ang-zeyu approved these changes Apr 10, 2021

View reviewed changes

ang-zeyu added this to the v3.0 milestone Apr 10, 2021

jonahtanjz mentioned this pull request Apr 11, 2021

Enhance regeneration of pages during live preview #1543

Open

raysonkoh approved these changes Apr 11, 2021

View reviewed changes

raysonkoh merged commit a56d3d7 into MarkBind:master Apr 11, 2021

jonahtanjz changed the title ~~Implement live preview for site.json~~ Implement full live preview for site.json Apr 11, 2021

jonahtanjz changed the title ~~Implement full live preview for site.json~~ Implement live preview fully for site.json Apr 11, 2021

ang-zeyu mentioned this pull request Apr 12, 2021

Setup e2e testing for live preview features #1544

Open


		<box type="warning">

		Note: `baseUrl` does not support live reload as it should not change in `markbind serve` mode.

	Note: `baseUrl` does not support live reload as it should not change in `markbind serve` mode.
	Note: `baseUrl` does not support live preview as there is no use case for changing it in during `markbind serve`.

Conversation

jonahtanjz commented Mar 30, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

raysonkoh left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raysonkoh Apr 5, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonahtanjz Apr 5, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ang-zeyu left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jonahtanjz commented Apr 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ang-zeyu left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

damithc commented Apr 6, 2021

Uh oh!

jonahtanjz commented Apr 6, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

jonahtanjz commented Apr 6, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jonahtanjz commented Apr 7, 2021

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

raysonkoh commented Apr 11, 2021

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

jonahtanjz commented Mar 30, 2021 •

edited

Loading

raysonkoh Apr 5, 2021 •

edited

Loading

jonahtanjz Apr 5, 2021 •

edited

Loading

ang-zeyu left a comment •

edited

Loading

jonahtanjz commented Apr 6, 2021 •

edited

Loading