Repository navigation
feat: scaffold MkDocs site and migrate inasafe-doc + WordPress content - #17
Merged
Merged
Conversation
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.
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).
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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.
docs/,structured like kartoza/InfrastructureMapper, branded as InaSAFE.
docs/) moved tolegacy-site/to free updocs/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.
(
scripts/migrate_sphinx_docs.pl) and inasafe.org's WordPress content —news, events, case studies, about, governance, contributing
(
scripts/migrate_wp_content.mjs).mkdocs build --strictpasses.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'tmigrated yet — tracked as a separate issue.
See SPECIFICATION.md for the full plan.