Skip to content

feat(wiki): preserve hand-authored custom pages across export#2159

Open
TomaszWu14 wants to merge 1 commit into
Graphify-Labs:v8from
TomaszWu14:feat/preserve-custom-wiki-pages
Open

feat(wiki): preserve hand-authored custom pages across export#2159
TomaszWu14 wants to merge 1 commit into
Graphify-Labs:v8from
TomaszWu14:feat/preserve-custom-wiki-pages

Conversation

@TomaszWu14

Copy link
Copy Markdown

Problem

graphify export wiki deletes every wiki/*.md at the start of each run:

for old_article in out.glob("*.md"):
    old_article.unlink()

This exists to clear orphaned community articles (LLM-generated labels are non-deterministic, so a renamed community would otherwise leave its old file behind). But it also deletes any page a user added by hand — custom analysis, notes, topology deep-dives — with no way to keep them. Re-running the export silently wipes them, and there's no opt-out.

Fix

to_wiki now tracks the files it generates in a .graphify_wiki_files.json manifest and, on re-export, deletes only its own prior output (files it generated last run but not this run — e.g. renamed communities). Any file graphify never wrote is left untouched.

Preserved pages are also auto-listed in a Custom Pages section of index.md, titled by their first markdown # H1 (falling back to a de-slugged filename), so they stay reachable from the agent entry point instead of becoming orphans.

Migration safety: the first run after upgrade has no manifest, so it deletes nothing — existing custom pages survive. Self-generated orphans are cleaned up from the next run onward.

Behavior

  • Community/god-node articles regenerate exactly as before (byte-identical on an unchanged graph).
  • A hand-authored my-analysis.md now survives re-export and appears under ## Custom Pages in the index.
  • Renaming a community still removes its stale article (verified by test).

Tests

Adds 5 tests to tests/test_wiki.py:

  • test_to_wiki_preserves_custom_pages
  • test_index_lists_custom_pages_by_h1
  • test_to_wiki_removes_only_its_own_orphans
  • test_to_wiki_writes_manifest
  • test_custom_page_without_h1_falls_back_to_filename

pytest tests/test_wiki.py35 passed (30 existing + 5 new).

Notes

  • import json moved to module level (was needed by the new manifest read/write).
  • No public API change; to_wiki's signature is unchanged. _index_md gains an optional custom_pages argument.

`graphify export wiki` deleted every `wiki/*.md` at the start of each run
(to clear orphaned community articles, since LLM labels are non-deterministic).
That also deleted any page a user added by hand — custom analysis, notes — with
no way to keep them.

Instead, track generated files in a `.graphify_wiki_files.json` manifest and on
re-export delete only our own prior output (files generated last run but not
this run, e.g. renamed communities). Any file graphify never wrote is preserved.
Preserved pages are auto-listed in a "Custom Pages" section of index.md, titled
by their first markdown H1, so they stay reachable from the entry point.

First run after upgrade has no manifest and deletes nothing, so existing custom
pages survive the migration; orphans self-heal on the next run.

Adds 5 tests covering preservation, index linking, own-orphan cleanup, the
manifest, and the no-H1 title fallback.
@TomaszWu14

Copy link
Copy Markdown
Author

Friendly heads-up: this PR is a first-time contribution, so the CI workflows are sitting in action_required pending maintainer approval. Whenever a maintainer has a moment, could you approve the workflow run so the checks can execute? Happy to address anything they surface. Thanks for the great tool! 🙏

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