Skip to content

Latest commit

 

History

51 Commits

Folders and files

Repository files navigation

DevCapsule Website

The presentation project for DevCapsule: an Eleventy static site with a landing page, navigable user guides, and a development journal. The authoritative content lives in mycodespace-ai/devcapsule. This repository owns layouts, styles, navigation, and the publishing machinery. Website functionality and follow-up work are tracked in BACKLOG.md; content and parent integration remain in DevCapsule. The owner authorized this backlog handoff on 2026-09-19.

Preview inside DevCapsule's repository

From the parent checkout:

git submodule update --init website
./scripts/website.sh install
./scripts/website.sh preview

Open the URL printed by the server, normally http://127.0.0.1:8080/. It binds only to loopback and tries subsequent ports if the requested port is occupied. Set PORT=8090 to start elsewhere. The development server watches content and presentation files; refresh your browser after its rebuild message. Stop with Ctrl+C. Failed rebuilds retain the last successful output.

Develop this project independently

Use Node 22 or later and Git. No parent submodule update is necessary:

git clone git@github.com:mycodespace-ai/devcapsule-website.git
cd devcapsule-website
# During initial review only: git switch initial-cut
npm ci
npm run content:fetch
npm run dev

content:fetch creates an ignored .content/ checkout of DevCapsule without initializing any of its submodules. Set CONTENT_REF to a branch, tag, or commit to select a different content revision. It refuses to overwrite local content edits. This avoids circular setup: the website can be developed before its parent updates the submodule pointer.

DEVELOPING-WITH-CONTENT.md explains what the copy must contain, how to experiment on a scratch copy, and which check to run when. Alternatively, use an existing content checkout:

CONTENT_DIR=/absolute/path/to/devcapsule npm run dev

Inside the parent, its checkout is the default content source. Standalone, .content/ is the default. CONTENT_DIR overrides both. Edit src/assets/site.css for styling (tokens first: type, spacing and every colour scheme are defined at its top, Catppuccin latte being the default, and components use only tokens), src/_includes/ for layouts, and scripts/content.mjs for routing and navigation. Keep substantive product prose in the DevCapsule repository.

This project's own capsule

Install DevCapsule using the current first-session guide. From a standalone clone on your host:

~/.local/bin/devcapsule project init
~/.local/bin/devcapsule project run

The committed configuration selects VSCodium and Node, with a platform lock generated by DevCapsule's resolver. It recommends host networking so your host browser can open the loopback preview; init asks for your authorization. This shares the host network, including its services. You may decline and use a browser inside the capsule instead. No host Docker socket, home directory, or agent credential access is requested by this project.

Inside the IDE terminal run npm ci, npm run content:fetch, then npm run dev. Choose any additional AI component using DevCapsule's normal local setup. The initial cut belonged to the parent website workstream. Following the owner's backlog handoff, independent work uses this project's single-stream handoff in CURRENT-STATUS.md.

Validate

npm test
npm run build
npm run check
npm run check:content
npx playwright install chromium
# Keep npm run dev running in another terminal:
npm run test:browser
# After committing the implementation, test a clean standalone clone:
npm run test:updates

Set PREVIEW_URL for browser checks when the server selected a different port or base path. Browser checks cover representative pages at desktop and mobile widths in the system day and night palettes and in every selectable colour scheme, keyboard/anchor navigation, WCAG A/AA automated checks, the colour-scheme picker and its persistence, and navigation without JavaScript. Screenshots and the audit record go to ignored .artifacts/. Visual review and owner acceptance remain necessary. Browser dependencies may require your environment administrator's help on a minimal machine; ordinary builds and previews need only Node/npm and Git.

npm run build writes _site/; npm run check verifies all local links and fragments, image labels, document structure, revision metadata, and that sitemap.xml lists exactly the indexable pages (none in a preview build). Production configuration and publication are described in PUBLISHING.md.

Content contract

CONTRACT.md is the accepted content–website contract, version 1 (backlog W12), implementing the producer's design of 2026-09-28. In short: the build consumes README.md as the landing page and dated Markdown journal entries below engineering-docs/blog/ from the content checkout, and builds the documentation tree docs/ once per version listed in docs/versions.yaml, each from its own Git source, with /docs/current/ as the canonical copy of the current version, a versions index at /docs/, a per-page version switcher and status banners. Every page under docs/ and the journal carries front matter (description, draft, status, aliases, weight, updated, and role on the six entry pages); versioned pages write {{version}} tokens instead of typed versions. Each failure names the file, field, version or role. npm run check:content runs the same assembly without output, for the producer's gate.

Root README.md supplies the landing prose through marked sections (<!-- website:hero --> and the others in CONTRACT.md 3.7); the three pillars are the role pages of the current version. A README without markers is still read by the original heading adapter. The journal is served at /journal/ with /blog/ redirecting; /why/ and /contribute/ come from the README's marked sections. Links to non-published files resolve to the exact content revision on GitHub. Only referenced image assets are copied.

Every page footer shows when the site version was built, in UTC. The same ISO timestamp appears as builtAt in build-info.json, alongside content and implementation Git SHAs, dirty indicators, a digest of consumed content/assets, the contract version, every documentation version's source revision and status, base path, and build mode. Promotion preserves that original build time; it is not a deployment completion time or a claim that every article changed then. No local paths or credentials appear there. Content must be a Git checkout with the tags or branches the manifest names; a dirty preview is supported and identified. Rendered released versions are cached under ignored .cache/ by source commit.

Development brief · Requirements · Index

Releases

Packages

Used by

Contributors

Languages