Edit TechDocs Without Leaving Backstage: The TechDocs Editor Plugin

If you have rolled out TechDocs in Backstage, you have probably seen this pattern: the documentation looks great, but only a handful of engineers are comfortable updating it. Everyone else gets stuck at "open GitHub, find the repo, create a branch, open a pull request" and quietly gives up.

That gap is why I built TechDocs Editor, an in-app TechDocs editor for Backstage. It lets teams edit documentation directly from the developer portal and open pull or merge requests without leaving the browser. It is also listed in the official Backstage plugin directory, alongside the source on GitHub.

In this post:

  • Why TechDocs is powerful but still hard for everyday contributors
  • What the TechDocs Editor plugin actually does
  • What the editing workflow looks like, step by step
  • How to add it to your Backstage instance
  • Where I would like help and feedback from the community

TechDocs solves publishing, but editing still has friction

TechDocs is Backstage's built-in docs-as-code solution. Engineers write documentation in Markdown alongside their code, and MkDocs plus TechDocs turn that into a documentation site inside Backstage.

The approach has real advantages. Docs live next to the service they describe. Markdown and Git history make changes auditable. The Docs tab gives every component a home for its documentation.

In practice, a few things still get in the way:

  • Simple edits feel heavy. Fixing a typo means opening the repo, creating a branch, opening a pull request, waiting on CI, and checking that it published correctly.
  • Non-developers get blocked. Product, design, support, and operations teammates often know exactly what a page should say, but are not comfortable with branches and pull requests.
  • Context switching breaks flow. You read the docs in Backstage, then have to jump to a separate tool just to fix one paragraph.
  • New pages are awkward to preview. Writing docs from scratch without a live preview means guessing how MkDocs will render the result.

TechDocs solves publishing. The TechDocs Editor plugin targets the remaining friction: the editing step itself.

What the TechDocs Editor plugin does

TechDocs Editor lets you treat documentation like any other Backstage-first experience. You stay inside the portal, make your changes, and send them for review through the same familiar UI you already use to browse the docs.

The project is split into five packages, following the standard Backstage plugin structure:

@estehsaan/backstage-plugin-techdocs-editor
@estehsaan/backstage-plugin-techdocs-editor-backend
@estehsaan/backstage-plugin-techdocs-editor-react
@estehsaan/backstage-plugin-techdocs-editor-node
@estehsaan/backstage-plugin-techdocs-editor-common

On the product side, it focuses on a few core capabilities:

  • WYSIWYG and Markdown modes. A Toast UI based rich text editor for people who prefer not to write raw Markdown, plus a source mode for engineers who want full control.
  • File tree with dirty indicators. Sidebar navigation of the docs folder, with a clear marker on any file that has unsaved changes.
  • New page creation. Add Markdown pages to the docs tree without touching Git directly.
  • GitHub and GitLab integration. The editor opens pull or merge requests against your existing repository, using the same review process your team already follows.
  • Submit Documentation Edits dialog. Shows the changed files, and lets you set the pull request title, description, and commit message, with support for draft pull requests.
  • Permission-aware UI. Backstage permissions (techdocs.editor.read and techdocs.editor.write) control who can edit and who can only read.
  • Entity integration. An /edit-docs content tab plus a standalone editor page, so it fits into your existing TechDocs reader as an addon.

The plugin does not replace Git or your code review process. It gives more people a practical way to reach that pull request step.

What the editing workflow looks like

  1. Open the docs. Navigate to a Backstage entity, open the Docs tab, then choose Edit Docs.
  2. Browse files in the sidebar. The file tree lists the Markdown files behind the TechDocs site, with dirty indicators on anything you have changed.
  3. Edit in WYSIWYG or Markdown. Use the rich text editor, or switch to raw Markdown when you need precise control.
  4. Preview the result, including pages that did not exist before you started.
  5. Submit changes as a pull or merge request. Review the changed files, set a title, description, and commit message, then choose a draft or regular pull request.
  6. Let normal review take over. Your existing review rules and CI pipeline run exactly as they would for a manual pull request.

For many teams, the real win is that non-developer contributors no longer need to learn Git to fix a sentence. They stay in Backstage, edit the text, and submit the change through a guided UI.

How it fits into the Backstage and TechDocs architecture

TechDocs itself prepares Markdown, generates HTML with MkDocs, publishes the output to storage, and renders it in Backstage's reader UI. The TechDocs Editor sits next to that pipeline rather than inside it.

  • On the frontend, it adds an editor view and an Edit Docs entry point to the TechDocs reader.
  • On the backend, it exposes REST endpoints that read and write documentation files in your version control system, and open pull requests with the changes.
  • On the node side, it provides an extension point for a custom version control provider, for teams not using GitHub or GitLab.

You keep your existing TechDocs configuration, whether that is a local or external builder, Docker or local MkDocs generation, or a local, S3, or GCS publisher. The editor adds an editing layer in front of whatever docs-as-code pipeline you already run.

Adding the TechDocs Editor to your Backstage instance

A full installation registers both a backend and a frontend plugin.

Backend. Register the TechDocs Editor backend alongside your existing plugin-techdocs-backend setup. This wires up the API routes that read and write docs in your version control system.

Frontend, new frontend system. Import techdocsEditorPlugin and add it to your application configuration.

Frontend, classic. Add TechDocsEditPageAddon inside TechDocsReaderPage, which adds an Edit Docs experience to the standard TechDocs reader view.

Backstage setups vary a lot between organizations, so the README on GitHub has the exact installation steps, plus notes on aligning React and @backstage/frontend-plugin-api versions to avoid invalid-hook errors when multiple React trees are loaded.

Why I built it

This started from a specific, frustrating pattern on a team I worked with. TechDocs was installed correctly. Markdown and MkDocs were set up in the repos. The Docs tab showed up for every component in Backstage.

Even so, small fixes sat unaddressed because they felt too heavy for what they were. Non-developers sent doc corrections through Slack messages or tickets instead of editing directly. People read the docs in Backstage, then jumped out to GitHub just to change one paragraph, and often did not bother.

TechDocs Editor is my attempt to close that gap and make documentation feel like a first-class part of the portal, something you can read and edit in the same place without the extra overhead.

Who this is for

This plugin is probably useful if:

  • Your TechDocs setup works, but updates are rare and feel painful.
  • Your platform team wants more documentation contribution from product, design, support, or operations.
  • Engineers keep context-switching between Backstage and GitHub for small doc edits.
  • You want documentation to feel genuinely integrated into your internal developer portal, not bolted on.

An advanced TechDocs setup, with an external builder, S3 storage, or a custom CI pipeline, does not remove this problem. A smoother editing experience still tends to make contribution more frequent.

What's next, and how you can help

TechDocs Editor currently supports GitHub and GitLab, WYSIWYG and Markdown modes, new page creation, and permission-aware editing. Next, I am exploring:

  • More version control providers through the node extension package
  • Deeper integration with TechDocs search and navigation
  • Better handling for large documentation sets and multi-repo docs
  • Editor conveniences like templates and reusable snippets

If you use Backstage and TechDocs, I would like to hear from you. Does this solve a real problem on your team? What would make an in-portal editor genuinely useful for the way you work? Are there approval, compliance, or audit workflows you need it to support?

Find the plugin in the Backstage plugin directory or on GitHub, and take a look at my other Backstage work on the projects page. If you try it, open an issue, a pull request, or just a discussion with feedback. Real-world input is what makes this better for the Backstage community.