Skip to content
shipyard
  • Docusaurus Feature Parity Roadmap
On this page

Docusaurus Feature Parity Roadmap

This document tracks shipyard’s progress towards supporting features from Docusaurus’s three main content plugins. Features are marked as:

  • ✅ Supported - Already implemented in shipyard
  • 🔄 Partial - Partially implemented or available through Astro
  • ⏳ Planned - On the roadmap for future implementation
  • ❌ Not Applicable - Not relevant for shipyard (usually because Astro handles it natively)

Documentation Plugin (@docusaurus/plugin-content-docs)

Core Functionality

  • Render documentation pages from Markdown/MDX files
  • Generate documentation routes automatically
  • Documentation sidebar navigation
  • Multiple documentation instances (multi-instance docs)
  • Documentation versioning

Configuration Options

  • Custom path to docs content directory
  • Custom URL route base path (routeBasePath)
  • Sidebar configuration path
  • Collapsible sidebar categories (sidebarCollapsible)
  • Sidebar categories start collapsed (sidebarCollapsed)
  • “Edit this page” links (editUrl)
  • Show last update timestamp (showLastUpdateTime)
  • Show last update author (showLastUpdateAuthor)
  • Breadcrumb navigation (breadcrumbs)
  • Include/exclude glob patterns
  • Custom doc layout component (via Astro layouts)
  • Custom doc item component (via Astro layouts)
  • Remark plugins support (via Astro)
  • Rehype plugins support (via Astro)

Frontmatter Support

  • title - Document title (used in sidebar and page <title> tag)
  • title_meta - SEO title override for <title> and meta tags
  • description - Meta description for SEO (schema exists, not yet rendered in docs)
  • slug - Custom URL slug (routes are generated from file paths)
  • sidebar.label - Custom sidebar label
  • sidebar.position - Position in sidebar
  • sidebar.className - Custom CSS class for sidebar item
  • sidebar.customProps - Custom properties for sidebar item
  • id - Document ID for referencing
  • hide_title - Hide the title heading
  • hide_table_of_contents - Hide TOC sidebar
  • toc_min_heading_level - Minimum heading level for TOC
  • toc_max_heading_level - Maximum heading level for TOC
  • pagination_next - Custom next page
  • pagination_prev - Custom previous page
  • pagination_label - Custom pagination label
  • keywords - Keywords for SEO
  • image - Social media preview image
  • tags - Document tags
  • draft - Mark as draft (excluded from production)
  • last_update - Manual last update info
  • unlisted - Hide from production but keep accessible
  • displayed_sidebar - Force a specific sidebar (N/A - shipyard uses auto-generated sidebars per docs instance)
  • sidebar_key - Unique sidebar item key for i18n (N/A - shipyard uses file paths as unique identifiers)
  • parse_number_prefixes - Parse number prefixes from filenames (N/A - use sidebar.position frontmatter instead)

MDX & Markdown Features

  • Standard Markdown support
  • MDX support (via Astro MDX integration)
  • Import React/Astro components in MDX
  • Admonitions/callouts (:::note, :::tip, :::warning, etc.)
  • Code blocks with syntax highlighting (via Astro/Shiki)
  • Line highlighting in code blocks
  • Line numbering in code blocks
  • Code block titles/filenames
  • Live code editors
  • npm2yarn code block support (via remarkNpm2Yarn plugin)
  • Automatic heading anchors
  • Tabs component
  • Details/collapsible sections component
  • Math equations (KaTeX) - Via Astro remark/rehype plugins (remark-math + rehype-katex)
  • Mermaid diagrams - Via Astro integrations (astro-mermaid or custom Mermaid component)
  • doc type - Link to a specific document
  • category type - Collapsible category with nested items
  • link type - External or internal link in sidebar
  • html type - Custom HTML content in sidebar (via labelHtml and defaultStyle)
  • autogenerated - Auto-generate sidebar from file structure
  • ref type - Reference to another sidebar item (N/A - shipyard uses explicit sidebar config)
  • Category index pages (folder with index.md)
  • Category metadata via index.md frontmatter (sidebar.label, sidebar.position, collapsed, collapsible, sidebar.className, sidebar.customProps)
  • Custom category icons (via sidebar.customProps in index.md frontmatter)
  • Multiple sidebars (via navigation config)
  • Sidebar hiding per-page (hide_sidebar)
  • Active page highlighting

