Practical comparison: install, preview, deploy, and extend

This comparison is about the commands and files a developer must operate. It does not turn one benchmark run into a universal ranking. The linked commands are from each project's official documentation; Pageskill commands are the current CLI in this repository.

Pageskill is reuse-first: people can use built-in Patterns, Blocks, and schemas directly, while an Agent is an optional discovery helper. Page authors do not hand-write HTML for each page; a theme extension is implemented once only when the catalog shows a real capability gap.

The shortest working path

The output boundary is a deployment fact, not a cosmetic detail: the public snapshot is under dist/public, while target-specific server or Worker files remain private. Pageskill reads deployment destinations from config.yml. Static generation is the default rendering method: ordinary content is pre-generated, and interactive features call same-origin APIs when needed. One Worker/Fetch service can serve the generated pages and same-origin APIs; /api/* is handled by the Worker first by default, and other dynamic paths belong in deployment.dynamicRoutes. Do not expose build output containing private code as a CDN, Caddy, Nginx, or GitHub Pages root. Keep server/, _pagekiln/, .pagekiln/, Worker files, and *.toml private, and read secrets only at runtime.

Pageskill task recipes

Install a new site

npm install
npm run compile-runtime
npm run compile-theme
npm run compile-backend
npm link
pageskill init
pageskill check

The starter is a real source directory. Its config.yml, content/, and themes/ show the contract that the CLI copies.

Preview and edit

pageskill s
pageskill s --port=4174

The preview server watches config.yml, content/, and themes/. An affected Markdown, CSS, or theme edit rebuilds and reloads the browser while the process stays alive after a diagnostic error.

Deploy

deployment:
  targets: [cloudflare-pages, github-pages, vps]
  cloudflare:
    apiTokenEnv: CLOUDFLARE_API_TOKEN
    pages:
      project: example-site
      branch: production
  github:
    remote: origin
    branch: gh-pages
    tokenEnv: GITHUB_TOKEN
  vps:
    host: vps.example.com
    user: deploy
    port: 22
    remotePath: /var/www/example-site
    identityFile: ~/.ssh/id_ed25519

pageskill d --dry-run
pageskill d

The supported connectors are cloudflare-pages, cloudflare-workers, github-pages, vps, and the optional openai-sites handoff. Tokens stay in environment variables. VPS authentication uses the local SSH agent or an existing private key; the public key must already be authorized on the server. GitHub Pages publishes the dist/public snapshot only and does not run APIs, while a dynamic VPS backend belongs in a private server directory. Workers use assets.directory: public, with .assetsignore as an additional exclusion layer; Cloudflare Pages uses target-specific deployment staging so public static uploads contain only public resources. A Worker/Fetch deployment can serve generated pages together with same-origin dynamic APIs; /api/* is handled by the Worker first by default, and other dynamic paths belong in deployment.dynamicRoutes.

Develop a Block

content/pages/guide/en.md       current explanation
themes/default/theme.ts         Block renderer and schema
themes/default/theme.yml        Block/resource registration
themes/default/style.css        one visual owner

Implement the Block through defineTheme, register it in theme.yml, use it with a Markdown directive, and verify it with:

npm run compile-theme
pageskill catalog
pageskill inspect block:hero
pageskill check
pageskill g

The full example and security boundary are in the development guide.

What each tool makes you maintain

Pageskill

Content identity is explicit: content/pages/<id>/<locale>.md is current site content, and content/posts/<id>/<locale>.md is a dated Product Note with a required date. docs is a Pattern inside pages, not a parallel collection. config.yml owns site settings and deployment destinations; the copied theme owns Patterns, Blocks, CSS, browser ESM, and plugin presentation.

Astro

Astro's official install guide starts with npm create astro@latest. Its development and build guide uses npm run dev and npm run build; .astro pages, components, integrations, and content collections form the extension surface. Choose this path when component and integration code is the primary authoring model.

Eleventy

Eleventy's official site demonstrates Markdown, templates, npx @11ty/eleventy --serve, and _site/. Its Data Cascade and Collections are the main organization surfaces. Choose this path when multiple template languages and data composition are central.

Hugo

Hugo's quick start uses hugo new site, hugo server, and hugo; its output is public/. Content organization and shortcodes place structure in the content tree and layouts. Choose this path when sections, taxonomies, templates, and a native binary are the priority.

VitePress

VitePress's getting started guide uses npx vitepress init, npm run docs:dev, and npm run docs:build. Its Vue-in-Markdown guide makes Vue components and client behavior part of document authoring. Choose this path when the documentation site is a Vue application.

Docusaurus

Docusaurus's installation guide uses a React-based starter, npm run start, and npm run build; its i18n guide covers locale directories and theme/plugin translations. Choose this path when docs sidebars, versions, MDX, and React plugins are required.

Choose by the next concrete task

• Need a Markdown-first product site with explicit current pages, dated Product Notes, locales, search, archive, sitemap, and static deployment: use Pageskill and start with the Guide.
• Need .astro components or an integration ecosystem: follow Astro's official starter.
• Need template-language choice and Data Cascade: follow Eleventy's starter.
• Need sections, taxonomies, shortcodes, and a native binary: follow Hugo's quick start.
• Need Vue components inside a documentation site: follow VitePress.
• Need React/MDX docs with sidebars, versions, and plugin translations: follow Docusaurus.

The decision should follow the next file you need to write. For Pageskill, that file is content/pages/ for current usage, content/posts/ for a dated change, or themes/<name>/theme.ts for a new Block.