Dicussion: Abstract/modularize all the things #445

alFReD-NSH opened this Issue Mar 4, 2013 · 15 comments


None yet
4 participants

So I want to be able to generate my docpad website on a browser, but docpad comes with lot of other things rather than just the generation code. And I only need the core to be in the browser. So I'm thinking of making core a seperate module, which can be fed with files and relative paths and modules and then it outputs some files. Only that and nothing more.

So I have this proposed the interface:

  • new DocpadGenerator(config)
  • DocpadGenerator::add{File,Document,Layout}(path, file) - Will add a file to the database. The root of the path will be the src directory.
  • DocpadGenerator::removeAll() - Will remove all files from database.
  • DocpadGenerator::remove(path) - Will remove a file from database. The root of the path will be src directory.
  • DocpadGenerator::generate() - Will make docpad generator to render the files that was added. After this any file related method or render should throw an error when called since the generator becomes read-only.
  • DocpadGenerator::on(event, fn) - Will call fn on the event.
  • DocpadGenerator::renderDynamic(reqLikeObject, cb)


  • finishFile(path, file) - Will call the callback when a file was finished.
  • finish - Will call the callback when all files are finished. After this point the generator is writable. Files are not cleaned and changed files for re-rendering can be changed using addFile method.

Want to back this issue? Place a bounty on it! We accept bounties via Bountysource.


balupton commented Mar 4, 2013

What about syncing the in memory docpad database with the browser? And allowing the browser to interact with the DocPad server via a REST API?

Yeah, getting the src files from some server(or maybe something like chrome file system) and then submitting them to another. My usecase is for something like uploading to s3 and the people who can't run docpad on their machine(non-tech people without node) will be able to use it. This will save them the money of having a node server.

One thing is that, I don't want it to have many features, which will allow for customizations, I want it only render and generate files. Then other modules will handle downloading files and uploading files or syncing.

On more thoughts about this, instead of this api, we can give the control of reading files to the generator by defining file system like functions for it, that'll use them instead of the actual. This will leave some space to docpad for optimizations(for example, layouts can be lazy loaded, one layout might be needed at all).


balupton commented Mar 12, 2013

@alFReD-NSH sweet? So like instead of having the write files done inside the file model, it just emits an event writeFile that plugins can then listen to and save it to the appropriate source? This sounds like a nifty idea, we've done some exploring with it here so keen to get your feedback: https://github.com/bevry/docpad/wiki/Brainstorm:-Modularization

That'll pretty much do what i want it


balupton commented Sep 17, 2013

Renamed this from "Making the DocPad core a separate module" to "Discussion: How to abstract all the things"


balupton commented Sep 17, 2013

Pretty much chases thoughts here https://gist.github.com/chase/9bdde631df6f3c41256a from comment bevry#445 (comment) all align with the noflo rewrite proposal #600, so that's all good.

One of the questions is how should the file and document models be? And how should loading, parsing, rendering, and writing those files be? As the File class and Document class has different handling on those, with the Document class extended the default handling of the File class.

We could perhaps just have the files be a very basic data store and event emitter, so things like load, render, parse, write are just events emitted on the file data store, which is then handled by the docpad controller, and delegated to the appropriate other dependencies.


balupton commented Sep 17, 2013

It would be worthwhile to look into how the jekyll noflo implementation does this.


balupton commented Sep 17, 2013

On another note, I'm completely fine with waiting until the noflo gui is implemented (perhaps a year from now) to do this, as there are still many other things we need to get done, and I don't really want to be re-writing everything twice, instead of just twice (in the case that multiple b/c breaks happen to noflo over the next year).


mikeumus commented Sep 19, 2013

If anyone wants to start working on this now, you've got a sidekick in me. I may just start with noflo docpad plugins and be a scout of the rest of us.


Zearin commented Apr 19, 2015

Some off-the-top-of-my-head ideas for splitting up the titanic class in lib/docpad.coffee

Breaking the giant class into chunks of logically-related functionality, how about something like:

  • actions.coffee (I think “actions” are basically the commands available on the console?)
  • server.coffee
  • events.coffee
  • config/ (see #390)
    • core.coffee (or perhaps core.cson? surely there must be functionality, but I like the idea of putting as much configuration into CSON files as possible)
    • paths.coffee
    • *.coffee (others by logical grouping)
    • Perhaps a config utility that lets people query docpad’s config from the console? I’m mean more powerful than docpad info…something more like npm config <get | set | list | …>!
  • skeletons.coffee
  • env.coffee
  • template-data.coffee
  • plugins/
    • plugins.coffee
    • loader.coffee

balupton commented Apr 19, 2015

+1 good thinking, the original idea of a huge class is so people can extend the docpad class - however I doubt anyone has ever done that ever, so we can deprecate that requirement and break it out into smaller classes and eventually smaller modules


balupton commented Jun 18, 2016

Moving over to #1046

balupton closed this Jun 18, 2016

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment