create-presmium 1.0.0-rc.0 → 1.0.0-rc.2

package/README.md

@@ -1,11 +1,12 @@
 # create-presmium
 
-Starts a new [Presmium](https://github.com/Lincyaw/presmium) project: a lecture, a workspace or a plugin. `presmium new` (from `pnpm add -g presmium`) runs it; so does `pnpm create presmium`.
+Starts a new [Presmium](https://github.com/Lincyaw/presmium) project: a lecture, a workspace, a themed site or a plugin. `presmium new` (from `pnpm add -g @lincyaw/presmium`) runs it; so does `pnpm create presmium`.
 
 ```sh
 presmium new
 presmium new my-lecture --type lecture --title "Tokenization"
 presmium new my-course --type workspace --title "Data structures"
+presmium new my-site --type site --theme course --title "My course"
 presmium new presmium-plugin-greeting --type plugin --name presmium-plugin-greeting
 ```
 
@@ -13,16 +14,35 @@ Without arguments it asks for the kind of project, the directory and the title (
 
 | Option | What |
 |---|---|
-| `--type <kind>` | `lecture` (one document), `workspace` (documents previewed with `presmium serve`) or `plugin` |
+| `--type <kind>` | `lecture` (one document), `workspace` (documents previewed with `presmium serve`), `site` (a themed workspace with a homepage and GitHub Pages workflow) or `plugin` |
+| `--theme <name>` | For `site`: `course` (default), `docs` or `showcase` |
 | `--title <text>` | The lecture's or the workspace's title (default: the directory's name) |
 | `--name <name>` | The plugin's package name (default: the directory's name) |
 | `--no-git` | Do not run `git init` |
 | `-h`, `--help` | Show the help |
 
-- A lecture: `lecture.md`; `presmium dev`, `presmium check`, `presmium build`.
+- A lecture: `lecture.json`; `presmium dev`, `presmium check`, `presmium build`.
 - A workspace: `presmium.workspace.yaml` and a first document in `intro/`; `presmium serve`.
-- A plugin: a directive, a Vue component shown in the web page and the slides, a server route, text in Chinese and English, an example document and integration tests; `pnpm install`, `pnpm test`, `pnpm dev`.
+- A site: `presmium.workspace.yaml`, an independent homepage in `site/home.json`, a teaching document in `intro/lecture.json`, and `.github/workflows/pages.yml`; `pnpm install`, `pnpm serve`, `pnpm build`.
+- A plugin: a directive, a React component shown in the web page and the slides, a server route, text in Chinese and English, an example document and integration tests; `pnpm install`, `pnpm test`, `pnpm dev`.
 
-Lectures and workspaces list `presmium` at create-presmium's own version as a dev dependency, so `pnpm install` pins it; without it the global `presmium` builds them. Each project gets an `AGENTS.md` (`CLAUDE.md` links to it) and copies of the Presmium skills for coding agents in `.agents/skills`. The text of the questions and of the new files follows the system's language (Chinese or English).
+Lectures, workspaces and sites list `presmium` at create-presmium's own version as a dev dependency, so `pnpm install` pins it; without it the global `presmium` builds them. Each project gets an `AGENTS.md` (`CLAUDE.md` links to it) and copies of the Presmium skills for coding agents in `.agents/skills`. The text of the questions and of the new files follows the system's language (Chinese or English).
+
+## Themed site
+
+```sh
+presmium new my-site --type site --theme showcase --title 'My work'
+cd my-site
+pnpm install
+pnpm serve
+```
+
+Edit `site/home.json` to design the homepage and `intro/lecture.json` for the first teaching document. `site.landing.source` selects the homepage file; homepage content has its own structure, while teaching documents retain `lecture.json` as their sole content authority. Change `site.theme` and `site.params` in `presmium.workspace.yaml` to personalize the site. `pnpm build` exports `dist/web/`.
+
+For your own HTML, CSS and JavaScript, replace the landing configuration with `site.landing: { template: './site/home.html' }`. The HTML entry and its local assets are bundled for static hosting; `script#presmium-site-data` provides the site's public document links. Refresh the homepage to rebuild that template during `pnpm serve`; template hot updates are not provided.
+
+Push the project to a GitHub repository, select **GitHub Actions** in **Settings → Pages → Build and deployment → Source**, then run the generated Pages workflow or push to its configured branch. It reads the repository's Pages base path, builds the site and deploys `dist/web/`. The build remains an ordinary static site that can be hosted elsewhere.
+
+See the [site theme guide](https://github.com/Lincyaw/presmium/blob/main/docs/site-themes.md) for the three presets, supported parameters and page layouts.
 
 License: Apache-2.0.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-presmium",
-  "version": "1.0.0-rc.0",
+  "version": "1.0.0-rc.2",
   "description": "presmium new, or pnpm create presmium: a new Presmium lecture, workspace or plugin",
   "license": "Apache-2.0",
   "repository": {
@@ -14,7 +14,7 @@
     "presmium",
     "create",
     "template",
-    "myst",
+    "document-ir",
     "slides"
   ],
   "type": "module",
@@ -37,10 +37,16 @@
     "templates"
   ],
   "dependencies": {
-    "jiti": "^2.7.0"
+    "jiti": "^2.7.0",
+    "@lincyaw/kernel": "1.0.0-rc.2"
   },
   "devDependencies": {
-    "@lincyaw/cli": "1.0.0-rc.0"
+    "@lincyaw/cli": "1.0.0-rc.2"
+  },
+  "presmium": {
+    "generated": [
+      "templates"
+    ]
   },
   "scripts": {
     "templates": "node scripts/templates.ts"

package/src/cli.ts

@@ -2,13 +2,15 @@ import { createInterface } from 'node:readline'
 import type { Interface } from 'node:readline'
 import { basename, relative, resolve } from 'node:path'
 import { parseArgs } from 'node:util'
-import { assertEmpty, createProject, CreateError, KINDS, nameOf, validName } from './create.ts'
+import { assertEmpty, createProject, CreateError, isValidPackageName, KINDS, packageNameFor, SITE_THEMES } from './create.ts'
+import type { ProjectKind, SiteTheme } from './create.ts'
 import { MESSAGES, systemLocale } from './messages.ts'
-import type { Messages, ProjectKind } from './messages.ts'
+import type { Messages } from './messages.ts'
 
 const DEFAULT_DIRS: Record<ProjectKind, string> = {
   lecture: 'my-lecture',
   workspace: 'my-course',
+  site: 'my-site',
   plugin: 'presmium-plugin-greeting',
 }
 
@@ -16,7 +18,7 @@ export async function main(argv: string[]): Promise<number> {
   const t = MESSAGES[systemLocale()]
   let args: ReturnType<typeof parse>
   try {
-    args = parse(argv)
+    args = parse(argv, t)
   } catch (error) {
     process.stderr.write(`create-presmium: ${(error as Error).message}\n\n${t.usage}\n`)
     return 2
@@ -31,15 +33,20 @@ export async function main(argv: string[]): Promise<number> {
     const kind = args.values.type ?? await questions.kind()
     if (!KINDS.includes(kind as ProjectKind)) throw new CreateError(t.badKind(kind), true)
     const project = kind as ProjectKind
+    if (args.values.theme !== undefined && project !== 'site') throw new CreateError(t.themeOnlyForSite, true)
+    const theme = args.values.theme ?? 'course'
+    if (!SITE_THEMES.includes(theme as SiteTheme)) throw new CreateError(t.badTheme(theme), true)
     const dir = resolve(args.positionals[0] ?? await questions.ask(t.dirQuestion, DEFAULT_DIRS[project]))
     assertEmpty(dir, t)
     const folder = relative(process.cwd(), dir) || '.'
     const title = args.values.title ?? (asking && project !== 'plugin' ? await questions.ask(t.titleQuestion, basename(dir)) : basename(dir))
-    const name = args.values.name ?? (asking && project === 'plugin' ? await questions.ask(t.nameQuestion, nameOf(dir)) : nameOf(dir))
-    if (!validName(name)) throw new CreateError(t.badName(name))
+    const name = args.values.name ?? (asking && project === 'plugin' ? await questions.ask(t.nameQuestion, packageNameFor(dir)) : packageNameFor(dir))
+    if (!isValidPackageName(name)) throw new CreateError(t.badName(name))
     questions.close()
-    createProject({ kind: project, dir, title, name, git: args.values.git, t })
-    const steps = [...folder === '.' ? [] : [`cd ${/[\s'"]/.test(folder) ? JSON.stringify(folder) : folder}`], ...project === 'plugin' ? ['pnpm install', 'pnpm test', 'pnpm dev'] : [`presmium ${project === 'lecture' ? 'dev' : 'serve'}`]]
+    // The project's content is written in the title's language: a Chinese title gets Chinese pages whatever the system says.
+    const lang = /\p{Script=Han}/u.test(title) ? 'zh-CN' : systemLocale()
+    createProject({ kind: project, dir, title, name, git: args.values.git, theme: theme as SiteTheme, t, content: MESSAGES[lang], lang })
+    const steps = [...folder === '.' ? [] : [`cd ${/[\s'"]/.test(folder) ? JSON.stringify(folder) : folder}`], ...project === 'plugin' ? ['pnpm install', 'pnpm test', 'pnpm dev'] : project === 'site' ? ['pnpm install', 'pnpm serve'] : [`presmium ${project === 'lecture' ? 'dev' : 'serve'}`]]
     process.stdout.write(`${t.created(project, folder)}\n\n${t.next}\n${steps.map(step => `  ${step}\n`).join('')}\n${t.agents}\n`)
     return 0
   } catch (error) {
@@ -51,7 +58,7 @@ export async function main(argv: string[]): Promise<number> {
   }
 }
 
-function parse(argv: string[]) {
+function parse(argv: string[], t: Messages) {
   const parsed = parseArgs({
     args: argv,
     allowPositionals: true,
@@ -59,12 +66,13 @@ function parse(argv: string[]) {
     options: {
       type: { type: 'string', short: 't' },
       title: { type: 'string' },
+      theme: { type: 'string' },
       name: { type: 'string' },
       git: { type: 'boolean', default: true },
       help: { type: 'boolean', short: 'h', default: false },
     },
   })
-  if (parsed.positionals.length > 1) throw new Error(`one directory, not ${parsed.positionals.length}`)
+  if (parsed.positionals.length > 1) throw new Error(t.tooManyDirectories(parsed.positionals.length))
   return parsed
 }
 

package/src/create.ts

@@ -1,16 +1,24 @@
+import { randomUUID } from 'node:crypto'
+import { DOCUMENT_ENTRY } from '@lincyaw/kernel'
+import type { TeachingDocument } from '@lincyaw/kernel'
 import { spawnSync } from 'node:child_process'
 import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, symlinkSync, writeFileSync } from 'node:fs'
 import { basename, dirname, join } from 'node:path'
-import type { Messages, ProjectKind } from './messages.ts'
+import type { Locale, Messages } from './messages.ts'
 import { projectPath, templateDir, templateFiles } from './templates.ts'
 
-export const KINDS: readonly ProjectKind[] = ['lecture', 'workspace', 'plugin']
+export type ProjectKind = 'lecture' | 'workspace' | 'plugin' | 'site'
+export type SiteTheme = 'course' | 'docs' | 'showcase'
+
+export const KINDS: readonly ProjectKind[] = ['lecture', 'workspace', 'plugin', 'site']
+export const SITE_THEMES: readonly SiteTheme[] = ['course', 'docs', 'showcase']
 
 export const VERSION = (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }).version
 
 const SKILLS: Record<ProjectKind, string[]> = {
-  lecture: ['presmium-author', 'presmium-present'],
-  workspace: ['presmium-author', 'presmium-present'],
+  lecture: ['presmium-author', 'presmium-animate', 'presmium-present'],
+  workspace: ['presmium-author', 'presmium-animate', 'presmium-present'],
+  site: ['presmium-author', 'presmium-animate', 'presmium-present'],
   plugin: ['presmium-develop', 'presmium-author'],
 }
 
@@ -24,7 +32,11 @@ export interface ProjectOptions {
   title: string
   name: string
   git: boolean
+  theme?: SiteTheme
   t: Messages
+  /** The messages the project's own files are written in, and their language; the command's messages when absent. */
+  content?: Messages
+  lang?: Locale
 }
 
 export class CreateError extends Error {
@@ -36,17 +48,17 @@ export class CreateError extends Error {
   }
 }
 
-export function validName(name: string): boolean {
+export function isValidPackageName(name: string): boolean {
   return name.length <= 214 && PACKAGE_NAME.test(name)
 }
 
-export function nameOf(dir: string): string {
+export function packageNameFor(dir: string): string {
   const name = basename(dir).toLowerCase().replace(/[^a-z0-9._~-]+/g, '-').replace(/^[._~-]+/, '')
   return name || 'presmium-project'
 }
 
-export function pluginId(name: string): string {
-  return name.replace(/^@/, '').replace('/', '.')
+export function pluginIdFor(packageName: string): string {
+  return packageName.replace(/^@/, '').replace('/', '.')
 }
 
 export function assertEmpty(dir: string, t: Messages): void {
@@ -55,27 +67,52 @@ export function assertEmpty(dir: string, t: Messages): void {
 
 export function createProject(options: ProjectOptions): void {
   const { kind, dir, title, name, t } = options
+  const c = options.content ?? t
   assertEmpty(dir, t)
-  if (!validName(name)) throw new CreateError(t.badName(name))
+  if (!isValidPackageName(name)) throw new CreateError(t.badName(name))
   mkdirSync(dir, { recursive: true })
   const document = (to: string, documentTitle: string) => {
-    const quoted = JSON.stringify(documentTitle).slice(1, -1)
-    copyTemplate('document/default', to, (path, text) => path.endsWith('.md') ? text.replaceAll('{{title}}', () => quoted) : text)
+    copyTemplate('document/default', to, (path, text) => {
+      if (path !== DOCUMENT_ENTRY) return text
+      const value = JSON.parse(text) as TeachingDocument
+      value.id = randomUUID()
+      value.metadata.title = documentTitle
+      if (options.lang) value.metadata.lang = options.lang
+      for (const section of Object.values(value.sections)) if (section.title === '{{title}}') section.title = documentTitle
+      return `${JSON.stringify(value, null, 2)}\n`
+    })
   }
   if (kind === 'lecture') {
     document(dir, title)
     copyTemplate('workspace', dir, unchanged, path => path === '.gitignore' || path === 'pnpm-workspace.yaml')
-    writePackage(dir, { name, private: true, type: 'module', scripts: { dev: 'presmium dev', check: 'presmium check', build: 'presmium build' }, devDependencies: { presmium: `^${VERSION}` } })
+    writePackage(dir, { name, private: true, type: 'module', scripts: { dev: 'presmium dev', check: 'presmium check', build: 'presmium build' }, devDependencies: { '@lincyaw/presmium': `^${VERSION}` } })
   } else if (kind === 'workspace') {
     copyTemplate('workspace', dir, (path, text) => path === 'presmium.workspace.yaml' ? text.replace(/^title: .*$/m, () => `title: ${JSON.stringify(title)}`) : text)
-    document(join(dir, FIRST_DOCUMENT), t.firstDocument)
-    writePackage(dir, { name, private: true, type: 'module', scripts: { serve: 'presmium serve', check: `presmium check ${FIRST_DOCUMENT}`, build: 'presmium build' }, devDependencies: { presmium: `^${VERSION}` } })
+    document(join(dir, FIRST_DOCUMENT), c.firstDocument)
+    writePackage(dir, { name, private: true, type: 'module', scripts: { serve: 'presmium serve', check: `presmium check ${FIRST_DOCUMENT}`, build: 'presmium build' }, devDependencies: { '@lincyaw/presmium': `^${VERSION}` } })
+  } else if (kind === 'site') {
+    copyTemplate('workspace', dir, unchanged, path => path === '.gitignore' || path === 'pnpm-workspace.yaml')
+    const theme = options.theme ?? 'course'
+    const params = theme === 'showcase'
+      ? { accent: 'violet', typography: 'sans', contentWidth: 'wide' }
+      : { accent: 'teal', typography: 'reading', contentWidth: 'comfortable' }
+    const strings: Record<string, string> = { ...c.site, title, theme, ...params }
+    copyTemplate('site', dir, (path, text) => {
+      if (path.endsWith('.json')) {
+        const value = JSON.parse(text, (_key, value: unknown) => typeof value === 'string' ? value.replace(/\{\{(\w+)\}\}/g, (token, key: string) => strings[key] ?? token) : value) as Record<string, unknown>
+        if (path.endsWith(DOCUMENT_ENTRY)) value.id = randomUUID()
+        return `${JSON.stringify(value, null, 2)}\n`
+      }
+      if (path === 'presmium.workspace.yaml') return text.replace(/\{\{(\w+)\}\}/g, (token, key: string) => key in strings ? JSON.stringify(strings[key]) : token)
+      return text
+    })
+    writePackage(dir, { name, private: true, type: 'module', scripts: { serve: 'presmium serve', check: 'presmium check intro', build: 'presmium build' }, devDependencies: { '@lincyaw/presmium': `^${VERSION}` } })
   } else {
-    copyTemplate('plugin', dir, (path, text) => text.replaceAll('{{name}}', () => name).replaceAll('{{id}}', () => pluginId(name)).replaceAll('{{version}}', () => VERSION))
+    copyTemplate('plugin', dir, (path, text) => text.replaceAll('{{name}}', () => name).replaceAll('{{id}}', () => pluginIdFor(name)).replaceAll('{{version}}', () => VERSION))
   }
   if (kind !== 'plugin') {
-    writeFileSync(join(dir, 'README.md'), t.readme(kind, title))
-    writeFileSync(join(dir, 'AGENTS.md'), t.agentsFile(kind, title))
+    writeFileSync(join(dir, 'README.md'), c.readme(kind, title))
+    writeFileSync(join(dir, 'AGENTS.md'), c.agentsFile(kind, title))
   }
   agentFiles(dir, SKILLS[kind])
   if (options.git) gitInit(dir)
@@ -83,7 +120,7 @@ export function createProject(options: ProjectOptions): void {
 
 const unchanged = (_path: string, text: string): string => text
 
-const TEXT = /(?:\.(?:md|ts|mts|js|mjs|vue|json|ya?ml|css|html|txt)|(?:^|[\\/])\.gitignore)$/
+const TEXT = /(?:\.(?:md|tsx?|mts|jsx?|mjs|json|ya?ml|css|html|txt)|(?:^|[\\/])\.gitignore)$/
 
 function copyTemplate(template: string, to: string, edit: (path: string, text: string) => string, only: (path: string) => boolean = () => true): void {
   const from = templateDir(template)
@@ -119,5 +156,6 @@ function agentFiles(dir: string, skills: string[]): void {
 function gitInit(dir: string): void {
   const inside = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], { cwd: dir, encoding: 'utf8' })
   if (inside.error || inside.stdout.trim() === 'true') return
-  spawnSync('git', ['init', '--quiet'], { cwd: dir, stdio: 'ignore' })
+  // The Pages workflow publishes on pushes to main, whatever the machine's default branch is.
+  spawnSync('git', ['init', '--quiet', '--initial-branch=main'], { cwd: dir, stdio: 'ignore' })
 }