simple-site-generator 0.1.3 → 0.2.0

package/templates/app/src/pages/GettingStarted/GettingStarted.md

@@ -0,0 +1,52 @@
+---
+id: gettingstarted
+title: Getting started
+description: Scaffold a project, add pages and verify the build before you deploy.
+label: Getting started
+icon:
+  name: i-mdi-rocket-launch
+tags:
+  - menu
+---
+
+## Scaffold a project
+
+```bash
+pnpm dlx simple-site-generator init my-site --template landing
+cd my-site
+pnpm install
+pnpm dev
+```
+
+Replace `landing` with `docs` or `business` to start from a different template.
+
+## Add a page
+
+```bash
+ssg add-page services --title "Services" --tags menu
+```
+
+This writes `src/pages/services.md` with frontmatter that already satisfies the
+page contract. Add `--page Landing` to render it with the conversion layout.
+
+## Check, build, verify
+
+```bash
+ssg check     # validate every page's frontmatter
+ssg build     # prerender the site into dist/static
+ssg verify    # SEO surface, byte budgets and Lighthouse
+```
+
+`ssg verify` fails the run on a broken SEO surface (a missing description, two
+titles, unparseable JSON-LD) or on an exceeded byte budget, and warns when
+Lighthouse performance is below target.
+
+## Deploy
+
+The build output is `dist/static` — plain files. Copy them to any static host.
+The included GitHub workflow uses `rsync` to push to your own server; define
+`DEPLOY_HOST`, `DEPLOY_USER` and `DEPLOY_KEY` as repository secrets.
+
+> **Note**
+> Change the `template` value in `vitrify.config.ts` to switch between `docs`,
+> `landing` and `business`.

package/templates/app/src/pages/Index.md.hbs

