content: add examples to packages (#238)

Author: Barbapapazes

bin/commands/github/sync-packages.ts

@@ -5,7 +5,7 @@ import { defineCommand } from 'citty'
 import consola from 'consola'
 import { ofetch } from 'ofetch'
 import { fetchRepos } from '../../utils/github'
-import { addPackage, getPackages, getPackagesPath, removePackage } from '../../utils/content'
+import { addPackage, getExamplesLink, getPackages, getPackagesPath, removePackage } from '../../utils/content'
 import { getPackagesRedirectsPath } from '../../utils/config'
 import type { GitHubRepo } from '../../types'
 
@@ -70,7 +70,12 @@ async function createPR(package_: string, repos: GitHubRepo[], operation: 'add'
       consola.fatal(`Repo ${package_} not found.`)
       exit(1)
     }
-    addPackage(repo)
+    const examplesLink = await getExamplesLink(repo.name)
+    addPackage({
+      name: repo.name,
+      description: repo.description,
+      examples: examplesLink,
+    })
   }
   else if (operation === 'remove') {
     removePackage(package_)

bin/commands/sync.ts

@@ -6,6 +6,7 @@ export const sync = defineCommand({
   },
   subCommands: {
     'packages-redirects': () => import('./sync/packages-redirects').then(m => m.packagesRedirects),
+    'packages-examples': () => import('./sync/packages-examples').then(m => m.packagesExamples),
     'packages': () => import('./sync/packages').then(m => m.packages),
   },
 })

bin/commands/sync/packages-examples.ts

@@ -0,0 +1,45 @@
+import { defineCommand } from 'citty'
+import { getExamplesLink, getPackages, loadPackageContent, writePackageContent } from '../../utils/content'
+
+export const packagesExamples = defineCommand({
+  meta: {
+    name: 'packages-examples',
+    description: 'Add examples link to packages that does not have it',
+  },
+  async run() {
+    const packages = getPackages()
+    const packagesContents = []
+
+    for (const package_ of packages) {
+      const content = loadPackageContent(package_)
+
+      packagesContents.push(content)
+    }
+
+    // We assume that examples will be in the root of the repo in the examples directory
+    const examples = await Promise.all(packagesContents.map(async (content) => {
+      const examplesLink = await getExamplesLink(content.title)
+
+      if (!examplesLink) {
+        // Remove examples link
+        content.examples = {
+          link: null,
+          page: false,
+        }
+
+        return content
+      }
+
+      // Add examples link
+      content.examples = {
+        link: examplesLink,
+        page: content.examples?.page || false,
+      }
+      return content
+    }))
+
+    // Write back
+    for (const example of examples)
+      writePackageContent(example)
+  },
+})

bin/commands/sync/packages.ts

@@ -1,7 +1,7 @@
 import { defineCommand } from 'citty'
 import { consola } from 'consola'
 import { fetchRepos } from '../../utils/github'
-import { addPackage, getPackages, removePackage } from '../../utils/content'
+import { addPackage, getExamplesLink, getPackages, removePackage } from '../../utils/content'
 
 export const packages = defineCommand({
   meta: {
@@ -14,9 +14,14 @@ export const packages = defineCommand({
     // Repositories without a package
     const reposWithoutPackage = repos.filter(repo => !packages.includes(repo.name))
 
-    for (const repo of reposWithoutPackage) {
+    for await (const repo of reposWithoutPackage) {
       consola.info(`Creating ${repo.name}`)
-      addPackage(repo)
+      const examplesLinks = await getExamplesLink(repo.name)
+      addPackage({
+        name: repo.name,
+        description: repo.description,
+        examples: examplesLinks,
+      })
     }
 
     // Packages without a repository

bin/types.ts

@@ -25,3 +25,29 @@ export interface GithubRelease {
   markdown: string
   html: string
 }
+
+// https://github.com/unjs/ungh#reposownernamefilesbranch
+export interface GitHubFile {
+  path: string
+  mode: string
+  sha: string
+  size: number
+}
+
+export interface ContentPackage {
+  title: string
+  description: string
+  github: {
+    owner: string
+    repo: string
+  }
+  npm?: {
+    name: string
+  }
+  documentation: string
+  examples?: {
+    link: string | null
+    page: boolean
+  }
+  playgrounds?: Record<string, string>
+}

bin/utils/content.ts

@@ -1,7 +1,9 @@
 import { readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { cwd } from 'node:process'
-import type { GitHubRepo } from '../types'
+import yaml from 'js-yaml'
+import { ofetch } from 'ofetch'
+import type { ContentPackage, GitHubFile } from '../types'
 
 export function getContentPath() {
   const currentPath = cwd()
@@ -21,13 +23,21 @@ export function getBlogPath() {
   return join(contentPath, '5.blog')
 }
 
+export function loadPackageContent(name: string) {
+  return yaml.load(readFileSync(join(getPackagesPath(), `${name}.yml`), 'utf-8')) as ContentPackage
+}
+
+export function writePackageContent(package_: ContentPackage) {
+  writeFileSync(join(getPackagesPath(), `${package_.title}.yml`), yaml.dump(package_))
+}
+
 export function getPackages() {
   const packagesPath = getPackagesPath()
 
   return readdirSync(packagesPath).filter(p => p.endsWith('.yml') && !p.startsWith('.')).map(p => p.replace('.yml', ''))
 }
 
-export function addPackage(repo: GitHubRepo) {
+export function addPackage(repo: { name: string, description: string, examples: string | null }) {
   const packagesPath = getPackagesPath()
 
   const template = readFileSync(join(packagesPath, '.template.yml'), 'utf-8')
@@ -37,6 +47,7 @@ export function addPackage(repo: GitHubRepo) {
     .replace('package_description', repo.description)
     .replace('repo_name', repo.name)
     .replace('npm_name', repo.name)
+    .replace('examples_link', repo.examples || 'null')
     .replace('docs_link', `https://github.com/unjs/${repo.name}`))
 }
 
@@ -45,3 +56,11 @@ export function removePackage(name: string) {
 
   rmSync(join(packagesPath, `${name}.yml`))
 }
+
+export async function getExamplesLink(name: string) {
+  const files = await ofetch<{ files: GitHubFile[] }>(`https://ungh.cc/repos/unjs/${name}/files/main`)
+
+  const hasExamples = files.files.some(f => f.path.startsWith('examples/'))
+
+  return hasExamples ? `https://github.com/unjs/${name}/blob/main/examples` : null
+}

content/4.packages/.template.yml

@@ -7,4 +7,6 @@ npm:
   name: npm_name
 playgrounds:
 examples:
+  link: examples_link
+  page: false # Used to create a page using the examples
 documentation: docs_link

content/4.packages/bundle-runner.yml

@@ -6,3 +6,6 @@ github:
 npm:
   name: bundle-runner
 documentation: https://github.com/unjs/bundle-runner
+examples:
+  link: null
+  page: false

content/4.packages/c12.yml

@@ -6,3 +6,6 @@ github:
 npm:
   name: c12
 documentation: https://github.com/unjs/c12#%EF%B8%8F-c12
+examples:
+  link: null
+  page: false

content/4.packages/changelogen.yml

@@ -6,3 +6,6 @@ github:
 npm:
   name: changelogen
 documentation: https://github.com/unjs/changelogen#changelogen
+examples:
+  link: null
+  page: false