2067852 - Migrate rst docs to markdown and host inside of bugzilla itself

Status: RESOLVED FIXED

(bugzilla.mozilla.org :: Documentation, enhancement)

Description

[David Lawrence [:dkl]]

Documentation: Markdown Docs and In-App Viewer

2026-08-29

The Bugzilla (BMO) documentation is authored in GitHub-flavored Markdown
under docs/en/md and served directly by Bugzilla itself at /docs. The
Markdown tree is the source of truth: edit the .md files and the changes
are live on the next deploy — there is no build step.

History

The docs were originally authored in Sphinx reStructuredText under
docs/en/rst and published externally (readthedocs, and before that
Sphinx/POD output built by docs/makedocs.pl). In August 2026 the RST tree
was converted 1:1 to Markdown (via a pandoc-based converter, since removed
with the RST tree), and the RST sources, the Sphinx/readthedocs build
machinery, makedocs.pl, and the docs_urlbase parameter were all removed.
docs/en/md/style.md describes the Markdown authoring conventions.

In-app documentation viewer

The Markdown docs can be browsed directly inside Bugzilla at /docs
(which redirects to /docs/en/md/index.md). This is a native Mojolicious
route (Bugzilla::App::Controller::Docs), not a page.cgi page.

• The /docs/en URL space mirrors docs/en on disk: pages are served at
  /docs/en/md/<path>.md and doc images at /docs/en/images/<name>.<ext>,
  so the relative links and image references inside the files work without
  rewriting. Directory URLs redirect to the section's index.md, and
  legacy Sphinx-style .html paths redirect to the Markdown page of the
  same name (old docs_urlbase bookmarks keep working).
• The docs_urlbase parameter was removed — the docs are no longer
  external. The docs_urlbase template variable remains and now
  returns <basepath>docs/en/md/, so the many templates that build help
  links did not need to change. REST error responses point their
  documentation field at the in-app API docs.
• Markdown is rendered server-side with the existing libcmark-gfm binding
  (Bugzilla::Markdown::GFM::Parser) in unsafe mode (the docs are trusted
  repository content and contain raw HTML tables and <a id> anchors);
  the tagfilter extension still neutralizes script-capable tags. The
  unsafe render option bit was added to Bugzilla::Markdown::GFM.
• The controller post-processes the HTML with Mojo::DOM to add GitHub-style
  heading ids (so #fragment links resolve) and to turn > [!NOTE]-style
  GFM alerts into styled callout boxes.
• Pages render through template/en/default/pages/doc_viewer.html.tmpl,
  which wraps the content in the standard Bugzilla header and footer;
  styling lives in skins/standard/docs.css and follows the theme's CSS
  variables (light and dark mode).
• Unknown paths and traversal attempts return a styled 404 via the
  docs_page_not_found user error.
• Tests: t/mojo-docs.t.

Comment 1

[BMO Github Automation]

Attachment: [mozilla/bmo] Bug 2067852 - Migrate rst docs to markdown and host inside of bugzilla itself (#2731)

Comment 4

[BMO Github Automation]

Authored by https://github.com/dklawren
https://github.com/mozilla/bmo/commit/c6c74b853ca9090bc3ceb329d41018f5ab93353f
[master] Bug 2067852 - Migrate rst docs to markdown and host inside of bugzilla itself

(via GitHub webhook, authenticated as shared-secret)