@@ -0,0 +1,46 @@
+---
+id: home
+title: Home
+description: A fast, static website built with Quasar and Vitrify — edit the
+  content as Markdown and deploy the generated files anywhere.
+label: Home
+{{#if landingPage}}
+page: Landing
+{{/if}}
+tags:
+  - menu
+icon:
+  name: i-mdi-home
+cta:
+  message: Get started
+  route: /gettingstarted
+cards:
+  - header: Content in Markdown
+    content: Write pages as Markdown files with frontmatter; the templates turn
+      them into a real site.
+  - header: Static and fast
+    content: Every page is prerendered to HTML, so it loads without waiting on
+      JavaScript.
+  - header: One command to verify
+    content: ssg verify checks the SEO surface, the byte budgets and Lighthouse
+      before you deploy.
+images:
+  - name: Landing
+    src: images/landing/landing.png
+    caption: A simple site generator project
+# The hero's animated process graphic — a route with named stops, drawn from
+# this list. Replace the stops with your own process; two to five read best.
+# `landing` shows it only when a page declares no hero image, and `business`
+# shows it in the page's title band instead of a background illustration.
+demo:
+  label: From Markdown to a deployed site
+  steps:
+    - Write Markdown
+    - Build
+    - Deploy
+---
+
+## Why use this
+
+Write Markdown, get a fast static site. The pages below are the starting point —
+replace them with your own content.

package/templates/app/src/router/index.ts

@@ -0,0 +1,21 @@
+/// <reference types="vitrify/client" />
+import {
+  createMemoryHistory,
+  createRouter as _createRouter,
+  createWebHistory
+} from 'vue-router'
+import routes from './routes'
+
+export default function createRouter() {
+  return _createRouter({
+    // use appropriate history implementation for server/client
+    // import.meta.env.SSR is injected by Vite.
+    history: import.meta.env.SSR
+      ? createMemoryHistory(__BASE_URL__)
+      : createWebHistory(__BASE_URL__),
+    scrollBehavior(_to, _from, _savedPosition) {
+      return { top: 0 }
+    },
+    routes
+  })
+}

package/templates/app/src/router/routes.ts

@@ -0,0 +1,218 @@
+import type { RouteRecordRaw } from 'vue-router'
+// The slim virtual module carries ONLY the site identity the client needs.
+// Importing `virtual:vitrify-config` instead inlined the entire build config
+// (including the whole UnoCSS/Quasar option tree) into the browser bundle —
+// 205 KB raw / 109 KB minified on the previous version of this file.
+import { site } from 'virtual:ssg:site'
+import { QNoSsr } from 'quasar'
+import { defineAsyncComponent, h } from 'vue'
+import { Layout } from 'virtual:ssg:template'
+
+const { tags, extra } = site
+
+/** Frontmatter a page file may declare (see CONTENT-BLUEPRINT.md). */
+interface PageFrontmatter {
+  id?: string
+  title?: string
+  label?: string
+  description?: string
+  /** Sort weight; the home page is always first. */
+  order?: number
+  /** Name of the template component to render, e.g. `Landing`. */
+  page?: string
+  /** Render this page client-side only. */
+  noSsr?: boolean
+  /** Keep the page out of the index and the sitemap. */
+  noindex?: boolean
+  image?: string
+  /**
+   * BCP-47 tag when this page is not in the site's default language, e.g. `nl`.
+   * Drives `<html lang>`, `og:locale` and the JSON-LD `inLanguage`.
+   */
+  lang?: string
+  /**
+   * Other-language versions of this page: `{ lang, path, label? }`.
+   *
+   * Emitted as `rel="alternate"` hreflang links, and rendered as the language
+   * switch in the header (which hides the entry pointing at the current page,
+   * so a single-language site shows no switch at all).
+   *
+   * The pairing is app-specific — declare it per page, or derive it here as
+   * `simsustech/website` does for its `nl-`-prefixed pages.
+   */
+  alternates?: { lang: string; path: string; label?: string }[]
+  breadcrumbs?: string[]
+  tags?: string[]
+  [key: string]: unknown
+}
+
+interface PageModule {
+  attributes?: PageFrontmatter
+  html?: string
+  default?: unknown
+}
+
+/**
+ * Markdown and Vue pages, eagerly imported so the route table is complete at
+ * module-evaluation time (prerendering needs every route to exist up front).
+ *
+ * The pattern MUST be relative. The previous version was a bare `src/pages` path,
+ * which Vite 8 rejects outright — "Invalid glob … It must start with '/' or
+ * './'" — so the glob resolved to nothing and every page silently disappeared
+ * from the build. The extglob alternation that also changed is NOT the cause: the
+ * extglob and brace forms match identically once the leading './' is present, and
+ * `test/page-glob.test.ts` pins that.
+ *
+ * Note for editors: never write a glob containing a `*` immediately followed by a
+ * `/` inside a block comment — the `*` + `/` pair closes the comment early and
+ * the rest of the comment is parsed as code.
+ */
+const pagesImport = import.meta.glob(
+  ['../pages/**/*.{md,vue}', '!**/Error404Page.vue'],
+  { eager: true }
+)
+
+const noSsrComponent = {
+  name: 'NoSSRWrapper',
+  render(this: { component: unknown; page: unknown }) {
+    const component = defineAsyncComponent(this.component as never)
+    return h(QNoSsr, null, {
+      default: () => h(component, this.page as Record<string, unknown>)
+    })
+  },
+  props: ['page', 'component']
+}
+
+function attributesOf(page: unknown): PageFrontmatter {
+  return (page as PageModule | undefined)?.attributes ?? {}
+}
+
+/**
+ * Home first, then pages with an explicit `order`, then the rest alphabetically.
+ */
+const orderedPages = [
+  ...Object.entries(pagesImport)
+    .filter(([, page]) => {
+      const { id, order = 0 } = attributesOf(page)
+      return order || id === 'home'
+    })
+    .sort(([, pageA], [, pageB]) => {
+      const { id: idA, order: orderA = 0 } = attributesOf(pageA)
+      const { id: idB, order: orderB = 0 } = attributesOf(pageB)
+
+      if (idA === 'home') return -1
+      if (idB === 'home') return 1
+
+      return orderA - orderB
+    }),
+  ...Object.entries(pagesImport).filter(([, page]) => {
+    const { id, order = 0 } = attributesOf(page)
+    return !order && id && id !== 'home'
+  })
+]
+
+const pageList = orderedPages.map(([, page]) => attributesOf(page))
+
+const routes: RouteRecordRaw[] = [
+  {
+    path: '/',
+    component: Layout,
+    props: {
+      ...site,
+      pages: pageList,
+      tags,
+      extra
+    },
+    children: [
+      ...orderedPages.map(([, page]) => {
+        const { id = '', page: componentName = '', noSsr } = attributesOf(page)
+        const { attributes = {}, html = '' } = (page ?? {}) as PageModule
+
+        const vuePage = async () => {
+          if ((page as PageModule).default) {
+            return (page as PageModule).default
+          }
+
+          return import('virtual:ssg:template').then((module) => {
+            const templates = module.default
+
+            // No component named: the template's `Page` is the default, which is
+            // what most pages want.
+            if (!componentName) return module.Page
+
+            const component = templates[componentName]
+
+            // A named component that does not exist used to fall back to
+            // `module.Page` silently. That is the worst possible outcome for a
+            // field that decides a page's entire layout: the page renders, looks
+            // plausible, and is the wrong template.
+            //
+            // Thrown during prerender, so it fails the build rather than
+            // shipping.
+            if (!component) {
+              const available = Object.keys(templates)
+                .sort((a, b) => a.localeCompare(b))
+                .join(', ')
+
+              throw new Error(
+                `Unknown page template component "${componentName}" on page "${id}".\n` +
+                  `  \`page:\` names a component from the configured template module,\n` +
+                  `  which provides: ${available}. Most pages should omit \`page:\`\n` +
+                  `  entirely and get the template's default \`Page\`.`
+              )
+            }
+
+            return component
+          })
+        }
+
+        const props = {
+          ...attributes,
+          content: html,
+          pages: pageList,
+          // The business details (phone, reviews, service area) live on the site
+          // config, not in each page's frontmatter, but the landing page needs them
+          // for its proof/CTA sections — so they are passed down here rather than
+          // duplicated into every page.
+          extra
+        }
+
+        return {
+          // The home page lives at the parent path, so its child path is empty.
+          path: id === 'home' ? '' : id,
+          name: id,
+          component: noSsr ? noSsrComponent : vuePage,
+          props: noSsr ? { page: props, component: vuePage } : props,
+          alias: id === 'home' ? ['home'] : [],
+          /**
+           * The single source of truth about a page, read by both the shell (for
+           * `<head>` tags) and the build (for the sitemap).
+           */
+          meta: {
+            id,
+            title: attributes.title,
+            description: attributes.description,
+            noindex: attributes.noindex ?? false,
+            image: attributes.image,
+            lang: attributes.lang,
+            alternates: attributes.alternates,
+            breadcrumbs: attributes.breadcrumbs
+          }
+        } as RouteRecordRaw
+      }),
+
+      // The catch-all is a CHILD of the layout on purpose. As a sibling it
+      // rendered outside the shell, so it had no header, no footer and — because
+      // `useSeo` lives in the layout — no `<head>` tags at all. Vue Router ranks
+      // a catch-all last, so it cannot shadow a real page.
+      {
+        path: ':catchAll(.*)*',
+        name: 'not-found',
+        component: () => import('../pages/Error404Page.vue'),
+        meta: { id: '404', title: 'Page not found', noindex: true }
+      }
+    ]
+  }
+]
+
+export default routes

package/templates/app/src/setup.ts

@@ -0,0 +1,8 @@
+import type { FastifyInstance } from 'fastify'
+
+/**
+ * Only used in SSR/SSG
+ */
+export default async function (_fastify: FastifyInstance) {
+  console.log('Running setup function....')
+}

package/templates/app/src/shims-virtual.d.ts

@@ -0,0 +1,67 @@
+// Types for the virtual modules the build injects. Without these, every import
+// from `virtual:ssg:*` is an unresolved module in the editor and in any
+// type-check of this app.
+
+declare module 'virtual:ssg:site' {
+  interface SsgTag {
+    label: string
+  }
+
+  interface SsgExtra {
+    phone?: string
+    email?: string
+    address?: string
+    instagramUrl?: string
+    facebookUrl?: string
+    mapUrl?: string
+    rating?: number
+    reviewCount?: number
+    reviewSource?: string
+  }
+
+  interface SsgBusiness {
+    type?: string
+    name?: string
+    description?: string
+    telephone?: string
+    email?: string
+    address?: {
+      streetAddress?: string
+      postalCode?: string
+      addressLocality?: string
+      addressCountry?: string
+    }
+    areaServed?: string[]
+    openingHours?: { days: string[]; opens: string; closes: string }[]
+    priceRange?: string
+  }
+
+  /**
+   * Site identity only. Deliberately NOT the whole build config: this module is
+   * evaluated in the browser, so anything added here ships to every visitor.
+   */
+  export const site: {
+    title: string
+    url: string
+    favicon?: string
+    description?: string
+    lang?: string
+    image?: string
+    twitter?: string
+    template: string
+    templatePackage: string
+    tags: Record<string, SsgTag>
+    extra?: SsgExtra
+    jsonLd?: { business?: SsgBusiness }
+  }
+}
+
+declare module 'virtual:ssg:template' {
+  import type { Component } from 'vue'
+
+  export const Layout: Component
+  export const Page: Component
+  /** Optional page components a template may expose, e.g. `Landing`. */
+  const template: Record<string, Component>
+  export default template
+}

package/templates/app/src/shims-vue.d.ts

@@ -0,0 +1,6 @@
+// Mocks all files ending in `.vue` showing them as plain Vue instances
+declare module '*.vue' {
+  import type { ComponentOptions } from 'vue'
+  const component: ComponentOptions
+  export default component
+}

package/templates/app/vitrify.config.ts.hbs

@@ -0,0 +1,249 @@
+import type { VitrifyConfig, VitrifyConfigAsync } from 'vitrify'
+import { QuasarPlugin, type QuasarPluginOptions } from 'vitrify/plugins'
+import type { QuasarIconSet } from 'quasar'
+// `QuasarPreset` is exported by the preset, NOT by vitrify. Importing it from
+// 'vitrify' fails at load time ("does not provide an export named
+// 'QuasarPreset'"), and since 0.7 the preset also refuses to run without a
+// style, so both the import and `style` below are required.
+import { QuasarPreset, quasarIconSet } from 'unocss-preset-quasar'
+import { MaterialDesign3 } from 'unocss-preset-quasar/styles'
+import { certificateFor } from 'devcert'
+import { plugin as mdPlugin } from 'vite-plugin-markdown'
+import { Mode } from 'vite-plugin-markdown'
+import { copyFile } from 'fs/promises'
+import { ssgSitemap } from '@simple-site-generator/templates/seo'
+import { ssgUnoConfig } from '@simple-site-generator/templates/design'
+
+interface SimpleSiteGenerator {
+  ssg: {
+    title: string
+    url: string
+    /** Site description: the sitemap's, and the fallback meta description. */
+    description: string
+    template: string
+    templatePackage: string
+    favicon: string
+    lang: string
+    sourceColor: string
+    tags: Record<string, { label: string }>
+    extra?: Record<string, unknown>
+    jsonLd?: { business?: Record<string, unknown> }
+  }
+}
+
+// Annotated with the interface rather than left to inference: the three reads
+// of `ssg.description`, `ssg.extra` and `ssg.jsonLd` below happen on values a
+// bare object literal does not have, so an unannotated literal makes every
+// generated project start with five `Property … does not exist` errors.
+const ssg: SimpleSiteGenerator['ssg'] = {
+  title: '{{ productName }}',
+  url: '{{ url }}',
+  description: '{{ description }}',
+  favicon: '/favicon-96.png',
+  // Rendered from the `--template` value passed to `ssg init`. It selects which
+  // template module the app imports, so it must be templated, not hardcoded.
+  template: '{{ template }}',
+  templatePackage: '@simple-site-generator/templates',
+  // BCP-47 tag for og:locale, JSON-LD `inLanguage`, and — through
+  // `vitrify.lang` below — the `<html lang>` that Quasar writes. It must name
+  // one of Quasar's language packs (node_modules/quasar/lang), e.g. `en-US`,
+  // `en-GB`, `nl`; a bare `en` has no pack and Quasar falls back to `en-US`.
+  lang: 'en-US',
+  // The only colour input. MD3 derives its whole tonal palette — every role
+  // token the design system reads, in light and dark mode — from this one value.
+  // A `colors` map beside it looks load-bearing and is not: it produced utility
+  // classes that drifted away from the templates' own tokens, so there is no
+  // second place to set a colour.
+  sourceColor: '#22c92a',
+  tags: {
+    menu: {
+      label: 'Menu'
+    },
+    footer: {
+      label: 'Footer'
+    },
+    contact: {
+      label: 'Contact'
+    }
+  }
+}
+
+const { template, templatePackage, title } = ssg
+
+/**
+ * Quasar's own icons, resolved to iconify classes.
+ *
+ * Handing Quasar the library *name* lets it pick its own font classes
+ * (`mdi mdi-menu-down`), and this app loads no icon font — so every icon the
+ * framework draws itself (the dropdown arrow, a select's chevron, a table's
+ * expander) renders as nothing. The rewritten set fixes that: each value is a
+ * class the preset emits CSS for.
+ *
+ * The resolution's `iconMapFn` is deliberately not passed — Vitrify serialises
+ * the Quasar config into the client bundle and a function does not survive, so
+ * passing it makes the arrow throw instead of render. Bare icon names need that
+ * mapper; write `i-mdi-*` names instead.
+ */
+const icons = quasarIconSet('mdi-v7')
+
+const quasarConf: QuasarPluginOptions = {
+  framework: {
+    components: [],
+    // 'Meta' is what makes Quasar emit the per-page <title>, description,
+    // canonical, OpenGraph and JSON-LD tags. Without it `ssrContext._meta.headTags`
+    // stays empty and a prerendered page ships no metadata at all.
+    plugins: ['Dialog', 'Notify', 'Loading', 'Meta'],
+    // A Quasar icon-library name. The preset derives the nested icon set from
+    // `quasar/dist/icon-set`, rewrites each value to its iconify class and
+    // safelists them — so the ~200-line hand-written icon map is not needed.
+    // The rewritten set is what Quasar renders from, above; the preset types it
+    // as `unknown`, so the assertion to Quasar's own type belongs here.
+    iconSet: icons.iconSet as QuasarIconSet
+  },
+  /*
+   * Disable SASS if you use UnoCSS
+   */
+  disableSass: true
+}
+
+export default async function ({
+  mode
+}: Parameters<VitrifyConfigAsync>[0]): Promise<VitrifyConfig> {
+  const config: VitrifyConfig & SimpleSiteGenerator = {
+    optimizeDeps: {
+      exclude: ['@simple-site-generator/templates']
+    },
+    plugins: [
+      mdPlugin({
+        mode: [Mode.HTML]
+      }),
+      // Emits sitemap.xml and robots.txt into dist/static, generated from the
+      // same page frontmatter the router reads.
+      ssgSitemap({
+        site: {
+          title: ssg.title,
+          url: ssg.url,
+          description: ssg.description,
+          favicon: ssg.favicon,
+          lang: ssg.lang,
+          extra: ssg.extra,
+          jsonLd: ssg.jsonLd
+        },
+        pagesDir: new URL('./src/pages', import.meta.url).pathname,
+        distDir: new URL('./dist', import.meta.url).pathname
+      }),
+      {
+        name: 'simple-site-generator-plugin',
+        resolveId(id: string) {
+          if (id === 'virtual:ssg:template' || id === 'virtual:ssg:site') {
+            return `\0${id}`
+          }
+        },
+        load(id: string) {
+          if (id === '\0virtual:ssg:template') {
+            return `import * as template from '${templatePackage}/${template}';
+              export * from '${templatePackage}/${template}';
+              export default template;`
+          }
+          if (id === '\0virtual:ssg:site') {
+            // ONLY the identity the browser needs. The previous version imported
+            // `virtual:vitrify-config`, which inlined the whole build config
+            // (UnoCSS presets, Quasar options, icon map) into the client bundle.
+            // The client reads exactly these fields, so anything else added here
+            // would ship to every visitor.
+            return `export const site = ${JSON.stringify({
+              title: ssg.title,
+              url: ssg.url,
+              favicon: ssg.favicon,
+              lang: ssg.lang,
+              template: ssg.template,
+              templatePackage: ssg.templatePackage,
+              tags: ssg.tags,
+              extra: ssg.extra,
+              jsonLd: ssg.jsonLd
+            })};`
+          }
+        },
+        closeBundle: () => {
+          copyFile(
+            new URL('./build/Caddyfile', import.meta.url).pathname,
+            new URL(`./dist/static/Caddyfile`, import.meta.url).pathname
+          )
+        }
+      }
+    ],
+    ssg,
+    vitrify: {
+      // Registering the Quasar plugin is what makes `useQuasar()` and every
+      // `q-*` component work during SSR. Without it a prerendered page throws
+      // "Cannot read properties of undefined (reading 'screen')" and ships an
+      // empty <div id="app">.
+      plugins: [
+        {
+          plugin: QuasarPlugin,
+          options: quasarConf
+        }
+      ],
+      productName: title,
+      // Pass the BCP-47 tag to Quasar as well: Quasar writes `<html lang>`
+      // from its selected language pack, and vitrify forwards this value to it.
+      lang: ssg.lang,
+      hooks: {
+        onSetup: [new URL('src/setup.ts', import.meta.url)]
+      },
+      unocss: {
+        presets: [
+          QuasarPreset({
+            style: MaterialDesign3,
+            sourceColor: ssg.sourceColor,
+            plugins: quasarConf.framework.plugins,
+            iconSet: 'mdi-v7',
+            // Only the third-party Quasar UI libraries whose styles this app
+            // needs contribute CSS; declaring them is what ports their
+            // selectors. The prose styles are not among them: the design system
+            // styles the markdown output itself (`ssg-prose`), so no Markdown
+            // component or stylesheet is needed on either side.
+            appExtensions: ['qmediaplayer']
+          })
+        ],
+        // The templates' design system: theme scale, shortcuts, preflights and
+        // the safelist of its class names.
+        ...ssgUnoConfig,
+        theme: ssgUnoConfig.theme,
+        content: {
+          pipeline: {
+            include: [
+              /\.(vue|svelte|[jt]sx|mdx?|astro|elm|php|phtml|html)($|\?)/,
+              // The templates package IS scanned, and has to be: a template
+              // component renders `q-separator` and `i-mdi-phone` as readily as
+              // it renders an `ssg-*` class, and `unocss-preset-quasar` is what
+              // turns both into CSS. Measuring this include against the site's
+              // own sources showed 137 selectors that exist *only* because of
+              // it — `q-separator`, `q-card__actions--*`, `q-btn-group*` and the
+              // icons among them. Dropping it looks like a free 17 KB and is
+              // actually an unstyled drawer with missing icons.
+              //
+              // The shortcut names are safelisted separately (`ssgSafelist`), so
+              // it is not the shortcut CSS this supplies — it is the Quasar and
+              // icon classes. The noise that rides along with it is bounded by
+              // the design system's own `blocklist`.
+              new RegExp(`${ssg.templatePackage}.*\\.js`)
+            ]
+          }
+        }
+      },
+      // No `sass.global` block: the media player's styles come from the preset's
+      // `appExtensions`, and the old `QMarkdown.sass` path does not exist (the
+      // file is `.scss`), so it only produced a resolution error.
+      ssr: {
+        serverModules: ['vite-plugin-markdown']
+      }
+    }
+  }
+  if (mode === 'development') {
+    config.server = {
+      https: await certificateFor('vitrify.test')
+    }
+  }
+  return config
+}