Generate default configuration documentation programmatically

[ivantsepp]

This is a PR just to generate some discussion about @zdroid's comment in #2102. What I've done here is create a liquid tag that outputs the default configuration for Jekyll. But I'm not too happy about this solution since this exposes a tag to all Jekyll users that they wouldn't use. So again, this PR is just a conversation starter and not really a complete work. Several alternatives I've been thinking about are:

• Extract this tag into its own gem and add it in the gemspec just like jekyll-coffeescript or jekyll-sass-converter. So at least the code is somewhere else. But it's the same issue as before because the tag is still publicly available.
• Make this a plugin and generate docs offline before pushing to gh-pages branch (since you can't run plugins when using Github to parse Jekyll).
• Expose Configuration::DEFAULTS to liquid variables. Maybe site.default_config?
• Instead of listing the defaults, link to the Github source code.
• Just keep doing what is done now which is synchronizing the doc with Jekyll source manually.

Thoughts?

[zlatanvasovic]

Good job. I hope @jekyll team will help you with this.

[parkr]

How about a rake task for this? It could generate this string and output it into an include then the docs/configuration page could include it.

The only thing generally useful is the way to print hashes as a nicely-formatted string, like array_to_sentence_string

[zlatanvasovic]

Rake task is better idea, as it will be optional.

2014-05-26 16:38 GMT+02:00 Parker Moore notifications@github.com:

How about a rake task for this? It could generate this string and output
it into an include then the docs/configuration page could include it.

The only thing generally useful is the way to print hashes as a
nicely-formatted string, like array_to_sentence_string

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/2452#issuecomment-44194468
.

Zlatan Vasović - ZDroid

[ivantsepp]

A rake task is a pretty good idea. I can work on that! I think I'll make a new task and add that to site:publish's dependency just like site:history. Question though, when does rake site:publish get executed? Is there a commit hook on the repo or do the maintainers run the task?

[parkr]

We run it manually. It'd be nice to have for rake site:preview, too.

[parkr]

Throw up a new PR for that when you have it. Thanks!