Skip to content

Feature: WYSIWYG page editor that submits simple edits as a GitHub pull request #75

Open

Description

@XtremeOwnageDotCom

Summary

Add a WYSIWYG editor to Netdocs sites so a reader can make simple changes to a page (typo fixes, rewording, small content updates) directly in the browser, and have those changes submitted as a pull request against the site's GitHub repository.

Motivation

Today the Material theme's "edit this page" action (built from repoUrl + editUri, see SourceLinkBuilder) sends the user to GitHub's raw Markdown editor. That works for people comfortable with Markdown and GitHub, but it's a high bar for quick fixes. A rendered, in-place editor would make small contributions much easier while keeping GitHub PRs as the review gate.

Proposed behaviour

  1. On a page with a configured repoUrl/editUri, the edit action opens an in-page WYSIWYG editor instead of (or alongside) the GitHub link.
  2. The editor works on the page's source Markdown and supports simple edits: text, headings, lists, links, emphasis, inline code. Anything it can't round-trip safely (admonitions, tabs, Mermaid, snippets, front matter, raw HTML) stays untouched or read-only.
  3. On submit, the user enters a short description and the change is submitted as a PR:
    • create a branch (on a fork if the user lacks write access),
    • commit the updated Markdown file,
    • open a PR with the description, linking back to the page.
  4. The user sees the resulting PR link.

Design considerations

  • Markdown round-tripping: edits must produce a minimal diff. Re-serializing the whole file would reformat unrelated content; editing only the changed blocks, or a Markdown-native editor, is preferable.
  • Imported docs: pages pulled from other repositories already get their own edit links (fix: point imported docs' edit/view links at their own repository #59). The editor should target the same repository/path those links use.
  • Authentication: Netdocs output is static, so the GitHub step needs either a GitHub OAuth/device flow in the browser or a small optional backend. Avoid storing tokens server-side.
  • Opt-in: off by default, enabled via a theme/plugin setting in appsettings.json, so existing sites are unaffected.
  • Dev server: netdocs serve could optionally save edits straight to the local file instead of opening a PR, which would be useful for authors.

Acceptance criteria

  • Opt-in config setting to enable the editor.
  • Editing a simple page and submitting creates a PR with only the intended lines changed.
  • Unsupported Markdown constructs are preserved byte-for-byte.
  • Works for imported docs that edit a different repository.
  • Docs page in docs-site describing setup and authentication.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions