Docs: Detail creation of custom registries

[pixeldesu]

This PR picks up the "Creating custom registries" bullet point from #2256

While writing this, I found that in the undertaker README, registry() is partially explained already, but I felt that just copy-pasting wasn't enough and the document here is a bit more thorough on what's exactly required or happening.

I also decided to link to all of the PoC registries that have been created in the organization beforehand, so people have some more starting points.

[phated]

@pixeldesu WOW! This is amazing!!! Thank you for adapting the undertaker README for the wider gulp audience.

I'm wondering if you could adapt https://github.com/gulpjs/undertaker#sharing-tasks and https://github.com/gulpjs/undertaker#sharing-functionalities for the audience as well? Those seem really important for explaining how you'd perform those use cases with a custom registry.

Once we get this landed, I'll restructure it into an "advanced" section for our website (which will be our first!).

[pixeldesu]

@phated Thanks for the feedback, didn't really expect it to be this well received! 😄

I could definitely wrangle the two Undertaker sections into the document as well, I'm just thinking about a structure for that now.

Maybe a "Use Cases" section? I think the examples here are actually thorough enough, I would just adjust them to use Gulp/Gulp exports instead of Undertaker, of course.

So the final structure afterwards would be

Creating Custom Registries

• Registry Structure (I guess I'll probably even drop the Registry here, it seems redundant, now looking at it)
• Registration
• Methods
• Use Cases
• Examples

[phated]

Yeah, I think that is perfect actually!

What if the top 2 sections were flipped?

1. Registration (maybe use one of the examples as the import)
2. Creating a Registry (What do you think of this name?)
3. Methods
4. Use Cases
5. Examples

One thing I just remembered is that there are "not implemented" references to custom registries in the gulp documentation, could you update those links as well? That would help me have a good diff of where the references are.

[pixeldesu]

What if the top 2 sections were flipped?

Hmmm. Considering the topic is the creation of custom registries, first handling the structure, which is then registered makes a bit more sense in terms of order. I was conflicted about this myself, but registering already existing registries is already explained in the registry() docs pretty much.

One thing I just remembered is that there are "not implemented" references to custom registries in the gulp documentation, could you update those links as well? That would help me have a good diff of where the references are.

I'll try to look for those and adjust them as necessary!

[phated]

Hmmm. Considering the topic is the creation of custom registries, first handling the structure, which is then registered makes a bit more sense in terms of order.

👍 Solid logic. I agree with your decision 😄

[pixeldesu]

@phated done!

As mentioned, I took the examples as given, just adjusted them to be for Gulp specifically! Also, I only found a single reference to the page on the registry() API page itself and removed the reference, it should now be resolved over the front matter ID anyway.

If there's anything else, just mention it!

[phated]

I committed some style changes and changed the location. Going to get this merged and fit in into the website.

[phated]

Thanks for all the work here @pixeldesu! This has been a great help 😄

[phated]

This is live now! https://gulpjs.com/docs/en/advanced/creating-custom-registries