60 lines
6.9 KiB
Markdown
60 lines
6.9 KiB
Markdown
# 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<number>-K<number>-W<number>, 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](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.
|