Updated Core Concepts

[FredKSchott]

Ready for review! Three new pages that create the beginning of our "Core Concepts" guide:

1. Why Astro (New!)
2. MPAs vs. SPAs (New! Replacing Astro vs. X)
3. Component Islands (Reformatted from the current "Partial Hydration" page)

There's a forth "Technical Explanation" page that I started, but it's lower priority than these and unrelated, so it can come in a follow-up PR if we have time.

[netlify]

✅ Deploy Preview for astro-docs-2 ready!

Name	Link
🔨 Latest commit	bf906f2
🔍 Latest deploy log	https://app.netlify.com/sites/astro-docs-2/deploys/62df82ae6706790008f90bb2
😎 Deploy Preview	https://deploy-preview-893--astro-docs-2.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 settings.

[yanthomasdev]

Wow, amazing work Fred! I was looking forward to reviewing this PR from the moment I saw it as a draft.💜

I added a couple of nits and suggestions 🙌

[sarah11918]

Whew! I love where this ended up, @FredKSchott !

Here are my comments and suggestions after a pass at editing!

[sarah11918]

This could be a candidate for tabs, if you wanted.

[FredKSchott]

I tried but couldn't get very far! I think we'll need MDX for this:

<!-- didn't render properly, probably an md-astro bug -->
<Tabs client:visible sharedStore="ui-frameworks">
    <Fragment slot="tab.npm">npm</Fragment>
    <Fragment slot="panel.npm">
        <pre><code set:html={`# create a new project with npm\nnpm create astro@latest`} /></pre>
    </Fragment>
</Tabs>

[yanthomasdev]

The Sharing State page uses an Astro component as a wrapper of the Tabs component, I think it's safe to add a package managers tab component, it can be really handy in some cases!

You can copy and paste this and it will work perfectly (you just have to change the single quotes for backticks):

// src/components/tabs/PackageManagerTabs.astro
---
import Tabs from './Tabs'
---

<Tabs client:visible sharedStore="package-managers">
  <Fragment slot="tab.npm">npm</Fragment>
  <Fragment slot="tab.pnpm">pnpm</Fragment>
  <Fragment slot="tab.yarn">Yarn</Fragment>

  <Fragment slot="panel.npm"><slot name="npm" /></Fragment>
  <Fragment slot="panel.pnpm"><slot name="pnpm" /></Fragment>
  <Fragment slot="panel.yarn"><slot name="yarn" /></Fragment>
</Tabs>

---
// page.md
< !--- >
setup: |
  import PackageManagerTabs from '~/components/tabs/PackageManagerTabs.astro'
---

<PackageManagerTabs>
  <Fragment slot="npm">
  '''shell
  npm create astro@latest
  '''
  </Fragment>
  <Fragment slot="pnpm">
  '''shell
  pnpm create astro@latest
  '''
  </Fragment>
  <Fragment slot="yarn">
  '''shell
  yarn create astro
  '''
  </Fragment>
</PackageManagerTabs>

[sarah11918]

Suggested change

	There are three main differences to be aware of when comparing MPAs vs. SPAs:
	There are three main differences between MPAs and SPAs that developers should note:

Again, personal preference, but I think the 3 main diffs between is a concise statement, and the being aware of really belongs to WHO those differences matters to.

"that developers should be aware of:"
"that developers choosing a framework should be aware of:"
"that make a difference to developers (choosing a framework):"
"of note to developers choosing a framework for a project:"

Or a different angle entirely:

"Examine these three key differences between MPAs and SPAs before choosing a framework for your next project:"
"Not sure which site architecture to choose for your project? Here are three key differences you should understand:"
"Trying to decide between MPA and SPA? Consider the following three key differences:"

[FredKSchott]

Just did a quick pass, thank you so much for the feedback @yan-thomas and @sarah11918!

I left a few larger items to return to later when I next have some time.

[sarah11918]

@FredKSchott Just made PR to this branch ( #985 ) that updates the link on the Shared State page (from partial-hydration to islands). That seems to be the only Docs page internally linking to the current (soon to be old) partial-hydration page that isn't a part of your PR here.

[FredKSchott]

Thanks for the feedback everyone! In the interest of NWTWWHB I'm going to merge this so that the content gets out there. Happy to do more revisions in future PRs!