Docusaurus includes several powerful features that allow you to build more sophisticated documentation sites. This page covers the core advanced capabilities: internationalization (i18n), versioning, and search integration. These features significantly enhance documentation usability while requiring minimal configuration.
For information about the theming system, see Theming.
Internationalization enables your documentation to serve a global audience by supporting multiple languages. Docusaurus provides built-in i18n support with locale detection, translation management, and a dedicated UI for language switching.
The i18n system orchestrates translations across the core, plugins, and theme components. The loadI18n function in the server package serves as the entry point for resolving the site's locale configuration.
Sources:
To enable i18n, you configure the i18n object in your site configuration. Docusaurus supports a decoupled translation workflow, meaning you can use any SaaS like Crowdin or manual translation files as long as they are placed in the expected i18n/[locale] directory structure. The loadI18n function is responsible for loading the i18n configuration, inferring default locale settings using getDefaultLocaleConfig, and determining the baseUrl and url for each locale packages/docusaurus/src/server/i18n.ts131-217
The extractSiteSourceCodeTranslations function uses Babel to scan source files (defined by SRC_DIR_NAME) and plugin paths to find translatable strings packages/docusaurus/src/server/translations/translationsExtractor.ts58-99
For details, see Internationalization.
Versioning enables you to maintain documentation for multiple versions of your project simultaneously. This is particularly valuable for software libraries where users might be using different releases.
The versioning system snapshots content and sidebars. It relies on a specific directory structure and the versions.json registry.
Sources:
The versioning system is managed primarily through the docusaurus-plugin-content-docs package. The loadSidebars function handles the complexity of loading version-specific sidebar files or falling back to DefaultSidebars if no specific configuration exists packages/docusaurus-plugin-content-docs/src/sidebars/index.ts106-129
When building the site, Docusaurus can build multiple locales and versions sequentially. The build command determines the locales to build via getLocaleList and then executes buildLocale for each packages/docusaurus/src/commands/build/build.ts41-53
For details, see Versioning.
Docusaurus provides robust search capabilities, primarily through integration with Algolia DocSearch, but it also supports extensible search headers and local search plugins.
| Feature | Description | Code Reference |
|---|---|---|
| Algolia DocSearch | Official integration for high-performance hosted search. | SearchBar component |
| Contextual Search | Filters results based on the current active version and language. | useBrokenLinks packages/docusaurus/src/client/exports/Link.tsx45 |
| Ask AI | Experimental RAG-based search features. | themeConfig.algolia.ai |
| OpenSearch | Generates an OpenSearch description for browser search bar integration. | opensearch.xml template |
Search is typically configured within themeConfig.algolia. It requires an appId, apiKey, and indexName. The system uses facet filters to ensure that a user searching while on the "v2" documentation only sees results for "v2" and the current language. Components like Link interact with the search and routing system by prefetching internal links to improve perceived performance packages/docusaurus/src/client/exports/Link.tsx105-125
For details, see Search Integration.
Docusaurus provides granular control over how documents are included in the build and displayed to users.
The system tracks content integrity and freshness through several mechanisms:
useBrokenLinks hook is used by components like Link and APITable to collect and validate internal anchors and URLs packages/docusaurus/src/client/exports/Link.tsx168-175 website/src/components/APITable/index.tsx58pathname:// protocol to bypass internal SPA routing for specific links while still appending the correct baseUrl packages/docusaurus/src/client/exports/Link.tsx70-73For technical documentation requiring diagrams, the @docusaurus/theme-mermaid package provides a useMermaidRenderResult hook that integrates the Mermaid rendering engine into the Docusaurus lifecycle, supporting theme-aware (light/dark mode) diagram rendering packages/docusaurus-theme-mermaid/src/client/index.ts81-113
Sources:
Refresh this wiki
This wiki was recently refreshed. Please wait 2 days to refresh again.