Files
portfolio/docs/content-editing.md
T

4.8 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
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; shared diagram labels in both languages
path Repository-relative project directory path, without a leading slash or . / .. segments
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 (repository-relative), type (nonempty display label such as JS or DOCX) and codes (array of known process codes). Optional directory is a boolean: true creates a repository tree link; omitted or false creates a blob link.

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. Keep these top-level keys stable: they become ES module 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 every generated source link. 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 project fields and checks mapping codes against settings. It is not a complete settings schema validator, external-link checker or assessment tool. Review settings structure, URLs, unique process codes and 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.