bridgetownrb / bridgetown

A next-generation progressive site generator & fullstack framework, powered by Ruby
https://www.bridgetownrb.com
MIT License
1.16k stars 112 forks source link

docs: improve documentation on hooks and inflections #792

Open jclusso opened 1 year ago

jclusso commented 1 year ago

For the life of me, I can't figure out where usage of hooks go when working with them directly. A proper example would be greatly helpful here. If they belong in the initializer or a config. I figured it would be nice to have a hooks.rb file in the config folder, but I was unsuccessful in getting that to work.

https://github.com/bridgetownrb/bridgetown/blob/6ff7de5fa3de68af9ebf9221e79378a7bc144459/bridgetown-website/src/_docs/plugins/hooks.md?plain=1#L24-L28

This also leads me to having no idea how to get inflections to work. I think a full example showing where and what hook it should use would be great.

https://github.com/bridgetownrb/bridgetown/blob/6ff7de5fa3de68af9ebf9221e79378a7bc144459/bridgetown-website/src/_docs/resources.md?plain=1#L248-L255

jclusso commented 1 year ago

The second part of this can be ignored once #793 is merged.

jaredcwhite commented 1 year ago

@jclusso Thanks for calling this out. Part of the issue I think is I really dislike that hooks API, as it's a holdover from Jekyll days, and I've been trying to move away from it in various ways. I'm realizing now there's not adequate documentation on how to use hook in initializer files, which is the new preferred way to define hooks going forward outside of a Builder. It needs updating here: https://www.bridgetownrb.com/docs/configuration/initializers