@narration-sd/sanity-astro-presentation NPM

sanity-astro-presentation

n.b. this is preliminary, a sketch to get started after removing the 'ground rules' alpha doc here earlier. Patience will be rewarded, and on the docs site rewrite....

Demonstration Apps

This repository is now moving on to a Beta version, with two example apps to explore capabilities, with the key feature being full Sanity Presentation Studio editing on both:

blog -- is an implementation of an upgrade to the sanity-astro-clean-template, with its easy on-ramps Astro-style TypeScript approach, including easy images-in-portable-text as well, particularly for WordPress etc. conversions.
authors -- this is a more fully featured employment, including Composable Content, Pictures as well as Images, Lists, and Lists of Cards as a basis of today's website designs.

Package and deployments.

sanity-astro-presentation is fully deployable, and has been deployed, held back to a very early version for present, as the real development is included here in the /packages folder.

This local package is used in the apps via a '*' version in package.json, which works fine on app deployments to Vercel and Netlify.

Sample content

For each app, there's a /content folder, with the same sample content seen in demos, so that you can easily try out in dev or build.

You'll just need to load one on a Sanity Project you've provided with its id, and create the Viewer key you'll need tof the .env file build off the example.

Deployment flavours

On both Netlify and Vercel, a 'editor' site and a 'production' site are each deployed -- fron the same source code.

The only difference between static and editable versions is one environmental variable. There is one additional variable available, to remove token warnings -- perhaps this ought to be telescoped.

App menu versions

There's a develompent menu at the top of both examples, when you ae in the example pages. This allows selection of three flavors:

Author or Post, the default app, with inline components
'Author-Wrap or Post-Wrap', an alternate source version, with wrap-style components
'Writer or Post-Orig' - this is a pure Astro code, for reference with no Presentation-capability components at all

Components, what do inline and wrap mean?

Let's have a look at the three flavours overall, as then the distinctions, and probably advantages, will be clear.

Astro code alone

Here's a simple line of Astro code, implementing say a title for an image:

<h1 class="post__title">{post.title}</h1>

This straightforward, having a styling class, and a field item from a presumed data retrieved normally above as post.

Inline components

With Inline components for Presentation in this package, the look is quite similar:

<h1 class="post__title">{<SAText dataField="title" live={live} />}</h1>

Here the HTML type and class remain, the field description is simpler, and is within an SAText component, with only an added live tag.

SAText (Sanity Astro Text) enables smooth transparency between live operation where Presentation is invoked, and otherwise, which will give an unassisted deployment site.

That deployment is SSR for development, so that a refresh of the site will show the edited content fully 'live', and SSG when the environmental is set, giving a fully static production site.

Wrap-style components

In many cases, the inline style might be well appreciated, as it gives Astro page code as compact and in the same shape as for a site without any Presentation, Visual Editing features.

On the other hand, some developers may prefer to only convert a few visuals on a page to Presentation -- or as a first step, to become familiar.

In this case, we have a way preserved from original work to do this exactly. There's an alternate version of the components which are used by wrapping the Astro code line, leaving it the one to operate when Presentation isn't bein gused.

That coding looks like this, for the example as above:

<SAText el="h1" dataField="title" class="post__title" live={live} >
  <h1 class="post__title">{post.title}</h1>
</SAText>

Now the component takes the same styling and type as the wrapped pure Astro, and is indistiguishable from it, which holds true for all the component types.

Wrap-style is just as simple as inline, only a bit more verbose and interrupting of the shape of original Astro code. You can use either, and even combine them, according to what you'd like at a time.

Astro components for Presentation

All the components provided for you to use are implemented in Astro.

They're self-contained and no React coding is ever required to use them.

Both versions, in-line and wrap, are in the library provided, which we'll discuss next.

Things go smoothly also when you reach the edge of what they provide and we'll get into that shortly.

Provided Code Organization

This may appear a little unusual, but the sense in it will become clear.

The basis package, sanity-astro-presentation, is fully deployable on NPM, and would be used as usual by installing it.
the library, /lib, appears at the top of the monorepo form. It is except for one area, entirely owned by the package, so that it could be updated by simple copy-paste.

We'll discuss later why the library is arranged this way, but it has to do with two factors:

that Astro's 'islands' for active components give great advantages, but don't allow some commonly applied React forms
that it can be very handy to see the code for each of the provided components, to extend wherever desired to add components of your own.

And that's all we need to concern with, as far as architecture, unless for persons especially interested.

What about extending abilities, and where would you want to?

The provided components should handle many of the common elements you put in web pages.

The exception case is when you want to provide a List of a complex component type -- that pattern shown in the authors demo, where a List of Cards operates as nicely in Presentation as when usually displayed.

There is a very interesting 'trick' to this, in that what you'd provide in that case is small, and nearly identical to what you'd write -- or did write -- in Astro to make the card.

That's because Astro code actually is simply a nicely improved version of JSX -- and JSX is the 'nice' part everyone likes about React for combining HTML and simple JavaScript in web pages.

JSX/Astro touches none of the problem aspects, which there are certainly, in React itself. Those are all taken care of for you, in the Sanity Astro Presentation package.

We'll describe later just how you'd easily add your Card or other complex List item, but it is easy -- just a few name changes mainly from equivalent Astro code, which you'd copy over as a basis.