Skip to content

feat: scaffold MkDocs site and migrate inasafe-doc + WordPress content - #17

Merged
timlinux merged 5 commits into
mainfrom
feature/mkdocs-site-migration
Oct 20, 2026
Merged

timlinux merged 5 commits into
mainfrom
feature/mkdocs-site-migration

Conversation

@timlinux

Copy link
Copy Markdown
Contributor

Bundles SRS Phases 0-2 (see SPECIFICATION.md) because they're interdependent:
a strict mkdocs build needs both the skeleton and real content to validate.

  • Adds a Nix-flake-provisioned MkDocs Material site under docs/,
    structured like kartoza/InfrastructureMapper, branded as InaSAFE.
  • The legacy WordPress static export (previously also at docs/) moved to
    legacy-site/ to free up docs/ as the canonical mkdocs source tree.
    Kept around for reference until the Phase 4 hosting cutover is verified,
    then deleted in a follow-up PR — nothing in it is modified by this PR.
  • Migrates inasafe-doc's user manual + training curriculum
    (scripts/migrate_sphinx_docs.pl) and inasafe.org's WordPress content —
    news, events, case studies, about, governance, contributing
    (scripts/migrate_wp_content.mjs).
  • Full nav wiring for every migrated page; mkdocs build --strict passes.

Needs your decision before merge: no LICENSE file was found anywhere in
this repo's history. Nothing was assumed/invented — add a LICENSE (and a
REUSE.toml once one exists) before merging, or tell me what to add.

Known follow-up (not in this PR): docs/for-users, for-coders,
for-translators, for-documentation-writers-and-designers,
publications, risk-and-vulnerability, and the per-author pages weren't
migrated yet — tracked as a separate issue.

See SPECIFICATION.md for the full plan.

Tim Sutton added 4 commits October 20, 2026 09:34
Adds flake.nix (mkdocs + mkdocs-material + plugins provisioned from
nixpkgs python3Packages), .envrc, pre-commit config, and lint configs
(markdownlint, yamllint, cspell) ahead of migrating content from
inasafe-doc and the former WordPress site into this repo.
…docs

Converts the legacy static-HTML WordPress export for these 5 sections
into Markdown via a reusable extraction script (scripts/migrate_wp_content.mjs),
rehomes referenced wp-content/uploads images into per-section assets/
dirs, builds index pages, and nests About/Contributing in the mkdocs nav.

Page-builder templates (about-inasafe/*, for-*) lack a clean content
wrapper, so those pages carry a manual-review TODO banner pending a
human pass; news/events/case-studies posts converted cleanly from their
article/entry-content structure.
Adds a Nix-flake-provisioned MkDocs Material site (modelled on
kartoza/InfrastructureMapper's structure, InaSAFE's own branding) under
docs_new/, kept deliberately separate from docs/ (the still-live legacy
WordPress static export) until the hosting cutover.

Migrates content via automated conversion scripts:
- scripts/migrate_sphinx_docs.pl: inasafe-doc's RST user manual and
  training curriculum -> docs_new/manual, docs_new/training
- scripts/migrate_wp_content.mjs: inasafe.org's WordPress HTML export
  (news, events, case studies, about, governance, contributing) ->
  docs_new/{news,events,case-studies,about,contributing}

Full nav wiring for all migrated sections. Fixes several WP-era
permalink/byline artifacts (dead author-archive links, mis-pathed
relative links) that failed a strict build. REUSE.toml/LICENSES/ added
as a placeholder (CC-BY-4.0) since no LICENSE file exists anywhere in
this repo's history — needs an explicit decision, see SPECIFICATION.md.

docs/ is untouched; nothing is deleted or renamed there.
A separately-running agent revisited this branch after the first fix and
reverted the docs_new/ -> docs/ canonicalization, re-adding a REUSE.toml +
LICENSES/CC-BY-4.0.txt placeholder license that was never authorized --
no LICENSE file exists anywhere in this repo's history, and inventing one
is a legal decision for the maintainers, not something to fabricate.

- Re-apply: legacy WordPress export -> legacy-site/, docs_new/ -> docs/
- mkdocs.yml, Docs.yml, cspell.config.yaml: docs/ paths restored
- scripts/migrate_wp_content.mjs: LEGACY_DOCS/DOCS split restored
- Remove REUSE.toml, LICENSES/CC-BY-4.0.txt, and the SPDX-License-Identifier
  header it added to flake.nix. Licensing is an open question for the
  maintainers -- see SPECIFICATION.md -- not something to default to.
- Keep the legitimate additions from that run: flake.lock, gitleaks +
  nodejs in flake.nix's devShell (needed to run the .mjs migration script),
  and the cspell package name fix.
@timlinux timlinux self-assigned this Oct 20, 2026
CI failed building the nix devShell: the nixos-unstable revision this
flake had resolved to (by tracking the branch rather than a pin) ships a
broken python3.14-reuse derivation whose builder doesn't produce its
'man' output.

- Pin inputs.nixpkgs.url to the same revision already used by the
  inasafe and GeoE3 flakes (2026-06-15), known to build cleanly.
- Drop pkgs.reuse from the devShell: it isn't wired to anything yet (no
  REUSE.toml/LICENSE exists) and was the specific package that failed.
  Re-add once a license is decided.
- flake.lock regenerated for the new pin (hand-written from the
  identical nixpkgs input already locked in inasafe/flake.lock, since
  this sandbox has no working nix daemon to run 'nix flake lock' -- the
  underlying CI run should be re-verified once this merges).
@timlinux
timlinux merged commit 431f3b5 into main Oct 20, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant