Docusaurus DocsSitemap with Two-Column Landing Page

Add a two-column landing page layout: left sticky sidebar (title, tagline, logo, links) + right column with expand/collapse DocsSitemap.

The right column renders each sidebar as a boxed accordion section (<details>/<summary>) with a bordered card style, animated chevron, and background header bar. Each section is open by default and can be collapsed.

Prerequisites

• gray-matter and clsx npm dependencies
• Docusaurus site with sidebars.ts (or .js)

Step 1: Detect Docusaurus Root

Find the directory containing docusaurus.config.ts (or docusaurus.config.js). This is the Docusaurus root directory, referred to as {DOCUSAURUS_ROOT} in the steps below. All file paths in this skill are relative to this root.

Step 2: Create doc-titles generation script

Same as /docusaurus-doc-title skill. Create {DOCUSAURUS_ROOT}/scripts/generate-doc-titles.js that scans all markdown files and outputs src/data/doc-titles.json.

Step 3: Create the DocsSitemap component

Read assets/DocsSitemap-index.tsx from this skill directory and copy it to:

{DOCUSAURUS_ROOT}/src/components/DocsSitemap/index.tsx

Read assets/DocsSitemap-styles.module.css from this skill directory and copy it to:

{DOCUSAURUS_ROOT}/src/components/DocsSitemap/styles.module.css

Create the directory structure if it doesn't exist.

Key features of the component:

• generateLabel() converts sidebar IDs to display names (e.g., inboxSidebar -> INBOX, apiSidebar -> API)
• Each sidebar renders as a bordered, rounded card with a background header bar
• Animated chevron rotates 90deg on open
• Handles autogenerated sidebars using category-nav.json (preferred) or doc-titles.json fallback
• Uses Fragment with keys (not <>) to avoid React key warnings
• Each section is open by default

CI compatibility: generate data before quality checks

The auto-generated JSON files (doc-titles.json, category-nav.json) are gitignored, so they don't exist at checkout. If CI runs typecheck or lint before build, these checks will fail because import statements reference missing files. The fix: run the generate scripts before quality checks in CI.

Example CI action step (before typecheck/lint):

- name: Generate data files
  run: |
    pnpm run generate-doc-titles
    pnpm run generate-category-nav
  shell: bash
  working-directory: ${{ inputs.working-directory }}

Do NOT use require() instead of import — ESLint @typescript-eslint/no-require-imports forbids it.

URL generation: strip /index suffix

Docusaurus routes index docs (e.g., overview/index) to the parent directory URL (/docs/overview), not /docs/overview/index. All link generation must use a helper to strip the /index suffix:

function docIdToUrl(docsBaseUrl: string, docId: string): string {
  const path = docId.replace(/\/index$/, '');
  return `${docsBaseUrl}${path}`;
}

Use docIdToUrl(docsBaseUrl, docId) instead of `${docsBaseUrl}${docId}` for all href attributes.

Resolving autogenerated sidebars

If the project has a category-nav.json (from the /docusaurus-category-nav skill), import it and use it for autogenerated sidebar resolution. For each autogenerated item with a dirName, look up categoryNav[dirName] and render its pages and subcategories with proper nesting (subcategory titles as links if they have index pages, with nested page lists).

Fallback (when category-nav.json is not available): filter doc-titles.json entries by dirName/ prefix, excluding dirName/index, and render as flat links.

Step 4: Copy the logo SVG

Copy the bundled logo from this skill's assets to the target project:

{SKILL_DIR}/assets/logo.svg → {DOCUSAURUS_ROOT}/static/img/logo.svg

If static/img/logo.svg already exists in the target project, keep the existing one (it may be project-specific). Only copy if no logo exists.

Step 5: Create the two-column landing page

Read assets/index.tsx from this skill directory and copy it to:

{DOCUSAURUS_ROOT}/src/pages/index.tsx

Read assets/index.module.css from this skill directory and copy it to:

{DOCUSAURUS_ROOT}/src/pages/index.module.css

If an existing src/pages/index.js redirect file exists, remove it (it conflicts with index.tsx).

After copying, customize the links section in index.tsx for the project (title, URLs).

Step 6: Update config

In docusaurus.config.ts (or .js):

• Ensure routeBasePath is /docs (not /)
• Update search plugin's docsRouteBasePath to /docs if applicable

Delete docs/intro.md if it has slug: /.

Step 7: Wire up scripts and gitignore

In package.json:

"start": "pnpm run generate && docusaurus start",
"build": "pnpm run generate && docusaurus build",
"generate": "pnpm run generate:doc-titles",
"generate:doc-titles": "node scripts/generate-doc-titles.js"

Add to .gitignore:

src/data/doc-titles.json

Install gray-matter if not already present.

Step 8: Verify

Run pnpm run generate then pnpm run build. Verify:

• Landing page shows two-column layout with logo on the left
• Logo appears inside an orange rounded-corner container, white-inverted
• Right column shows boxed accordion sections for each sidebar
• Each accordion has a bordered card with rounded corners, background header, and animated chevron
• Responsive: single column on mobile (< 996px)
• Left column is sticky on scroll

Assets

• assets/logo.svg - Default logo SVG. Target: {DOCUSAURUS_ROOT}/static/img/logo.svg
• assets/index.tsx - Landing page component with two-column layout. Target: {DOCUSAURUS_ROOT}/src/pages/index.tsx
• assets/index.module.css - Landing page CSS module. Target: {DOCUSAURUS_ROOT}/src/pages/index.module.css
• assets/DocsSitemap-index.tsx - DocsSitemap component with boxed accordion style. Target: {DOCUSAURUS_ROOT}/src/components/DocsSitemap/index.tsx
• assets/DocsSitemap-styles.module.css - DocsSitemap CSS module with card/chevron styles. Target: {DOCUSAURUS_ROOT}/src/components/DocsSitemap/styles.module.css