Staticman: Add better support for other static site generators

[eduardoboucas]

Currently, Staticman will look for a _config.yml configuration file on the root of the repository, which is specific to Jekyll.

I'd like us to support other engines, so I see two options:

1. Allow requests to specify the path to the configuration file within the options object (ugly, potential security issues?)
2. Move the staticman config block to its own file

Option 2 seems more appropriate, but what should the name for the new config file be? Jekyll doesn't include files prefixed with an underscore in the generated site — is this a convention used by other engines as well? If not, is there a filename we could use that would cause this effect in all (or, at least, in the majority) of engines?

@biilmann would you be able to advise on this?

(As a side note, this will be a breaking change, so I'll have to release a v2endpoint for entries)

[MoOx]

The _ convention is not used by Phenomic. I have to admit I found the _ convention looks like a dirty hack :)
Any file would works for Phenomic since everything is explicit (no magic on files based on their names yet).

Note: To avoid breaking change, you can support old way, provides new way via config file and warn user that rely on old way, this will provide a nice UX :)

[eduardoboucas]

To be clear, the _ convention used by Jekyll is so that the files will not be part of the generated output. Just a small detail.

And yes, the plan is to add a v2 endpoint to the API with support for the new config format whilst still supporting the current method in v1.

Warning users of deprecation is not as straightforward, since we don't have a UI. Perhaps include a note in the commit message is an option.

Thanks for your input!

[MoOx]

I know the convention. It can even leads to "bug" by default (if you don't use jekyll but have _ files on your github pages, those will be removed... You have to add a .nojekyll files so you can rely and those).

[eduardoboucas]

Oh, wow. That's ugly indeed.

I'm thinking the new config file could simply be staticman.yml in the root of the repository. For simplicity reasons, we need to support a single format for the config file, and YAML seems to be the most human-friendly choice.

[mdxprograms]

I'm definitely in favor of doing a specific config file for staticman.
Also YAML is probably the most readable format I've seen for config files in general.

[jonschlinkert]

responding to https://twitter.com/staticmanapp/status/766633703468593152

We're planning to directly support .assemblerc.json when generate generator support is added, but assemble can support any config format or filename via plugins. (fwiw, assemble can practically run any other static site generator as a plugin, so we can go with the flow on whatever you decide).

Allow requests to specify the path to the configuration file within the options object

I'm not familiar with staticman yet, but this seems like a better choice IMO. Then you can restrict formats to .json and .yml or just one. Which leaves the rest to implementors.

[eduardoboucas]

I'm not familiar with staticman yet, but this seems like a better choice IMO. Then you can restrict formats to .json and .yml or just one. Which leaves the rest to implementors.

The only thing I'm not comfortable with about this option is that you're allowing end-users to decide which file in the repository serves as the config. And sure, you're limited to the files that exist within the repository, but you could effectively load different configs than what the site admin has intended.

[jonschlinkert]

you could effectively load different configs than what the site admin has intended.

Maybe I'm missing something. Isn't it the content of the config file that would matter? Even if you restrict the name of the file to something specific, what would stop user from loading bad configs, undesired content, or abusing features (unintentionally or otherwise). Using a specific file name won't do anything to change this.

Just a thought. Again, it wouldn't really matter to assemble, we could use whatever convention you decide on.

[eduardoboucas]

To be clear, what we're talking about here is letting each request decide, using a field in the form, which file to load. This would be done like this:

<form action="https://api.staticman.net/...">
  <input type="hidden" name="options[config]" value="custom-config.yml">
</form>

Imagine you have a second file (another-config.yml) in the repository (maybe inside a node_modules directory or something else that's out of your control). Nothing stops a user from changing the form so that another-config.yml will be used to feed Staticman, and not the file that the site admin intended.

Yes, the situations where a vulnerability could occur seem slim: the repository would have to be open, so that people could look around for files, and you'd need another file with the right structure to fit the config block that Staticman uses. But it could happen.

Does that make sense?

Even though the alternative means a breaking change (renaming the fixed file config from _config.yml to staticman.yml), it does seem more robust than the above. At least we know for sure the config that will be used.

[eduardoboucas]

This has been addressed in #18. When using the API with v2, Staticman will look for a staticman.yml file in the root of the repository. Since the file is now for exclusive use of Staticman, there is no need to nest the options inside a staticman object.

_v1:_

# _config.yml

staticman:
  allowedFields: ['one', 'two']

_v2:_

# staticman.yml

allowedFields: ['one', 'two']

If anyone wants to give it a test, please let me know of any issues so I can address before making this official and add to the documentation.

Thanks! 👍

[eduardoboucas]

Closing in favour of #32. Will release with v2 of the API shortly.