Files
portfolio/docs/content-editing.md
2026-11-10 14:19:34 +01:00

6.9 KiB

Content editing reference

The editable source is content/. content.js is a tracked generated browser module; dist/ is ignored build output. No dependency installation or public admin interface is needed.

Project workflow

  1. Run npm run project:add -- my-project from the repository root. IDs use lowercase letters, digits and single separating hyphens. The command refuses to overwrite an existing filename, creates placeholder content and regenerates the module.
  2. Replace placeholders in content/projects/my-project.json. Use the ID as the filename for consistency; routes use the id field, not the filename.
  3. Run npm run content for validation. Preview with npm run dev and refresh after saving. The preview compiles /content.js in memory on each request; it does not watch files or reload the browser automatically.
  4. Run npm test and npm run build, inspect both languages, then commit source and generated content together.

Delete a project's JSON file to remove it. Remove entries from its evidence array to remove evidence. Empty project collections and empty evidence arrays are supported. Renaming an ID breaks existing project links; keep IDs stable.

Project fields

Field Format and behavior
id Unique lowercase slug, for example my-project; used by #project/my-project
number Nonempty string; numeric-aware string sorting determines display order and the homepage feature. Use distinct numeric values such as 01, 02
challenge Nonempty string, including combined labels such as 14 + 15; use — for personal projects
kind, title, name, intro, context, implementation, decisions Two nonempty strings in [Dutch, English] order. title is required by validation but not currently rendered
stack Nonempty array of nonempty strings; technology badges
nodes Exactly three nonempty strings; schematic structure labels shown near the implementation explanation
path Repository-relative project directory path, without a leading slash or . / .. segments. An empty string links to the root only when repository is supplied
repository Optional object: url (HTTPS repository URL on github.com or codealvin.xyz), revision (40-character lowercase commit SHA), forge (github or gitea, matching the host). Applies to project and evidence links
setting Optional [Dutch, English] context, such as personal project or school year. Defaults to school project, year 2
codes Array of known process codes; dossier tags linking to the evidence index. May be empty
evidence Array of evidence objects; may be empty

Evidence objects require label ([Dutch, English]), path (nonempty and repository-relative), type (nonempty display label such as JS or DOCX) and codes (array of known process codes). Optional directory is a boolean: on GitHub, true creates a tree link and omitted or false creates a blob link. Gitea uses src/commit for both files and directories. Evidence paths always use their project's repository; individual evidence items cannot override it.

The scaffold supplies challenge: "—", path: "projects" and no repository or setting. Before publishing a personal project, set its repository and bilingual context explicitly; otherwise its links still target the school archive and its dossier context defaults to school year 2. Use a repository URL without a trailing slash, query or fragment, and copy the full reviewed commit SHA rather than a branch name.

Evidence counts come only from each evidence item's codes, not the project's codes. An item can map to several processes, so summed process counts can exceed the number of evidence items. Empty mappings are allowed and do not appear in process counts.

Shared settings and copy

content/settings.json supplies profile, revision and processes. Only these top-level keys are accepted. The compiler explicitly exports profile, revision, processes, projects and the source helper; arbitrary settings cannot become JavaScript exports.

  • profile.github and profile.gitea supply external profile links; profile.school supplies the repository base for source links.
  • profile.qualification supplies the qualification document link. profile.name and profile.reviewed are stored but are not currently rendered; visible identity and biography remain in app.js.
  • revision pins default school-archive source links; a project repository.revision overrides it. Review project and evidence paths against a new revision before updating it. Change profile.reviewed only after that review.
  • Each process has a unique code, bilingual title and bilingual description. The current tests expect eight processes.

Shared contribution and reflection placeholders are in app.js. Per-project reflections require a deliberate schema and renderer change; adding arbitrary JSON fields alone will not display them. index.html also contains static title, description, language fallback and a school repository link.

Validation limits

The compiler validates the exact settings and profile structure, nonempty name, valid ISO review date, safe HTTPS links without credentials, GitHub/Gitea profile hosts, the GitHub school repository, full lowercase commit pins, unique process codes (B-K-W, positive integers), and complete Dutch/English titles and descriptions. Project mappings must reference known codes. Optional project repositories require supported hosts, matching forge types and full commit pins. Validation does not check remote availability or assess evidence; review content accuracy manually. Text is rendered as escaped text, not Markdown or HTML.

The current tests deliberately assert that B1-K2-W1, W2 and W3 have no evidence yet. When genuine collaboration evidence is added, update that test to reflect the supported evidence and remaining gaps. Do not remove the safeguard simply to make unsupported mappings pass.

An invalid file causes preview /content.js to return HTTP 500 with a generic message. Run npm run content to see the underlying validation or JSON error. The scaffold command writes its new JSON file before compiling; if compilation fails, inspect the created file and fix the reported issue before retrying.

All generated content is public. The build includes settings and project fields even if the interface does not display them.

Reviewing repositories

Keep a dated record in repository-review.md. Review representative source files and verify all linked paths at the exact commit before adding a project. Account ownership alone does not establish authorship of every file. Avoid duplicating mirrors and do not present upstream forks as original work. New sources may use empty codes arrays until an exam mapping is supported; these links remain visible in the project dossier without changing process counts. The current six additions follow this policy.