WIP: new AI tutorial

[evilnick]

This just sketches out the steps at the moment, posted for initial feedback on structure and elements.

[netlify]

✅ Deploy Preview for n8n-docs ready!

Name	Link
🔨 Latest commit	45686bb
🔍 Latest deploy log	https://app.netlify.com/sites/n8n-docs/deploys/67a0bb1ee092970008c4274f
😎 Deploy Preview	https://deploy-preview-2799--n8n-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

Overall readability score: 44.87 (🔴 -0.03)

File	Readability
intro-tutorial.md	66.57 (🔴 -9.36)

View detailed metrics

🟢 - Shows an increase in readability
🔴 - Shows a decrease in readability

File	Readability	FRE	GF	ARI	CLI	DCRS
intro-tutorial.md	66.57	55.54	9.45	10.6	10.32	7.2
	🔴 -9.36	🔴 -3.15	🔴 -2.12	🔴 -1.5	🔴 -0.53	🔴 -0.71

Averages:

	Readability	FRE	GF	ARI	CLI	DCRS
Average	44.87	35.73	11.37	14.57	14.19	8.42
	🔴 -0.03	🔴 -0.01	🟢 +0	🔴 -0.01	🟢 +0	🟢 +0

View metric targets

Metric	Range	Ideal score
Flesch Reading Ease	100 (very easy read) to 0 (extremely difficult read)	60
Gunning Fog	6 (very easy read) to 17 (extremely difficult read)	8 or less
Auto. Read. Index	6 (very easy read) to 14 (extremely difficult read)	8 or less
Coleman Liau Index	6 (very easy read) to 17 (extremely difficult read)	8 or less
Dale-Chall Readability	4.9 (very easy read) to 9.9 (extremely difficult read)	6.9 or less

[evilnick]

This adds a further style for an 'info' themed expandable section, similar to the existing 'details' one. The styling is taken from the default for material, but we can debate appropriate colours etc.

[imchairmanm]

Got it. Yeah, I think changes to the styling are fine. I think if we're going with green, it'd be good to try to riff off of the green we already use for the theme. That being said, with the website style changes coming, it might not matter all too much.

[evilnick]

Convenience link for the preview- https://deploy-preview-2799--n8n-docs.netlify.app/advanced-ai/intro-tutorial/

[evilnick]

The titles of these explanations will be edited to reflect the contents

[evilnick]

seemed more useful to establish a pattern of using our embedded workflow styles for these. I have a slight niggle with scrolling (if you are scrolling the text and you happen to land on one of these, you proceed to scroll the workflow rather than the text) and maybe these ones are simple enough that screenshots would be fine?
The main advantage here I see is that automating the generation of these parts could be fairly trivial and not involve filling up the repo with more images

[imchairmanm]

I think you're right about using the workflow component to render these. That might not have been an option when this was initially written.

I might not have understood your explanation above fully, but is there a reason you decided to define these in this way? Here, you're referencing the n8n-demo component directly, percent encoding the workflow, and define it inline. The way we typically do this is to put the workflow file in the docs/_workflows directory and then use the workflowDemo function to reference it like this. Are there advantages to doing it the way you do here?

[evilnick]

Ah, no particular reason. I didn't find any appropriate examples. I guess the only advantage of embedding everything is that it makes it easier to test ( a subject for another day), but I will redo these for now then and maybe update the wiki to include it

[evilnick]

Hmmm... is the standard here that it opens the code in a new tab? I think I prefer the forum style where it reveals the code block under the diagram and has a neat copy button. Out of scope for this work but maybe we should discuss that

[imchairmanm]

You can find the function details here. Currently, for local files, it does just show the file, but there's no reason we can't adjust. Not sure if you saw this already, but these are the specific docs for the demo component that this uses.

[evilnick]

This workflow uses the frame so it can be easily copied (if someone made a mistake or couldn't get those theirs to work. Could this work as a template instead?

[imchairmanm]

By "as a template" do you mean published here or something else?

[evilnick]

I'm not sure how the distinction works, but when using a template, rather than importing, you get a splash screen indicating what things you need to add (credentials), which I think would be better for this usage

[imchairmanm]

Got it, yeah. For templates published in that library, we have a separate function that renders those, which is a step up from what you can do with a raw template.

[evilnick]

when we have extra tutorials to build on this we would link them here

[evilnick]

It's always good to remind people of what they did, it's a reinforced learning thing that really works!

[imchairmanm]

Yeah, that's definitely a good touch for tutorials. Good call out.

[imchairmanm]

One thing I wonder about with this framing is whether we're introducing branching complexity here where we might prefer a beginner tutorial to be more streamlined and predictable. Maybe we could say something like "we're using OpenAI with this tutorial. Once you have it working, it's easy to swap out the model for your preferred choice" or something. Maybe it doesn't materially impact things though if the services are all equally reliable. I don't have strong feelings, but wanted to mention it.

[evilnick]

Yes, it's a good point. I just wanted to highlight that people could pretty much use whatever they chose and namecheck a few things (e.g. DeepSeek probably helps SEO atm). I'll have a think