Openpress Create Pages

OpenPress Create Pages

openpress-create-pages owns artifact creation. The openpress skill owns CLI lifecycle: build, render, PDF, image, deploy, doctor, upgrade.

Boundary

---

Setup

1. Environment check:

node -v && npm -v && npx -v

Node ≥ 20 required. If missing or outdated, stop and ask the user to install Node.js LTS.

2. Detect workspace branch:

find press -mindepth 2 -maxdepth 2 -name press.tsx -print -quit 2>/dev/null | grep -q . && echo EXISTING || echo FRESH

3a. Fresh workspace:

Use npm create @open-press <target> -- --type slides only to create the package-based workspace shell when the user is starting from an empty folder. After dependencies and skills are installed, replace the generated slides Press with a pages Press owned by this skill. Do not use a force flag or removed scaffolding commands.

3b. Existing workspace:

Read press/*/press.tsx to identify existing slugs, geometries, componentsDir, and mediaDir. Create a new press/<slug>/ folder. Do not touch sibling Press folders unless the user asks.

---

Intake

Gather before writing files:

• Artifact type: report / proposal / whitepaper / paper / book / teaching note / handbook / other
• Audience
• Primary language
• Title
• Page geometry:
• report, proposal, whitepaper, paper, book, teaching note, handbook → a4
• custom: ask for width and height in CSS absolute units
• Theme inputs: primary ink, accent, font roles, Chinese/English font configuration, optional reference aesthetic
• body:正文、表格、caption、註解
• serif:書名、章節標題、正式敘事
• mono:code、路徑、資料欄位
• display:封面大標，可選
• Prefer self-hosted Latin fonts plus local CJK fallbacks; bundle licensed CJK subsets only when identical Chinese glyphs are required across machines.
• Known source material and confirmed facts

Do not ask for subtitle, organization, author, version, or footer as Press metadata — those are rendered text in cover/page components.

---

Hierarchy and Writing Rules

Decide structure before drafting prose.

Heading levels:

• #: whole document title only; cover identity, not normal content files
• ##: formal chapter/document unit; enters formal TOC
• ###: major topic group; enters formal TOC
• ####: concrete algorithm, operation, theorem, variant, worked procedure, or local reference item; normally stays out of formal TOC

Rules:

• Preserve confirmed facts.
• Mark missing facts as [TODO: ...], [FIX: ...], or [DRAFT: ...].
• Use <TableCaption>...</TableCaption> before captioned tables.
• Do not hand-maintain figure/table numbers.
• Public content belongs in registered MDX sources. Internal planning belongs in press/design.md, memory/, or skills.
• For teaching notes, course handouts, worksheets, study guides, or tutorials, write to the learner: compare nearby concepts, show state-changing procedures step by step, add short practice checks only when useful, and place answers after the learner has had a chance to attempt.
• For programming teaching material, introduce the data shape before long code, break helper functions apart before the complete version, keep identifiers consistent across prose/tables/diagrams/code, and include expected output or final state when it helps verification.

Use open-press search to locate content before editing:

# 找哪個章節提到某個關鍵字，回傳 page id + 行號
open-press search . "<query>" --json

# 含 components / theme / design.md 一起搜
open-press search . "<query>" --scope all --json

Portable skill triggers:

Resolve conflicts in this order: explicit user instruction → workspace memory/design.md → document brief → this skill's structural decisions → portable language skill rules.

---

Verify

Draft marker scan before build:

# 確認沒有未完成標記殘留
open-press search . "[TODO:" --scope all --json
open-press search . "[DRAFT:" --scope all --json
open-press search . "[FIX:" --scope all --json

Fresh or structural edit:

npm run build

When PDF readiness matters:

npm run openpress:pdf

Report: Press slug, title, geometry, source root, theme paths written, next editable paths, verification result.

---

When to Read References

• Press Tree & folder layout: read references/press-tree.md — canonical folder structure, Press Tree TSX example, path resolution rules.
• Theme & page components: read references/theme.md — paths to write, theme rules, CSS constraints.

---

Do Not

• Do not use npm create @open-press or open-press create as an upgrade or migration tool.
• Do not edit generated output.
• Do not publish.
• Do not write unsupported facts.

Press Tree & Folder Contract

Pages Press Tree Default Shape

import { Press } from "@open-press/core";
import { mdxSource } from "@open-press/core/mdx";
import { Sections, Toc } from "@open-press/core/manuscript";

export default function ReportPress() {
  return (
    <Press
      slug="report"
      title="Report Title"
      type="pages"
      page="a4"
      sources={[
        mdxSource({ id: "report", preset: "section-folders", root: "report/chapters" }),
      ]}
    >
      <Cover />
      <Toc source="report" maxLevel={2} />
      <Sections source="report" />
      <BackCover />
    </Press>
  );
}

Recommended Folder Layout

press/<slug>/press.tsx               ← canonical entry
press/<slug>/chapters/               ← MDX source root
press/<slug>/components/             ← page components (Cover, BackCover, etc.)
press/<slug>/theme/                  ← artifact-local tokens, prose rules, and font loading
press/<slug>/theme/tokens.css
press/<slug>/theme/fonts.css
press/<slug>/theme/prose.css
press/<slug>/theme/fonts/            ← optional self-hosted font files
press/design.md                      ← shared user/agent design source

Use per-Press folders for multi-Press workspaces. Create press/shared/ only when multiple Press folders intentionally share assets, facts, or components. The framework supplies the generic page-contract.css, print route reset, and measurement shell; workspace themes adjust shell behavior through tokens, local prose CSS, and React/Tailwind component classes. Do not add shared base/*.css. New page-specific surfaces should live in React components with Tailwind classes. Do not add shared page-surfaces/, shell/, or patterns/ CSS.

Component & Media Path Resolution

• Default authoring: pass folder-local ./components and ./media on <Press>
• Custom path: set <Press componentsDir> or <Press mediaDir> to a string or string array
• Paths starting with ./ resolve relative to the owning Press folder
• Bare paths resolve relative to press/

Theme & Page Components

Paths to Write or Update

press/design.md
press/<slug>/theme/tokens.css
press/<slug>/theme/fonts.css
press/<slug>/theme/fonts/
press/<slug>/theme/prose.css
press/<slug>/components/

Theme Rules

• Keep page geometry on <Press page>, not CSS.
• Treat the framework page-contract.css as read-only; customize the shell with CSS variables and page components.
• Use press/design.md as the shared user/agent design source.
• Put new theme tokens, self-hosted font loading, and pagination-sensitive prose rules under press/<slug>/theme/; do not create press/shared/ unless the user explicitly wants a shared multi-Press asset pool.
• Keep PDF-safe fixed-layout CSS: no uncontrolled overflow, no local-only font dependency for public/PDF output.
• Use components as reading aids: definitions, figures, tables, KPI surfaces, callouts, and reusable page shells.
• Put cover, back-cover, TOC, and other page-specific surfaces in React components with Tailwind classes by default.
• Keep MDX prose styling in local page components or press/<slug>/theme/prose.css; do not create shared base/*.css.
• Do not use remote Google Fonts @import or other network font CSS in final Press themes. Use @font-face with files in press/<slug>/theme/fonts/, or explicitly choose system fonts.
• Define font roles in tokens.css: body, serif, mono, and optional display. Use the role tokens from page components and prose CSS instead of repeating raw family stacks.
• For mixed Chinese/English documents, self-host a Latin brand font when needed, then list local Traditional Chinese fallback fonts. Bundle licensed CJK subsets only when the project requires identical Chinese glyphs across machines.
• Use Press-scoped tokens, then bridge them into framework/runtime variables:

:root {
  --report-font-body: "Report Sans Latin", "PingFang TC", "Noto Sans TC", sans-serif;
  --report-font-serif: "Noto Serif TC", "Songti TC", "Source Han Serif TC", serif;
  --report-font-mono: "SFMono-Regular", "Menlo", monospace;
  --report-font-display: var(--report-font-serif);

  --openpress-font-body: var(--report-font-body);
  --openpress-font-serif: var(--report-font-serif);
  --openpress-font-mono: var(--report-font-mono);
  --openpress-font-display: var(--report-font-display);
}

• Do not create press/shared/theme/page-surfaces/, press/shared/theme/shell/, or press/shared/theme/patterns/; active work should use React/Tailwind instead.
• Avoid interactive UI patterns inside formal documents.
• For multi-Press workspaces, keep shared Tailwind @theme entries variable-backed and generic. Put artifact-specific values under a Press-scoped wrapper or page component so slides, pages, and social formats do not pollute each other.

Theme Inputs to Gather

• Primary ink color
• Accent color
• Font plan:
• body —正文、表格、caption、註解
• serif —書名、章節標題、正式敘事
• mono —code、路徑、資料欄位
• display —封面大標，可選
• Chinese/English font configuration: self-hosted Latin face, system CJK fallback, or licensed self-hosted CJK subset
• Optional reference aesthetic

Self-hosted Font Pattern

Prefer .woff2 files in the Press theme:

press/<slug>/theme/
  fonts.css
  tokens.css
  prose.css
  fonts/
    report-sans-latin-400.woff2
    report-sans-latin-600.woff2

@font-face {
  font-family: "Report Sans Latin";
  src: url("/openpress/fonts/report-sans-latin-400.woff2") format("woff2");
  font-weight: 400;
  font-style: normal;
  font-display: swap;
}

OpenPress copies press/<slug>/theme/fonts/ to /openpress/fonts/ during export. In multi-Press workspaces, give font files unique names so Presses do not accidentally overwrite each other's files in the shared public font folder.

tokens.css should hold stable design values, not selector rules. Good token subjects: palette, font roles, type scale, line-height, spacing scale, chart/status colors, and page geometry fallbacks. Put element-specific behavior such as table cell padding, figure max-height, or code block wrapping in prose.css or component CSS.