Document Analog SFC Usage

[crutchcorn]

I noticed that there were no docs for using the .analog extension.

This PR adds in initial documentation for the Analog SFC format. It denotes the extension as being experimental, but otherwise outlines how to use the extension

PR Checklist

Please check if your PR fulfills the following requirements:

• [x] The commit message follows our guidelines: https://github.com/analogjs/analog/blob/main/CONTRIBUTING.md#-commit-message-guidelines
• [x] Tests for the changes have been added (for bug fixes / features)
• [x] Docs have been added / updated (for bug fixes / features)

PR Type

What kind of change does this PR introduce?

• [ ] Bugfix
• [ ] Feature
• [ ] Code style update (formatting, local variables)
• [ ] Refactoring (no functional changes, no api changes)
• [ ] Build related changes
• [ ] CI related changes
• [x] Documentation content changes
• [ ] Other... Please describe:

Does this PR introduce a breaking change?

• [ ] Yes
• [x] No

[optional] What gif best describes this PR or how it makes you feel?

[crutchcorn]

@joshuamorony thanks for the review! I'll update the doc tomorrow with the suggested changes.

How do you feel about the code sample at the start and any other contents?

[joshuamorony]

@joshuamorony thanks for the review! I'll update the doc tomorrow with the suggested changes.

How do you feel about the code sample at the start and any other contents?

I'll give this another more thorough read later (excited to see the PR and wanted to leave some quick thoughts) but if I'm going to nitpick the example a bit I think I'd like to see it touch on most of the core .analog concepts, so perhaps:

• Something that uses import attributes to add an Analog component to metadata
• Something that uses import attributes to add a provider to the metadata
• Perhaps using defineMetadata to define some styles using the host property as this is something that requires defineMetadata specifically

But I think it's a good example and I like the idea of just having a quick/simple todo example. Perhaps we could also link to the ng-app example from the repo which is sort of an ugly kitchen-sink of all different sorts of .analog features. This was named ng-app when this was initially released as the .ng format, so if we are going to link to it maybe now would be a good time to rename that.

[joshuamorony]

Also probably a good time to bring up the Analog SFC naming which is what is being used now (by the Analog team as well), but imo I don't think it makes much sense, on two counts mainly:

• SFC isn't a unique feature .analog brings as this can already be done in Angular normally
• .analog isn't restricted to SFC anyway, you can still define styles/template externally with .analog

Personally, I'd prefer "Analog Format", "Analog Components", or something else, but I might be in the minority here

[luishcastroc]

Should we also mention (for better DX) that there's a webstorm plugin coming? Or that would be an ad 😅

[crutchcorn]

@luishcastroc not just coming, it's here for 2024.1!

Lemme add that to the # Usage heading alongside VSCode

[crutchcorn]

All code review comments have been addressed!

@joshuamorony - my concern with a more complex example is that it may scare away other folks. I vote we link to the ng-app as a more in-depth example and rename the directory; but not in this PR.

[netlify[bot]]

✅ Deploy Preview for analog-blog ready!

Name	Link
🔨 Latest commit	1c4f4893877413fc62580cdcf5983ff1a3165f60
🔍 Latest deploy log	https://app.netlify.com/sites/analog-blog/deploys/660e78e35c97920008c3254c
😎 Deploy Preview	https://deploy-preview-987--analog-blog.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.

[netlify[bot]]

✅ Deploy Preview for analog-app ready!

Name	Link
🔨 Latest commit	1c4f4893877413fc62580cdcf5983ff1a3165f60
🔍 Latest deploy log	https://app.netlify.com/sites/analog-app/deploys/660e78e3e6934a00087d296d
😎 Deploy Preview	https://deploy-preview-987--analog-app.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.

[netlify[bot]]

✅ Deploy Preview for analog-ng-app ready!

Name	Link
🔨 Latest commit	1c4f4893877413fc62580cdcf5983ff1a3165f60
🔍 Latest deploy log	https://app.netlify.com/sites/analog-ng-app/deploys/660e78e3e7178000089121cc
😎 Deploy Preview	https://deploy-preview-987--analog-ng-app.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.

[crutchcorn]

@brandonroberts I've addressed all of the feedback you've left 😄 Should be ready for a re-review

[netlify[bot]]

✅ Deploy Preview for analog-docs ready!

Name	Link
🔨 Latest commit	1c4f4893877413fc62580cdcf5983ff1a3165f60
🔍 Latest deploy log	https://app.netlify.com/sites/analog-docs/deploys/660e78e312b3dc0008be120c
😎 Deploy Preview	https://deploy-preview-987--analog-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.