docs: define Starlight wiki migration
This commit is contained in:
msa46
commit
19bee8539c
1 changed files with 222 additions and 0 deletions
|
|
@ -0,0 +1,222 @@
|
|||
# Incognito Starlight Wiki Migration Design
|
||||
|
||||
## Summary
|
||||
|
||||
Build a public, read-only MSV Incognito knowledge base with Astro Starlight in the existing `Incognito-Wiki` Git repository. Authorized Incognito members will maintain the site through Git. The published site will contain only the Incognito material from the DokuWiki export, rewritten manually as Markdown or MDX and reviewed page by page.
|
||||
|
||||
The newer live wiki is not a content source for this migration. Its contents will be captured separately under `to-be-studied/` so Incognito members can compare them with the export later without publishing them in Starlight.
|
||||
|
||||
## Goals
|
||||
|
||||
- Create a maintainable Starlight project in `/Volumes/S/Incognito/Incognito-Wiki`.
|
||||
- Publish the exported Incognito and study content as a searchable static website.
|
||||
- Preserve empty course and year pages as visible placeholders.
|
||||
- Correct spelling, punctuation, capitalization, and obvious grammar errors without changing meaning.
|
||||
- Repair links when their intended destinations can be established safely.
|
||||
- Identify potentially outdated information explicitly instead of silently inventing replacements.
|
||||
- Reuse current MSV Incognito brand assets and visual cues where practical.
|
||||
- Support local builds, Netlify, and an optional GitHub Pages deployment from the mirrored repository.
|
||||
- Preserve newer live-wiki material outside the published content tree for later study.
|
||||
|
||||
## Non-goals
|
||||
|
||||
- Do not migrate the generic DokuWiki documentation under `pages/wiki/`.
|
||||
- Do not add authentication, authorization, user accounts, or browser-based editing.
|
||||
- Do not use the newer live wiki to replace or expand the published exported content.
|
||||
- Do not modernize uncertain academic facts by guessing.
|
||||
- Do not require CI on the private Forgejo server.
|
||||
- Do not build a general-purpose DokuWiki conversion utility.
|
||||
|
||||
## Source and Destination Scope
|
||||
|
||||
The export contains 32 text pages and no media files. The migration includes the 29 relevant pages represented by `pages/start.txt` and `pages/study/**`. It excludes the three generic pages under `pages/wiki/`.
|
||||
|
||||
Published content will live only in `src/content/docs/`. The intended top-level routes are:
|
||||
|
||||
- `/`
|
||||
- `/bachelor/`
|
||||
- `/bachelor/year-1/`
|
||||
- `/bachelor/year-2/`
|
||||
- `/bachelor/year-3/`
|
||||
- `/master-ai/`
|
||||
- `/master-dsdm/`
|
||||
- `/useful-information/`
|
||||
- `/about-incognito/`
|
||||
|
||||
Child course and guide pages will follow the corresponding section route. Route names will use lowercase kebab-case. A manual source-to-destination inventory in `docs/migration-report.md` will make every mapping explicit.
|
||||
|
||||
## Architecture
|
||||
|
||||
The repository will use a conventional Astro Starlight structure:
|
||||
|
||||
```text
|
||||
Incognito-Wiki/
|
||||
├── .github/workflows/ # Optional checks/Pages deployment on GitHub mirror
|
||||
├── docs/ # Maintainer documentation and migration report
|
||||
├── public/ # Favicons and unprocessed public assets
|
||||
├── src/
|
||||
│ ├── assets/ # Bundled Incognito images and logos
|
||||
│ ├── content/docs/ # The only published wiki content
|
||||
│ └── styles/ # Incognito Starlight theme overrides
|
||||
├── to-be-studied/ # Unpublished captures and comparison material
|
||||
├── astro.config.mjs
|
||||
├── netlify.toml
|
||||
├── package.json
|
||||
└── tsconfig.json
|
||||
```
|
||||
|
||||
Astro produces a static `dist/` directory. Starlight provides navigation, local search, page tables of contents, previous/next links, accessible documentation layout, and light/dark theme behavior. No runtime server or database is required.
|
||||
|
||||
The sidebar will be configured manually. This keeps the intended academic hierarchy stable and ensures that empty placeholder pages remain discoverable.
|
||||
|
||||
## Manual Migration Method
|
||||
|
||||
Each included DokuWiki source page will be rewritten manually and checked against the original. There will be no source-to-Markdown converter.
|
||||
|
||||
For every page, the migration will:
|
||||
|
||||
1. Add explicit Starlight frontmatter, including a page title and description.
|
||||
2. Convert headings, paragraphs, lists, tables, emphasis, code, and embeds to valid Markdown or MDX.
|
||||
3. Convert DokuWiki namespace links to their final Starlight routes.
|
||||
4. Correct spelling and obvious grammatical errors while preserving the original meaning.
|
||||
5. Remove DokuWiki-only controls such as `NEWPAGE`, `indexmenu`, and `NOCACHE`.
|
||||
6. Remove obsolete instructions about DokuWiki registration, upload permissions, and browser editing.
|
||||
7. Add status notices for outdated information, missing assets, or intentionally empty content as needed.
|
||||
8. Record the source, route, and material editorial decisions in the migration report.
|
||||
|
||||
## Editorial Policy
|
||||
|
||||
### Corrections
|
||||
|
||||
Spelling, punctuation, capitalization, and clear grammatical mistakes will be corrected directly. A correction that could change the factual meaning must instead be recorded for review in the migration report.
|
||||
|
||||
### Outdated information
|
||||
|
||||
Time-sensitive material that originated in the old wiki and cannot be confirmed safely will remain available for historical context with a consistent Starlight warning callout:
|
||||
|
||||
> This information originated in the previous wiki and may be outdated.
|
||||
|
||||
The notice may include a more specific explanation when the reason is known, such as an old department name, superseded service, historical course structure, or dated hardware guidance. The migration will not present uncertain replacements as facts.
|
||||
|
||||
### Empty pages
|
||||
|
||||
Empty course and year pages will retain their titles, routes, breadcrumbs, and sidebar entries. Their body will show a neutral notice:
|
||||
|
||||
> This page is awaiting content.
|
||||
|
||||
This distinguishes intentional placeholders from migration failures.
|
||||
|
||||
### Missing assets
|
||||
|
||||
The export contains references to media such as `study:dke-schedule.png`, but includes no media files. A missing embed will not remain as a broken image. The page will show a visible missing-asset notice, and the expected source identifier and affected destination page will be recorded in the migration report.
|
||||
|
||||
## Link Policy
|
||||
|
||||
- Internal DokuWiki links will point to final Starlight routes.
|
||||
- Links to excluded generic DokuWiki documentation will be removed unless they remain necessary for understanding the content.
|
||||
- External links will be checked during migration.
|
||||
- An obsolete external URL may be replaced only when its intended official successor is unambiguous.
|
||||
- An unresolved or missing internal target will be rendered as explanatory text rather than a knowingly broken link and recorded in the migration report.
|
||||
- The production site will be checked for broken internal links before completion.
|
||||
|
||||
## Branding and User Experience
|
||||
|
||||
Official Incognito logos, favicon assets, colors, and appropriate graphical material will be sourced from the current MSV Incognito association site. Source URLs and retrieval dates will be recorded. Assets will be optimized for the documentation site while preserving their proportions and legibility.
|
||||
|
||||
The interface will keep Starlight's documentation-first layout rather than reproduce the main association site's marketing layout. Brand customization will cover:
|
||||
|
||||
- Logo and favicon
|
||||
- Primary and accent colors
|
||||
- Light and dark theme color tokens
|
||||
- Header identity and short wiki description
|
||||
- A prominent link back to the association website
|
||||
- Repository edit links for authorized maintainers
|
||||
|
||||
Status presentation will be consistent and restrained: warnings for possibly outdated information, neutral notices for empty pages, and error-style notices only for missing source assets.
|
||||
|
||||
The result must remain readable on long academic pages, usable by keyboard, responsive on mobile and desktop, and compatible with light and dark themes.
|
||||
|
||||
## Newer Live-Wiki Material
|
||||
|
||||
Newer material from `wiki.msvincognito.nl` will be kept under `to-be-studied/`, outside Starlight's content collection and static asset directories. It must not appear in the built site.
|
||||
|
||||
The research area will contain:
|
||||
|
||||
```text
|
||||
to-be-studied/
|
||||
├── README.md # Purpose, capture method, and non-publication rule
|
||||
├── live-wiki/
|
||||
│ └── 2026-08-02/ # Human-readable page captures
|
||||
├── manifest.json # Source URL, title, capture date, and local path
|
||||
└── comparison.md # New-only, overlapping, and materially changed pages
|
||||
```
|
||||
|
||||
Each captured page will retain its source URL and capture date. The comparison will identify:
|
||||
|
||||
- Pages present only on the newer live wiki
|
||||
- Pages present only in the export
|
||||
- Pages that overlap
|
||||
- Obvious structural or substantive differences in overlapping pages
|
||||
|
||||
The comparison is an inventory for later review, not a decision to merge newer content into the published wiki.
|
||||
|
||||
## Maintenance Workflow
|
||||
|
||||
The published site is public and requires no login. Incognito members with repository access maintain Markdown or MDX through the private Forgejo repository. The repository may be mirrored to GitHub for deployment.
|
||||
|
||||
Maintainer documentation will explain:
|
||||
|
||||
- How to install dependencies
|
||||
- How to run the local development server
|
||||
- How to add or edit a page
|
||||
- How to update the manual sidebar
|
||||
- How to use the standard status notices
|
||||
- How to run checks and produce a static build
|
||||
|
||||
No secrets or authentication data will be committed.
|
||||
|
||||
## Validation and Error Handling
|
||||
|
||||
Local commands are the source of truth because Forgejo has no CI requirement. The project will expose scripts for development, formatting or linting, Astro validation, link checking, and the production build.
|
||||
|
||||
Validation will cover:
|
||||
|
||||
- Valid Astro and Starlight configuration
|
||||
- Valid content frontmatter and MDX
|
||||
- Successful static production build
|
||||
- Working internal links and routes
|
||||
- No accidental publication of `to-be-studied/`
|
||||
- Presence of every included source page in the migration report
|
||||
- Explicit handling of every missing asset and unresolved link
|
||||
- Representative desktop and mobile pages in light and dark themes
|
||||
- Search and sidebar discoverability for both populated and empty pages
|
||||
|
||||
When a source ambiguity cannot be resolved, implementation will preserve the source meaning, add a visible notice if readers could otherwise be misled, and document the issue instead of guessing.
|
||||
|
||||
## Deployment
|
||||
|
||||
The site will not depend on Forgejo CI.
|
||||
|
||||
- `npm run build` will always produce the deployable `dist/` directory locally.
|
||||
- `SITE` and `BASE` environment variables will allow root-domain or repository-subpath deployments.
|
||||
- `netlify.toml` will define the Netlify build command and output directory.
|
||||
- An optional workflow under `.github/workflows/` may validate and deploy the GitHub mirror to GitHub Pages.
|
||||
- Forgejo will ignore the GitHub-specific workflow files.
|
||||
- Deployment-specific configuration can be removed without affecting local development or the Starlight build.
|
||||
|
||||
The final public hostname does not need to be chosen to build the project. It must be provided before production deployment so canonical URLs and any required base path can be verified.
|
||||
|
||||
## Completion Criteria
|
||||
|
||||
The migration is complete when:
|
||||
|
||||
1. Starlight installs and builds successfully from a clean checkout.
|
||||
2. All 29 included exported pages have documented destination outcomes.
|
||||
3. No generic `pages/wiki/` content is published.
|
||||
4. Internal navigation, sidebar links, and representative external links work.
|
||||
5. Empty pages remain visible and are clearly marked.
|
||||
6. Potentially outdated content, missing media, and unresolved links are explicitly handled and reported.
|
||||
7. Incognito branding is present and legible in both themes.
|
||||
8. The newer live-wiki captures and comparison exist only under `to-be-studied/`.
|
||||
9. Maintainers can edit content and validate or build the site without CI.
|
||||
10. The production build is suitable for either Netlify or the mirrored GitHub Pages repository.
|
||||
Loading…
Add table
Reference in a new issue