DOCS: WIP - Examples and Template page example for review

[aFuzzyBear]

This is a WIP of the Examples page, to view the page would be at the url ('localhost/template') - there is not sidebar access to this page at the present moment as it is a WIP and awaiting adjudication on its composure

Changes

-Examples.astro
This is a component file that parses the template data from (./src/templates.ts) and outputs them onto small 'cards'
Each card has the following structure:
Title
Blurb
Command
Links to Github and if there is an online demo then the scope to add those links as well.

-template.astro
This is serving as the page template for the Templates list

-templates.ts (in hindsight this should be called templateList.ts)
This is the datafile containing links and description to the Templates located in the astro/examples folder, my reasoning for doing it this way was after I had scrapped the data via the api i was wanting to annotate it a bit with a blurb and allow for the potenial of applying demonstration links to the templates, once these become available. I realised that this was out-with my current skill level and thought that this approach should suffice in delivering the same objectives for this particular page.
I would happily defer this to a better practice,

Please let me know what you think of this page,

Many Thanks =)

[changeset-bot]

⚠️ No Changeset found

Latest commit: e9de20c

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployments, click below or on the icon next to each commit.

astro-docs – ./docs

🔍 Inspect: https://vercel.com/pikapkg/astro-docs/9KfVSmGfXmRPSqfP1MumNoM1Y67o
✅ Preview: https://astro-docs-git-fork-afuzzybear-docs-experimental-546c26-pikapkg.vercel.app

astro-www – ./www

🔍 Inspect: https://vercel.com/pikapkg/astro-www/7iXgMLw6Bb1TRtVuf9fkJoz3Jhut
✅ Preview: https://astro-www-git-fork-afuzzybear-docs-experimental-74e1ab-pikapkg.vercel.app

[jasikpark]

here's the link to that page in the preview: https://astro-docs-git-fork-afuzzybear-docs-experimental-546c26-pikapkg.vercel.app/template

You should be able to add the page to the sidebar config file so that it shows up in the sidebar, that would be a part of this pr

[aFuzzyBear]

Ill add that to the sitemap and have that added to this pr @jasikpark, thanks for pulling up that preview page =)

[aFuzzyBear]

Changes Made:

You should be able to add the page to the sidebar config file so that it shows up in the sidebar, that would be a part of this pr

Updated the Sitemap and the Sidebar to incorporate the Examples & Templates page, I have left the existing Examples.md page link also on the sidebar, this is too allow for comparison between the two pages, if accepted we could easily remove the latter reference,

• Housekeeping

Renamed the files with some better filenames, and updated the relevant file paths where needed.

[matthewp]

@aFuzzyBear when this is ready can you remove the "WIP" in the title? For in the future, GitHub lets you create Draft PRs now, that way reviewers know that it's a work in progress.

[vercel]

@aFuzzyBear is attempting to deploy a commit to the Pika Team on Vercel.

A member of the Team first needs to authorize it.

[aFuzzyBear]

ignore the last one, pushd to the wrong place 😓

[shreeshbhat]

Would love to see some examples around using web components too?
I had some trouble figuring out how to use web component.
Haven't figured it out yet. Will raise a PR for docs if I figure it out soon.

[aFuzzyBear]

hey bud @shreeshbhat, if there is an example that we could put together and have placed into the example repo ill be able to make a link to it on the examples page, just need to get the doc's sidebar styling to work then this should be good to go,

[aFuzzyBear]

I've managed to get the examples page working perfectly with the rest of the site, I did notice a few things that required me to bend the Main.astro a bit in order to get this to work,

There is a part of the Main.astro that pulls in the current page, this works great for *.md files but not astro files, Since this was a pure astro page, this made getting some of the data that the Main.astro needed such as the document title headers, to then be passed into the DocSidebar.tsx. To do this I had created a separate function that produces an array for the Sidebar to consume from the template.ts which holds the template data.

To get the sidebar working I had to rearrange some variables in the Main.astro here I'd had moved currentPage = Astro.request?.url?.pathname to the props so astro files could send down the page pathname as well. Adjusted some of the logic to allow for the variables from the pages(both *.md and *.astro to be properly passes into the Sidebar.

All I need to do now is update the placeholder text in the templates.ts file with better copywritten content and this should be good to go.

=)

[aFuzzyBear]

Been struggling with the online code sandboxes today, been wanting to setup online demo's for each of the templates, any advice/assistance with this would be great.

I was thinking of just dockerising each template so that there is a live version of it, when there is better support for Astro with the online code-waste of times then we can add in a link to those as well, this wouldn't take much todo, just add in a link in the Examples.astro file and a new field to the templates.ts to house the demo link.