Versioning

  • Create versioned documentation snapshots
  • Version dropdown selector
  • Version badges
  • Unmaintained version banners
  • Custom version labels
  • Version-specific sidebars
  • Version-specific edit URLs

SEO Features

  • Meta description from frontmatter
  • OpenGraph tags (og:title, og:description)
  • Custom canonical URLs
  • Keywords support
  • Custom meta tags via frontmatter
  • Social card images (og:image, twitter:image)
  • Sitemap generation (via Astro sitemap integration)

Blog Plugin (@docusaurus/plugin-content-blog)

Core Functionality

  • Blog post management from Markdown/MDX files
  • Blog listing page with posts
  • Individual blog post pages
  • Author management
  • Tag system for blog posts
  • RSS/Atom feed generation
  • Archive page

Configuration Options

  • Custom path to blog content directory
  • Custom URL route base path
  • Blog title configuration
  • Blog description configuration
  • Blog sidebar title
  • Blog sidebar post count
  • Posts per page (pagination)
  • Custom blog list component (via Astro layouts)
  • Custom blog post component (via Astro layouts)
  • Authors map file support
  • Show reading time
  • Custom reading time calculation
  • “Edit this page” links
  • Truncation marker (<!--truncate-->)
  • RSS/Atom feed options
  • Sort posts by date
  • Remark plugins (via Astro)
  • Rehype plugins (via Astro)

Frontmatter Support

  • title - Post title
  • title_meta - SEO title override for <title> and meta tags
  • description - Post description/excerpt
  • date - Publication date
  • authors - Post author(s)
  • tags - Post tags
  • image - Social card image
  • keywords - SEO keywords
  • hide_table_of_contents - Hide TOC
  • sidebar.label - Custom label for blog sidebar
  • toc_min_heading_level - Min TOC level
  • toc_max_heading_level - Max TOC level
  • draft - Mark as draft
  • unlisted - Unlisted post
  • last_update - Last update info
  • slug - Custom URL slug

Author Features

  • Author name
  • Author role/title
  • Author URL/website
  • Author avatar image
  • Author email
  • Generated author pages
  • Multiple authors per post
  • Inline author definition in frontmatter

Tag Features

  • Tag listing page
  • Individual tag pages
  • Tag counts
  • Tags definition file
  • Tag descriptions
  • Tag permalinks

Feed Features

  • RSS 2.0 feed
  • Atom feed
  • JSON feed
  • Custom feed configuration
  • Feed title/description
  • Feed item limits
  • Blog sidebar with posts
  • Pagination controls
  • Previous/next post navigation
  • Archive page with chronological listing
  • Tag-based navigation

Other Blog Features

  • Reading time estimation
  • Multi-instance blogs (via routeBasePath configuration)
  • i18n support for blog posts
  • Draft posts (dev-only)

Pages Plugin (@docusaurus/plugin-content-pages)

Core Functionality

  • Create standalone pages (via Astro pages)
  • Support for Astro/React and Markdown/MDX pages
  • Route generation from file structure
  • Landing pages and custom pages

Configuration Options

  • Custom path to pages directory (Astro native)
  • Base URL route (Astro native)
  • Include/exclude patterns (Astro native)
  • Remark plugins (via Astro)
  • Rehype plugins (via Astro)

Page Types

Component Pages (Astro/React)

  • Full component pages (.astro, .tsx)
  • Access to shipyard components and layouts
  • Custom layouts
  • Dynamic content
  • Client-side interactivity (via Astro)

Markdown/MDX Pages

  • Markdown pages with frontmatter
  • MDX support (via Astro)
  • Import components in MDX
  • Use shipyard components

Frontmatter Support (MDX Pages)

  • title - Page title
  • description - Meta description
  • keywords - SEO keywords
  • image - Social preview image
  • wrapperClassName - Custom wrapper class
  • canonical_url - Custom canonical URL
  • custom_meta_tags - Custom meta tags
  • hide_table_of_contents - Hide TOC (N/A - standalone pages don’t have TOC)
  • draft - Mark as draft
  • unlisted - Unlisted page

Routing Features

  • File-based routing (Astro native)
  • Nested routes via folder structure
  • Index pages
  • Dynamic routes (Astro native)

Cross-Plugin Features

