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 (partial - uses Astro layouts)
  • Custom doc item component (partial - uses Astro layouts)
  • Remark plugins support (via Astro)
  • Rehype plugins support (via Astro)

Frontmatter Support

  • title - Document title (used in sidebar, not yet in page <title> tag)
  • 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_class_name - Custom CSS class for sidebar item
  • sidebar_custom_props - 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

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
  • Automatic heading anchors
  • Tabs component
  • Details/collapsible sections 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
  • autogenerated - Auto-generate sidebar from file structure
  • ref type - Reference to another sidebar item
  • Category index pages (folder with index.md)
  • Category metadata via _category_.json or _category_.yml
  • Custom category icons
  • Multiple sidebars (via navigation config)
  • Sidebar hiding per-page
  • 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
  • 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 (partial - uses Astro)
  • Custom blog post component (partial - uses Astro)
  • 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
  • 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
  • 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
  • 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
  • hide_table_of_contents - Hide 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
  • Component swizzling/overrides

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 - Essential for documentation
  2. Tags for docs and blog - Important for content organization
  3. RSS/Atom feeds - Expected feature for blogs
  4. Reading time - Nice UX for blog posts
  5. Draft mode - Essential for content workflow
  6. Previous/next navigation - Expected in docs

Medium Priority (Enhanced Features)

  1. Search integration - Critical for larger docs
  2. “Edit this page” links - ✅ Implemented
  3. Last updated timestamps - ✅ Implemented
  4. Code block enhancements - Line numbers, highlighting, titles
  5. Tabs component - Common docs pattern
  6. Archive page for blog - Better blog navigation

Lower Priority (Advanced Features)

  1. Documentation versioning - Complex feature for mature projects
  2. Multi-instance docs/blogs - ✅ Implemented for docs
  3. Custom sidebar items (HTML, links) - Power user feature
  4. Author pages - Nice to have for multi-author blogs
  5. Social card images - Automated OG images

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: November 2025