Allow live reloading for plugin defined sources

[ang-zeyu]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Documentation update
• [x] Enhancement to an existing feature

Resolves#913

What is the rationale for this request?
To allow plugins to define their own source file types and corresponding
source files that will be watched and updated by the live preview appropriately.

What changes did you make? (Give an overview)

• Plugins can a new attribute in its exports: getSources
  • getSources: Allows plugins to return an array of source file paths to watch
• Similar to Page.prototype.preRender, Page.prototype.getSources runs getSources all plugins just before
  preRender.
• Updated relavant test files

Provide some example code that this change will affect:

(Plantumlpluginfile)module.exports={
...,getSources: (content)=>{// Add all src attributes in <puml> tags to watch listconst$=cheerio.load(content,{xmlMode: true});return$('puml').map((i,tag)=>tag.attribs.src).get();},

Is there anything you'd like reviewers to focus on?
Whether a callback style solution would be better ( a 5th parameter to preRender / postRender that contains callbacks plugins can use ), since in the long run one may find plugins requiring more and more functionality.

Testing instructions:
I added a <puml> tag, and an <include> tag ( including testPlantUML.md )
to the test site. Changing any of the source files ( e.g. activity.puml ) should
cause the affected pages to reload when serving the page.

Proposed commit message: (wrap lines at 72 characters)
Allow live reloading for plugin defined sources

This allows plugins to define a custom list of source files and file
types for the page to be watched, allowing live reload to rebuild
the affected page.

[acjh]

Why _.castArray? getSources should return an array.

[ang-zeyu]

So that a single source file could be returned as well,
should I enforce returning an array instead?

[acjh]

Yes, since getSources is plural.

[ang-zeyu]

Updated getSources to require returning array instead as per method naming

[yamgent]

Seems good implementation-wise, comments are mostly about wordings:

[yamgent]

The indentation of the method body is off. Only the comment line was in the correct indentation

[yamgent]

Hence, to add custom source files to watch, MarkBind allows defining an additional method in the plugin. implement the ``getSources`` method:

Prefer being more direct in documentations so that it is easier for the reader to process.

[yamgent]

any -> the current? The use of "any" makes it seems like this call is not tied to any pages.

[yamgent]

Returns an array of source file paths to watch. Called before a Markdown file'spreRender function is called.

[yamgent]

Seems a bit wrong to say "page sources", since puml files are not really pages? Maybe "file sources"?

[ang-zeyu]

Hi, thanks for looking through it! I've updated the relavant lines.

On another note, I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

[yamgent]

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

[ang-zeyu]

Updated, will squash if its fine!

[acjh]

I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

Actually, it was intentionally undocumented by @jamos-tay as of #714 (comment):

I needed access to Page.headingIndexingLevel, so I added a 4th parameter, page which is the Page object itself... Other plugins might need access to page config so this could be helpful

I'm thinking we can use this for internal plugins, but don't document it in user docs, since we don't want to expose authors to the implementation

[ang-zeyu]

Actually, it was intentionally undocumented by @jamos-tay as of [#714 (comment)]

Thanks for the heads up!

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. Regarding the original concern for the change ( passing the entire Page being dangerous ), I could include a warning in the docs about includedFiles since it is used in Site.proto.updateSiteData(). Still, its a subsection to add into the docs which means more details for the user to read. Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

What's the take on this? 😮

[acjh]

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. ... Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

The concern isn't that it is tedious to document. Rather, ideally, plugins should purely process content rather than use variables from and depend on the (filesystem-aware) implementation of Markbind CLI.

[ang-zeyu]

Noted on the intended usage of plugins. Thanks!

Reverted the 'documentation updates' and squashed

[ang-zeyu]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Documentation update
• [x] Enhancement to an existing feature

Resolves#913

What is the rationale for this request?
To allow plugins to define their own source file types and corresponding
source files that will be watched and updated by the live preview appropriately.

What changes did you make? (Give an overview)

• Plugins can a new attribute in its exports: getSources
  • getSources: Allows plugins to return an array of source file paths to watch
• Similar to Page.prototype.preRender, Page.prototype.getSources runs getSources all plugins just before
  preRender.
• Updated relavant test files

Provide some example code that this change will affect:

(Plantumlpluginfile)module.exports={
...,getSources: (content)=>{// Add all src attributes in <puml> tags to watch listconst$=cheerio.load(content,{xmlMode: true});return$('puml').map((i,tag)=>tag.attribs.src).get();},

Is there anything you'd like reviewers to focus on?
Whether a callback style solution would be better ( a 5th parameter to preRender / postRender that contains callbacks plugins can use ), since in the long run one may find plugins requiring more and more functionality.

Testing instructions:
I added a <puml> tag, and an <include> tag ( including testPlantUML.md )
to the test site. Changing any of the source files ( e.g. activity.puml ) should
cause the affected pages to reload when serving the page.

Proposed commit message: (wrap lines at 72 characters)
Allow live reloading for plugin defined sources

This allows plugins to define a custom list of source files and file
types for the page to be watched, allowing live reload to rebuild
the affected page.

[acjh]

Why _.castArray? getSources should return an array.

[ang-zeyu]

So that a single source file could be returned as well,
should I enforce returning an array instead?

[acjh]

Yes, since getSources is plural.

[ang-zeyu]

Updated getSources to require returning array instead as per method naming

[yamgent]

Seems good implementation-wise, comments are mostly about wordings:

[yamgent]

The indentation of the method body is off. Only the comment line was in the correct indentation

[yamgent]

Hence, to add custom source files to watch, MarkBind allows defining an additional method in the plugin. implement the ``getSources`` method:

Prefer being more direct in documentations so that it is easier for the reader to process.

[yamgent]

any -> the current? The use of "any" makes it seems like this call is not tied to any pages.

[yamgent]

Returns an array of source file paths to watch. Called before a Markdown file'spreRender function is called.

[yamgent]

Seems a bit wrong to say "page sources", since puml files are not really pages? Maybe "file sources"?

[ang-zeyu]

Hi, thanks for looking through it! I've updated the relavant lines.

On another note, I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

[yamgent]

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

[ang-zeyu]

Updated, will squash if its fine!

[acjh]

I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

Actually, it was intentionally undocumented by @jamos-tay as of #714 (comment):

I needed access to Page.headingIndexingLevel, so I added a 4th parameter, page which is the Page object itself... Other plugins might need access to page config so this could be helpful

I'm thinking we can use this for internal plugins, but don't document it in user docs, since we don't want to expose authors to the implementation

[ang-zeyu]

Actually, it was intentionally undocumented by @jamos-tay as of [#714 (comment)]

Thanks for the heads up!

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. Regarding the original concern for the change ( passing the entire Page being dangerous ), I could include a warning in the docs about includedFiles since it is used in Site.proto.updateSiteData(). Still, its a subsection to add into the docs which means more details for the user to read. Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

What's the take on this? 😮

[acjh]

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. ... Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

The concern isn't that it is tedious to document. Rather, ideally, plugins should purely process content rather than use variables from and depend on the (filesystem-aware) implementation of Markbind CLI.

[ang-zeyu]

Noted on the intended usage of plugins. Thanks!

Reverted the 'documentation updates' and squashed

[ang-zeyu]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Documentation update
• [x] Enhancement to an existing feature

Resolves#913

What is the rationale for this request?
To allow plugins to define their own source file types and corresponding
source files that will be watched and updated by the live preview appropriately.

What changes did you make? (Give an overview)

• Plugins can a new attribute in its exports: getSources
  • getSources: Allows plugins to return an array of source file paths to watch
• Similar to Page.prototype.preRender, Page.prototype.getSources runs getSources all plugins just before
  preRender.
• Updated relavant test files

Provide some example code that this change will affect:

(Plantumlpluginfile)module.exports={
...,getSources: (content)=>{// Add all src attributes in <puml> tags to watch listconst$=cheerio.load(content,{xmlMode: true});return$('puml').map((i,tag)=>tag.attribs.src).get();},

Is there anything you'd like reviewers to focus on?
Whether a callback style solution would be better ( a 5th parameter to preRender / postRender that contains callbacks plugins can use ), since in the long run one may find plugins requiring more and more functionality.

Testing instructions:
I added a <puml> tag, and an <include> tag ( including testPlantUML.md )
to the test site. Changing any of the source files ( e.g. activity.puml ) should
cause the affected pages to reload when serving the page.

Proposed commit message: (wrap lines at 72 characters)
Allow live reloading for plugin defined sources

This allows plugins to define a custom list of source files and file
types for the page to be watched, allowing live reload to rebuild
the affected page.

[acjh]

Why _.castArray? getSources should return an array.

[ang-zeyu]

So that a single source file could be returned as well,
should I enforce returning an array instead?

[acjh]

Yes, since getSources is plural.

[ang-zeyu]

Updated getSources to require returning array instead as per method naming

[yamgent]

Seems good implementation-wise, comments are mostly about wordings:

[yamgent]

The indentation of the method body is off. Only the comment line was in the correct indentation

[yamgent]

Hence, to add custom source files to watch, MarkBind allows defining an additional method in the plugin. implement the ``getSources`` method:

Prefer being more direct in documentations so that it is easier for the reader to process.

[yamgent]

any -> the current? The use of "any" makes it seems like this call is not tied to any pages.

[yamgent]

Returns an array of source file paths to watch. Called before a Markdown file'spreRender function is called.

[yamgent]

Seems a bit wrong to say "page sources", since puml files are not really pages? Maybe "file sources"?

[ang-zeyu]

Hi, thanks for looking through it! I've updated the relavant lines.

On another note, I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

[yamgent]

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

[ang-zeyu]

Updated, will squash if its fine!

[acjh]

I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

Actually, it was intentionally undocumented by @jamos-tay as of #714 (comment):

I needed access to Page.headingIndexingLevel, so I added a 4th parameter, page which is the Page object itself... Other plugins might need access to page config so this could be helpful

I'm thinking we can use this for internal plugins, but don't document it in user docs, since we don't want to expose authors to the implementation

[ang-zeyu]

Actually, it was intentionally undocumented by @jamos-tay as of [#714 (comment)]

Thanks for the heads up!

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. Regarding the original concern for the change ( passing the entire Page being dangerous ), I could include a warning in the docs about includedFiles since it is used in Site.proto.updateSiteData(). Still, its a subsection to add into the docs which means more details for the user to read. Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

What's the take on this? 😮

[acjh]

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. ... Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

The concern isn't that it is tedious to document. Rather, ideally, plugins should purely process content rather than use variables from and depend on the (filesystem-aware) implementation of Markbind CLI.

[ang-zeyu]

Noted on the intended usage of plugins. Thanks!

Reverted the 'documentation updates' and squashed

[ang-zeyu]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Documentation update
• [x] Enhancement to an existing feature

Resolves#913

What is the rationale for this request?
To allow plugins to define their own source file types and corresponding
source files that will be watched and updated by the live preview appropriately.

What changes did you make? (Give an overview)

• Plugins can a new attribute in its exports: getSources
  • getSources: Allows plugins to return an array of source file paths to watch
• Similar to Page.prototype.preRender, Page.prototype.getSources runs getSources all plugins just before
  preRender.
• Updated relavant test files

Provide some example code that this change will affect:

(Plantumlpluginfile)module.exports={
...,getSources: (content)=>{// Add all src attributes in <puml> tags to watch listconst$=cheerio.load(content,{xmlMode: true});return$('puml').map((i,tag)=>tag.attribs.src).get();},

Is there anything you'd like reviewers to focus on?
Whether a callback style solution would be better ( a 5th parameter to preRender / postRender that contains callbacks plugins can use ), since in the long run one may find plugins requiring more and more functionality.

Testing instructions:
I added a <puml> tag, and an <include> tag ( including testPlantUML.md )
to the test site. Changing any of the source files ( e.g. activity.puml ) should
cause the affected pages to reload when serving the page.

Proposed commit message: (wrap lines at 72 characters)
Allow live reloading for plugin defined sources

This allows plugins to define a custom list of source files and file
types for the page to be watched, allowing live reload to rebuild
the affected page.

[acjh]

Why _.castArray? getSources should return an array.

[ang-zeyu]

So that a single source file could be returned as well,
should I enforce returning an array instead?

[acjh]

Yes, since getSources is plural.

[ang-zeyu]

Updated getSources to require returning array instead as per method naming

[yamgent]

Seems good implementation-wise, comments are mostly about wordings:

[yamgent]

The indentation of the method body is off. Only the comment line was in the correct indentation

[yamgent]

Hence, to add custom source files to watch, MarkBind allows defining an additional method in the plugin. implement the ``getSources`` method:

Prefer being more direct in documentations so that it is easier for the reader to process.

[yamgent]

any -> the current? The use of "any" makes it seems like this call is not tied to any pages.

[yamgent]

Returns an array of source file paths to watch. Called before a Markdown file'spreRender function is called.

[yamgent]

Seems a bit wrong to say "page sources", since puml files are not really pages? Maybe "file sources"?

[ang-zeyu]

Hi, thanks for looking through it! I've updated the relavant lines.

On another note, I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

[yamgent]

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

[ang-zeyu]

Updated, will squash if its fine!

[acjh]

I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

Actually, it was intentionally undocumented by @jamos-tay as of #714 (comment):

I needed access to Page.headingIndexingLevel, so I added a 4th parameter, page which is the Page object itself... Other plugins might need access to page config so this could be helpful

I'm thinking we can use this for internal plugins, but don't document it in user docs, since we don't want to expose authors to the implementation

[ang-zeyu]

Actually, it was intentionally undocumented by @jamos-tay as of [#714 (comment)]

Thanks for the heads up!

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. Regarding the original concern for the change ( passing the entire Page being dangerous ), I could include a warning in the docs about includedFiles since it is used in Site.proto.updateSiteData(). Still, its a subsection to add into the docs which means more details for the user to read. Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

What's the take on this? 😮

[acjh]

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. ... Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

The concern isn't that it is tedious to document. Rather, ideally, plugins should purely process content rather than use variables from and depend on the (filesystem-aware) implementation of Markbind CLI.

[ang-zeyu]

Noted on the intended usage of plugins. Thanks!

Reverted the 'documentation updates' and squashed

[ang-zeyu]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Documentation update
• [x] Enhancement to an existing feature

Resolves#913

What is the rationale for this request?
To allow plugins to define their own source file types and corresponding
source files that will be watched and updated by the live preview appropriately.

What changes did you make? (Give an overview)

• Plugins can a new attribute in its exports: getSources
  • getSources: Allows plugins to return an array of source file paths to watch
• Similar to Page.prototype.preRender, Page.prototype.getSources runs getSources all plugins just before
  preRender.
• Updated relavant test files

Provide some example code that this change will affect:

(Plantumlpluginfile)module.exports={
...,getSources: (content)=>{// Add all src attributes in <puml> tags to watch listconst$=cheerio.load(content,{xmlMode: true});return$('puml').map((i,tag)=>tag.attribs.src).get();},

Is there anything you'd like reviewers to focus on?
Whether a callback style solution would be better ( a 5th parameter to preRender / postRender that contains callbacks plugins can use ), since in the long run one may find plugins requiring more and more functionality.

Testing instructions:
I added a <puml> tag, and an <include> tag ( including testPlantUML.md )
to the test site. Changing any of the source files ( e.g. activity.puml ) should
cause the affected pages to reload when serving the page.

Proposed commit message: (wrap lines at 72 characters)
Allow live reloading for plugin defined sources

This allows plugins to define a custom list of source files and file
types for the page to be watched, allowing live reload to rebuild
the affected page.

[acjh]

Why _.castArray? getSources should return an array.

[ang-zeyu]

So that a single source file could be returned as well,
should I enforce returning an array instead?

[acjh]

Yes, since getSources is plural.

[ang-zeyu]

Updated getSources to require returning array instead as per method naming

[yamgent]

Seems good implementation-wise, comments are mostly about wordings:

[yamgent]

The indentation of the method body is off. Only the comment line was in the correct indentation

[yamgent]

Hence, to add custom source files to watch, MarkBind allows defining an additional method in the plugin. implement the ``getSources`` method:

Prefer being more direct in documentations so that it is easier for the reader to process.

[yamgent]

any -> the current? The use of "any" makes it seems like this call is not tied to any pages.

[yamgent]

Returns an array of source file paths to watch. Called before a Markdown file'spreRender function is called.

[yamgent]

Seems a bit wrong to say "page sources", since puml files are not really pages? Maybe "file sources"?

[ang-zeyu]

Hi, thanks for looking through it! I've updated the relavant lines.

On another note, I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

[yamgent]

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

[ang-zeyu]

Updated, will squash if its fine!

[acjh]

I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

Actually, it was intentionally undocumented by @jamos-tay as of #714 (comment):

I needed access to Page.headingIndexingLevel, so I added a 4th parameter, page which is the Page object itself... Other plugins might need access to page config so this could be helpful

I'm thinking we can use this for internal plugins, but don't document it in user docs, since we don't want to expose authors to the implementation

[ang-zeyu]

Actually, it was intentionally undocumented by @jamos-tay as of [#714 (comment)]

Thanks for the heads up!

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. Regarding the original concern for the change ( passing the entire Page being dangerous ), I could include a warning in the docs about includedFiles since it is used in Site.proto.updateSiteData(). Still, its a subsection to add into the docs which means more details for the user to read. Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

What's the take on this? 😮

[acjh]

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. ... Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

The concern isn't that it is tedious to document. Rather, ideally, plugins should purely process content rather than use variables from and depend on the (filesystem-aware) implementation of Markbind CLI.

[ang-zeyu]

Noted on the intended usage of plugins. Thanks!

Reverted the 'documentation updates' and squashed

[ang-zeyu]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Documentation update
• [x] Enhancement to an existing feature

Resolves#913

What is the rationale for this request?
To allow plugins to define their own source file types and corresponding
source files that will be watched and updated by the live preview appropriately.

What changes did you make? (Give an overview)

• Plugins can a new attribute in its exports: getSources
  • getSources: Allows plugins to return an array of source file paths to watch
• Similar to Page.prototype.preRender, Page.prototype.getSources runs getSources all plugins just before
  preRender.
• Updated relavant test files

Provide some example code that this change will affect:

(Plantumlpluginfile)module.exports={
...,getSources: (content)=>{// Add all src attributes in <puml> tags to watch listconst$=cheerio.load(content,{xmlMode: true});return$('puml').map((i,tag)=>tag.attribs.src).get();},

Is there anything you'd like reviewers to focus on?
Whether a callback style solution would be better ( a 5th parameter to preRender / postRender that contains callbacks plugins can use ), since in the long run one may find plugins requiring more and more functionality.

Testing instructions:
I added a <puml> tag, and an <include> tag ( including testPlantUML.md )
to the test site. Changing any of the source files ( e.g. activity.puml ) should
cause the affected pages to reload when serving the page.

Proposed commit message: (wrap lines at 72 characters)
Allow live reloading for plugin defined sources

This allows plugins to define a custom list of source files and file
types for the page to be watched, allowing live reload to rebuild
the affected page.

[acjh]

Why _.castArray? getSources should return an array.

[ang-zeyu]

So that a single source file could be returned as well,
should I enforce returning an array instead?

[acjh]

Yes, since getSources is plural.

[ang-zeyu]

Updated getSources to require returning array instead as per method naming

[yamgent]

Seems good implementation-wise, comments are mostly about wordings:

[yamgent]

The indentation of the method body is off. Only the comment line was in the correct indentation

[yamgent]

Hence, to add custom source files to watch, MarkBind allows defining an additional method in the plugin. implement the ``getSources`` method:

Prefer being more direct in documentations so that it is easier for the reader to process.

[yamgent]

any -> the current? The use of "any" makes it seems like this call is not tied to any pages.

[yamgent]

Returns an array of source file paths to watch. Called before a Markdown file'spreRender function is called.

[yamgent]

Seems a bit wrong to say "page sources", since puml files are not really pages? Maybe "file sources"?

[ang-zeyu]

Hi, thanks for looking through it! I've updated the relavant lines.

On another note, I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

[yamgent]

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

[ang-zeyu]

Updated, will squash if its fine!

[acjh]

I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

Actually, it was intentionally undocumented by @jamos-tay as of #714 (comment):

I needed access to Page.headingIndexingLevel, so I added a 4th parameter, page which is the Page object itself... Other plugins might need access to page config so this could be helpful

I'm thinking we can use this for internal plugins, but don't document it in user docs, since we don't want to expose authors to the implementation

[ang-zeyu]

Actually, it was intentionally undocumented by @jamos-tay as of [#714 (comment)]

Thanks for the heads up!

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. Regarding the original concern for the change ( passing the entire Page being dangerous ), I could include a warning in the docs about includedFiles since it is used in Site.proto.updateSiteData(). Still, its a subsection to add into the docs which means more details for the user to read. Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

What's the take on this? 😮

[acjh]

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. ... Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

The concern isn't that it is tedious to document. Rather, ideally, plugins should purely process content rather than use variables from and depend on the (filesystem-aware) implementation of Markbind CLI.

[ang-zeyu]

Noted on the intended usage of plugins. Thanks!

Reverted the 'documentation updates' and squashed

[ang-zeyu]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Documentation update
• [x] Enhancement to an existing feature

Resolves#913

What is the rationale for this request?
To allow plugins to define their own source file types and corresponding
source files that will be watched and updated by the live preview appropriately.

What changes did you make? (Give an overview)

• Plugins can a new attribute in its exports: getSources
  • getSources: Allows plugins to return an array of source file paths to watch
• Similar to Page.prototype.preRender, Page.prototype.getSources runs getSources all plugins just before
  preRender.
• Updated relavant test files

Provide some example code that this change will affect:

(Plantumlpluginfile)module.exports={
...,getSources: (content)=>{// Add all src attributes in <puml> tags to watch listconst$=cheerio.load(content,{xmlMode: true});return$('puml').map((i,tag)=>tag.attribs.src).get();},

Is there anything you'd like reviewers to focus on?
Whether a callback style solution would be better ( a 5th parameter to preRender / postRender that contains callbacks plugins can use ), since in the long run one may find plugins requiring more and more functionality.

Testing instructions:
I added a <puml> tag, and an <include> tag ( including testPlantUML.md )
to the test site. Changing any of the source files ( e.g. activity.puml ) should
cause the affected pages to reload when serving the page.

Proposed commit message: (wrap lines at 72 characters)
Allow live reloading for plugin defined sources

This allows plugins to define a custom list of source files and file
types for the page to be watched, allowing live reload to rebuild
the affected page.

[acjh]

Why _.castArray? getSources should return an array.

[ang-zeyu]

So that a single source file could be returned as well,
should I enforce returning an array instead?

[acjh]

Yes, since getSources is plural.

[ang-zeyu]

Updated getSources to require returning array instead as per method naming

[yamgent]

Seems good implementation-wise, comments are mostly about wordings:

[yamgent]

The indentation of the method body is off. Only the comment line was in the correct indentation

[yamgent]

Hence, to add custom source files to watch, MarkBind allows defining an additional method in the plugin. implement the ``getSources`` method:

Prefer being more direct in documentations so that it is easier for the reader to process.

[yamgent]

any -> the current? The use of "any" makes it seems like this call is not tied to any pages.

[yamgent]

Returns an array of source file paths to watch. Called before a Markdown file'spreRender function is called.

[yamgent]

Seems a bit wrong to say "page sources", since puml files are not really pages? Maybe "file sources"?

[ang-zeyu]

Hi, thanks for looking through it! I've updated the relavant lines.

On another note, I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

[yamgent]

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

[ang-zeyu]

Updated, will squash if its fine!

[acjh]

I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

Actually, it was intentionally undocumented by @jamos-tay as of #714 (comment):

I needed access to Page.headingIndexingLevel, so I added a 4th parameter, page which is the Page object itself... Other plugins might need access to page config so this could be helpful

I'm thinking we can use this for internal plugins, but don't document it in user docs, since we don't want to expose authors to the implementation

[ang-zeyu]

Actually, it was intentionally undocumented by @jamos-tay as of [#714 (comment)]

Thanks for the heads up!

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. Regarding the original concern for the change ( passing the entire Page being dangerous ), I could include a warning in the docs about includedFiles since it is used in Site.proto.updateSiteData(). Still, its a subsection to add into the docs which means more details for the user to read. Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

What's the take on this? 😮

[acjh]

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. ... Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

The concern isn't that it is tedious to document. Rather, ideally, plugins should purely process content rather than use variables from and depend on the (filesystem-aware) implementation of Markbind CLI.

[ang-zeyu]

Noted on the intended usage of plugins. Thanks!

Reverted the 'documentation updates' and squashed

[ang-zeyu]

What is the purpose of this pull request? (put "X" next to an item, remove the rest)

• [x] Documentation update
• [x] Enhancement to an existing feature

Resolves#913

What is the rationale for this request?
To allow plugins to define their own source file types and corresponding
source files that will be watched and updated by the live preview appropriately.

What changes did you make? (Give an overview)

• Plugins can a new attribute in its exports: getSources
  • getSources: Allows plugins to return an array of source file paths to watch
• Similar to Page.prototype.preRender, Page.prototype.getSources runs getSources all plugins just before
  preRender.
• Updated relavant test files

Provide some example code that this change will affect:

(Plantumlpluginfile)module.exports={
...,getSources: (content)=>{// Add all src attributes in <puml> tags to watch listconst$=cheerio.load(content,{xmlMode: true});return$('puml').map((i,tag)=>tag.attribs.src).get();},

Is there anything you'd like reviewers to focus on?
Whether a callback style solution would be better ( a 5th parameter to preRender / postRender that contains callbacks plugins can use ), since in the long run one may find plugins requiring more and more functionality.

Testing instructions:
I added a <puml> tag, and an <include> tag ( including testPlantUML.md )
to the test site. Changing any of the source files ( e.g. activity.puml ) should
cause the affected pages to reload when serving the page.

Proposed commit message: (wrap lines at 72 characters)
Allow live reloading for plugin defined sources

This allows plugins to define a custom list of source files and file
types for the page to be watched, allowing live reload to rebuild
the affected page.

[acjh]

Why _.castArray? getSources should return an array.

[ang-zeyu]

So that a single source file could be returned as well,
should I enforce returning an array instead?

[acjh]

Yes, since getSources is plural.

[ang-zeyu]

Updated getSources to require returning array instead as per method naming

[yamgent]

Seems good implementation-wise, comments are mostly about wordings:

[yamgent]

The indentation of the method body is off. Only the comment line was in the correct indentation

[yamgent]

Hence, to add custom source files to watch, MarkBind allows defining an additional method in the plugin. implement the ``getSources`` method:

Prefer being more direct in documentations so that it is easier for the reader to process.

[yamgent]

any -> the current? The use of "any" makes it seems like this call is not tied to any pages.

[yamgent]

Returns an array of source file paths to watch. Called before a Markdown file'spreRender function is called.

[yamgent]

Seems a bit wrong to say "page sources", since puml files are not really pages? Maybe "file sources"?

[ang-zeyu]

Hi, thanks for looking through it! I've updated the relavant lines.

On another note, I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

[yamgent]

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

[ang-zeyu]

Updated, will squash if its fine!

[acjh]

I noticed that usingPlugins.md does not have documentation for the fourth parameter, config, even though it is used in the preRender and postRender functions. I've correspondingly also omitted it from getSources for now.

Was this an intentional decision to hide some of the implementation details? If not, I could update it as well.

It was probably an oversight. Feel free to add it in.

Actually, it was intentionally undocumented by @jamos-tay as of #714 (comment):

I needed access to Page.headingIndexingLevel, so I added a 4th parameter, page which is the Page object itself... Other plugins might need access to page config so this could be helpful

I'm thinking we can use this for internal plugins, but don't document it in user docs, since we don't want to expose authors to the implementation

[ang-zeyu]

Actually, it was intentionally undocumented by @jamos-tay as of [#714 (comment)]

Thanks for the heads up!

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. Regarding the original concern for the change ( passing the entire Page being dangerous ), I could include a warning in the docs about includedFiles since it is used in Site.proto.updateSiteData(). Still, its a subsection to add into the docs which means more details for the user to read. Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

What's the take on this? 😮

[acjh]

Since @jamos-tay ended up going with the approach @marvinchin suggested, there isn't too much to document though. ... Other properties aside though, rootPath, sourcePath and resultPath seem to be quite useful for plugins.

The concern isn't that it is tedious to document. Rather, ideally, plugins should purely process content rather than use variables from and depend on the (filesystem-aware) implementation of Markbind CLI.

[ang-zeyu]

Noted on the intended usage of plugins. Thanks!

Reverted the 'documentation updates' and squashed