Shared Capabilities

  • MDX support with components (via Astro)
  • Remark/Rehype plugin extensibility (via Astro)
  • Admonitions/callouts in all content types
  • Draft mode for all content types
  • Unlisted content for all types
  • i18n/internationalization support
  • Asset handling (images, files)
  • Theme components (via Tailwind/DaisyUI)
  • SEO meta tags

Navigation & UI

  • Global navigation bar
  • Mobile-responsive hamburger menu
  • Sidebar navigation (docs)
  • Breadcrumbs
  • Table of contents
  • Search integration
  • Announcement banner
  • Theme/dark mode toggle

Theming & Styling

  • Tailwind CSS integration
  • DaisyUI component library
  • Typography (prose) styling
  • Responsive design
  • Custom CSS classes via frontmatter
  • Theme configuration file (via Astro config and shipyard config)
  • Component swizzling/overrides (via Astro component imports and layouts)

Features Not Applicable to shipyard

The following Docusaurus features are not applicable because Astro handles them natively or they don’t fit shipyard’s architecture:

FeatureReason
Content collection loadersAstro Content Collections handles this
Static site generationAstro core feature
Plugin lifecycle hooksAstro integrations handle this
Webpack/bundler configAstro uses Vite natively
React hydration strategiesAstro Islands architecture handles this
Global data via hooksAstro’s data fetching handles this
Build-time data loadingAstro’s getStaticPaths handles this

Priority Roadmap

High Priority (Core Parity)

  1. Admonitions/Callouts - ✅ Implemented
  2. Tags for docs and blog - ✅ Implemented
  3. RSS/Atom feeds - ✅ Implemented
  4. Reading time - ✅ Implemented
  5. Draft mode - ✅ Implemented
  6. Previous/next navigation - ✅ Implemented

Medium Priority (Enhanced Features)

  1. Search integration - ✅ Implemented (via Pagefind)
  2. “Edit this page” links - ✅ Implemented
  3. Last updated timestamps - ✅ Implemented
  4. Code block enhancements - ✅ Implemented (line numbers, highlighting, titles)
  5. Tabs component - ✅ Implemented
  6. Archive page for blog - ✅ Implemented
  7. Announcement banner - ✅ Implemented

Lower Priority (Advanced Features)

  1. Documentation versioning - ✅ Implemented (multi-version docs with version selector)
  2. Multi-instance docs/blogs - ✅ Implemented (routeBasePath for both docs and blogs)
  3. Sidebar link type - ✅ Implemented (external/internal links in sidebar)
  4. Author pages - ✅ Implemented (generated author pages for blog)
  5. hide_table_of_contents - ✅ Implemented (per-page TOC hiding)
  6. Social card images - ✅ Implemented (og:image, twitter:image support)
  7. Dark mode toggle - ✅ Implemented (ThemeToggle component)
  8. hide_title - ✅ Implemented (hide H1 heading via frontmatter)
  9. TOC level filtering - ✅ Implemented (toc_min/max_heading_level)
  10. Keywords SEO - ✅ Implemented (keywords meta tag)
  11. pagination_label - ✅ Implemented (custom pagination labels)
  12. last_update - ✅ Implemented (manual last update override)
  13. hide_sidebar - ✅ Implemented (per-page sidebar hiding)
  14. Blog TOC levels - ✅ Implemented (toc_min/max_heading_level for blog)
  15. Custom URL slug - ✅ Implemented (slug frontmatter for docs)
  16. Canonical URLs - ✅ Implemented (canonical_url frontmatter)
  17. Tag descriptions - ✅ Implemented (tags.yml with labels and descriptions)
  18. Sidebar custom props - ✅ Implemented (badges via sidebar.customProps)
  19. Custom meta tags - ✅ Implemented (custom_meta_tags frontmatter)
  20. Document ID - ✅ Implemented (id frontmatter for pagination references)
  21. Pages frontmatter - ✅ Implemented (keywords, image, wrapperClassName, canonical_url, custom_meta_tags)
  22. Custom sidebar HTML - ✅ Implemented (labelHtml and defaultStyle properties)
  23. Multi-instance blogs - ✅ Implemented (routeBasePath configuration)
  24. npm2yarn code blocks - ✅ Implemented (remarkNpm2Yarn plugin)

Contributing

We welcome contributions to help reach feature parity with Docusaurus! If you’d like to implement any of the unchecked features above:

  1. Check the GitHub Issues for existing discussions
  2. Open a new issue to discuss your proposed implementation
  3. Submit a pull request

Last updated: January 2026