So should I go ahead and spend tomorrow making up dockerfiles, if so, what about deployment....? if not, what should be the best course for me to pursue with this?

KR

[aFuzzyBear]

Had an update from the team over at 'Stackblitz' and they said that they are currently working on the 'problem' of allowing astro to run natively on their online code-editors. The current problem as they state is "The underlying issue is our lack of ESM modules (and dynamic import()) at the moment. We're working on it though. Thanks for the report!" if this does get solved then it should be as simple to run the links to the online code sandbox.
Stackblitz PR #281

[FredKSchott]

Hey @aFuzzyBear, thanks for submitting this! I think this is a great start and I think this would be a great addition to the site. Here are some thoughts on what's still needed to get this merged:

1. rebase (or merge) onto main to get back up to date with the latest changes on main.
2. templates.ts - I'm worried about the cost of maintaining this over time. Instead, could we automatically generate the data for all of our official templates? I think that you could read all examples/*/package.json files and turn each one into an object for this JSON array. Then, this file could just for community templates. Does that make sense?
3. Design - it would be great to get a bit more visual on this page. Also, we could fit more on the page if they took up less room. What do you think about how 11ty does it? https://www.11ty.dev/docs/starter/ I think having a screenshot for each one (or a nice default gradient) could be nice as well.

If you can tackle these, I'd be happy to help review the rest of the PR and get it merged in.

Thanks for taking the initiative on this!

[aFuzzyBear]

Hi fred, thanks for taking a look over it man, I will start working on these the day. =)

Looking over the 11ty example site, this is very doable in terms of design, I really like the use of site images and lighthouse scores. I'm just thinking about this extra annotation, would this information such as site image, lighthouse scores, links to external demo's would this be placed into the example/*/package.json, and about the the use-case where this information is not present inside the package.json.

I wholly accept your remarks concerning the maintenance of the template.ts file, this was really a shim to house the data for me which had kinda made life easier since I had limited success with the github API at the time. I am going to have to look deeper into how to achieve no2. That is going to be the most challenging.

Thanks for this Fred, really looking forward to tackling this =)

[FredKSchott]

An idea that I hope might work:

// templateData.ts

export function getExamples() {
  const allExampleManifests = // glob.sync('../../examples/*/package.json);
  return allExampleManifests.map((fileContents) => JSON.parse(allExampleManifests));
  // TODO: make sure any metadata that you want to show here, lives on the example package.json
  // even better, reuse existing data like pkg.description
}

export const examples = getExamples();
export const templates = [
  // user-submitted templates added here!
];

[FredKSchott]

I think some of those features of the 11ty site should definitely be avoided for now. For example, they generate live screenshots of every site automatically via pupeteer. I think we could just use imgSrc: 'https://...' to hardcode images for now.

Also, lighthouse scores are a great idea but can be added later on after this has been merged.

[jasikpark]

Topical for the screenshots:

• https://www.zachleat.com/web/screenshots/
• https://github.com/11ty/api-screenshot

[aFuzzyBear]

@jasikpark dude I can hug you, lol I know the fred said that he wasnt keen on the idea but it has been buggin me for most of the day.

Also having a small victory dance atm;

Thats me able to get the data from the package.json files from the examples directory, thanks for that heads up @FredKSchott (actual legend). I was looking back at the route of the github api, when this was way easier.

Now all I need to do is go through each of the repo's and update the manifest files....then i'll tackle the re-design,

[FredKSchott]

@aFuzzyBear awesome, nicely done! Still blown away that you can do that with Astro :)

[FredKSchott]

also don't get me wrong, I'd love to get an auto-screenshotting-with-puppeteer setup going eventually! But its a pretty big task and this PR already has the potential to get too big to review if we're not careful. No reason it can't be done in a separate followup immediately after

Update: I take that back... it looks like Zach isn't saying no to using his hosted version of https://v1.screenshot.11ty.dev/:url/ directly... if we don't have to build the service ourselves I'm +1! We were also lucky enough to get a OSS Netlify plan for the project, so we could literally hit that "Deploy with Netlify" button from the blog post and host a copy ourselves.

<img src={`https://v1.screenshot.11ty.dev/` + encodeURIComponent(templateHostedDemoUrl)} />

[aFuzzyBear]

inadvertently astro has server-side functions nailed to a T 😅
I agree with the whole puppetter thing, thats just one kettle I dont wish to brew just yet, would be cool to learn and implement but not yet, wanna get this finished off (hopefully tomorrow and have it ready to be reviewed for next week).
hope you have a good weekend guys, =)

[jasikpark]

With that, it'd be really nice to have hosted versions of all of the example sites for people to browse and for the screenshot endpoint to be pointed at! That'd also make it easier for people to spot problems in the example sites as well!

[FredKSchott]

Superseded by #1100