4 posts tagged with "Docusaurus"

Docusaurus gives you a reasonably accessible starting point, and most sites then lose some of it. The losses rarely come from the framework itself. They come from custom colors, custom components, a sticky banner someone added for a launch, and years of Markdown written without anyone checking alt text or heading order. This post lists the WCAG 2.2 AA issues we look for first on a Docusaurus site, where each one usually comes from, and how to test for them.

Most comparisons of Docusaurus, MkDocs and GitBook are written for developer documentation: API references, SDK guides, versioned technical manuals. A customer help center has different requirements. The people writing it are often support agents rather than engineers, the readers arrive from search with a problem, and the site has to hand off to a human when the article is not enough. This comparison is written for that case.

A Zendesk help center that has been live for a few years usually ranks for a long tail of how-to queries nobody on the team tracks. Moving it to Docusaurus keeps that traffic only if every old article URL answers with a permanent redirect to its new home on the day you switch. How you do that depends on one question most teams have not asked yet: who controls the domain the help center is served from?

Moving a Confluence space to Docusaurus is mostly a conversion problem with three traps in it: macros that have no Markdown equivalent, a page tree that does not map cleanly to folders, and URLs that carry page IDs your redirects have to honor. This guide covers each step in the order we do it, with the commands and config we actually use.