Add builder cms integration guide #3357
Conversation
after docs repo migrated to Astro 2.0 and npm broke
I think I missed smth here. The way I found it a big chunk of content seemed to be missing. It was simply the line starting with 'the instructions below' ...but there were no instructions for actually creating the model?
it's mentioned in the text and i think is a good idea
because who wouldn't like to read more about `getStaticPaths()` after reading it has its own fancy scope?
it took me a second to figure out that they're not just a mistake
instead of front-loading :o)
* a note feels appropiate, as this is more of an aside * rephrased to point out a helpful resource rather than to anticipate a problem
as in every other title
|
EDIT: Please don't take any of the edits as me trying to sneak in some changes at the last minute or backpedalling on issues I marked as resolved/committed earlier. I'm especially thinking of the commits where I added notes and links to official resources (or re-added?). And of course the major edit. I tried to do my best not to re-open any major discussion and just went for the low-hanging fruit. Please direct any complaints to my hazy memory. All honest mistakes, I assure you 😁. ok, I'm done. Mostly tiny fixes, a few rephrasings and additions of notes, and one major thing where I added a section that I felt was missing ('Creating a model for a blog post'). I feel sort of weird about this, like I'm springing this on you, @sarah11918 at the last minute or I'm changing my mind about an issue we had already resolved. I honestly was kind of gobsmacked / flabbergasted (or even both) to see that this section is missing. Right now I'm thinking that I must have missed this discussion or something. I have to say - I'm still 'getting used to' how a big PR works and looks on Github (meaning I found it pretty hard to follow y'alls changes sometimes and was pretty confused as to what was happening at the end). As it is, I feel like we need some kind of section talking about creating a Builder model. Just having the instruction 'create a builder model named Right now I took the section 'Creating a model for a blog post' from my initial commit, gave it a once-over and re-added it. I feel like we need some kind of instructions, but I'm open to having this section revised. But that's probably not what you want to hear at this point 😆 I hope it doesn't hurt too much :o) |
|
No worries! Admittedly, this one took a LONG time, and for sure my memory was hazy when I finally got back to it last week. 😅 I appreciate the close, careful look. And I'll have some time this evening to give it another once-over just to make sure you didn't "sneak in" too much! 😉 (Side note: when you start to type I'll get through this tonight, and I'm confident we'll merge by the end of the week! 🙌 |
There was a problem hiding this comment.
I suspect you really just don't want this PR to end.... 😂
Thanks for a bunch of those fixes! I checked each commit and am glad you found some stuff that got past me!
There are three remaining things that I still really don't like, and I've explained why. I do feel strongly enough to point them out to you, but not enough to block if you're absolutely determined, after hearing my side. 😅 In that spirit, I've tried to be quite clear/direct about where I'm coming from! Because we're so close to the end and we should have all our cards on the table to make these final decisions!
I will now let you take that info, with no doubt as to my feelings on these, and make your final decisions! When you tell me you're done, then it's ready. 🚀
|
|
||
| 1. In your Builder dashboard, go into your **`blogpost`** model. Under **Show More Options**, select **Edit Webhooks** at the bottom. | ||
| 2. Add a new webhook by clicking on **Webhook**. Paste the URL generated by your hosting provider into the **Url** field. | ||
| 3. Click on **Show Advanced** under the URL field and toggle the option to select **Disable Payload**. With the payload disabled, Builder sends a simple POST request to your hosting provider. Otherwise, the payload might overwhelm your hosting provider, as your site grows. Click **Done** to save this selection. |
There was a problem hiding this comment.
Otherwise, the payload might overwhelm your hosting provider
OK, I can see this is a change I made, that you reverted and added back. I'm not gonna lie, I really dislike this. 😄
The first time I read this, I thought, "If I need to toggle this option on, because otherwise Builder is going to bork my hosting provider, a) why isn't it on by default and b) uh... why did Builder build something that might break my hosting?"
So, it's not just about being explanatory. It's also about, "Is something going to distract the reader as they're trying to complete the steps?" This absolutely distracted me, and worse, gave me a bad impression of Builder. (There may be very good reasons behind all this, but again, that would be more that you'd need to put here that are not relevant to just following the instructions and getting it working.) That's why I had a more neutral statement "do this" here.
But, it's your show! I just want to make you aware of that!
| If you are using a JavaScript framework (e.g. Svelte, Vue, or React) in your Astro project you can use [one of Builder's integrations](https://www.builder.io/m/integrations) as an alternative to making raw fetch calls through the REST API. | ||
| ::: | ||
|
|
||
| :::tip[API explorer] |
There was a problem hiding this comment.
Did you really think you were going to sneak TWO ADJACENT TIPS past me? 😂
This is visually very distracting, and I remember that I moved this because the link is at the bottom of the page already, and, we don't want to inject random troubleshooting (implying they should be having problems) in the middle of the instructions.
This is another "strongly dislike; bad practice" (on multiple fronts!) that you're trying to get me to accept in my docs. 😄
| :::caution | ||
| This guide relies on these fields being exactly like this and later code will not run correctly if these fields don't exist, are empty, or the titles misspelled. | ||
| ::: |
There was a problem hiding this comment.
| :::caution | |
| This guide relies on these fields being exactly like this and later code will not run correctly if these fields don't exist, are empty, or the titles misspelled. | |
| ::: |
Suggest remove this first caution.
As in my other comment, two notes/asides and ESPECIALLY two cautions next to each other are really bad practice. I strongly feel this one is unneeded. It's basically saying: Here are instructions. WARNING YOU HAVE TO FOLLOW THEM. (That's what instructions are for? You follow them?)
Something like adding to around line 68 with "creating the REQUIRED fields exactly as specified below", i.e. working this idea inline that fields are not forgiving, can't be blank etc. is a better strategy.
It targets the reader at the moment they are performing that step, rather than at the end a huge caution that will make people go, "Oh crap, maybe I should go back and check" and definitely breaks flow when it won't matter for most: they will have followed the instructions you gave them.
I know all instructions are subject to user error, but I prefer not to make people second guess themselves or worry unnecessarily, nor clutter the flow if we can help it. People who make a mistake will simply have to go back and recheck, and everyone else can move along.
|
Ok, I reverted and relented :). All with good reasons. This looks good to go! I'm still curious what happened with that 'creating a builder model' step. But since I don't see a comment here, I take it y'all approving of re-adding this section. @sarah11918 I left our conversations unresolved cuz I had stuff to say and didn't want it to get buried. You can go ahead and resolve them (or MERGE this baby) at your leisure. PS. Did You mean that 🥲 smiley when You talked about |
|
Well, I think there's nothing left to say here but... WELCOME TO TEAM DOCS (finally)! 🥳 Thanks for everything, @Return180bpm! |
Co-authored-by: Yan Thomas <61414485+Yan-Thomas@users.noreply.github.com> Co-authored-by: Sarah Rainsberger <sarah@rainsberger.ca> Co-authored-by: Reuben Tier <64310361+TheOtterlord@users.noreply.github.com> Co-authored-by: Elian ☕️ <hello@elian.codes>
|
Holy cow, it's a great day! Thanks y'all!!! I feel we did some good work in a good way here! |
What kind of changes does this PR include?
Description
⚡️ New ideas
Some ideas I put into this guide that I haven't seen in the other CMS recipes I looked at:
Curious to hear your thoughts on these!
💭 Considerations
After many edits I decided to leave out the section Integrating with Astro that's at the beginning of the other CMS guides (Contentful, Ghost, Storyblok) and instead jump straight into building a blog and show the integration through a concrete example.
The reason for this is that it got complicated with Builder's specific
preview URLfeature. This seemed like it surely had to be part of the Integrating section. To test this you also need to explain how to create a content entry. So far so good. But then in the very next section Creating your blog you're doing the same things: setting up apreview URLand creating content... so you put backlinks to the Integrating section... or repeat instructions... and it seems a little 🤡. At some point I just decided to avoid these problems and make one continuous recipe for setting up a blog.🧤 Also
💜 Thank You to all the nice folks on the Discord who answered my questions!