Customization and Deployment

Level: Beginner

ℹ️ What You'll Learn

• Editing docusaurus.config.ts for site config
• Custom logo, colors, and theme
• Dark mode toggle and configuration
• Navbar links and footer content
• Search plugin configuration (Algolia)
• Building production output
• Deploying to GitHub Pages
• Custom domain setup and SSL

Why This Matters

Docusaurus out-of-box looks good. But you'll customize colors, logo, and branding to match your company or project (like NexCoding's styling).

Site Configuration

Edit docusaurus.config.ts:

const config: Config = {
  title: 'NexCoding',
  tagline: 'Learn .NET Backend Development',
  url: 'https://nexcoding.in',
  baseUrl: '/',
  organizationName: 'TeamSahasra',
  projectName: 'nexcoding',

  themeConfig: {
    colorMode: {
      defaultMode: 'light',
      disableSwitch: false,
    },
    navbar: {
      title: 'NexCoding',
      logo: {
        alt: 'NexCoding Logo',
        src: 'img/logo.svg',
      },
    },
  },
};

url = production URL. baseUrl = deployment path (/ for root, /docs/ for subfolder).

Navbar Customization

navbar: {
  title: 'NexCoding',
  logo: { src: 'img/logo.svg' },
  items: [
    {
      type: 'docSidebar',
      sidebarId: 'docsSidebar',
      label: 'Tutorials',
      position: 'left',
    },
    {
      href: 'https://github.com/TeamSahasra/nexcoding',
      label: 'GitHub',
      position: 'right',
    },
  ],
}

items = navbar links. position: 'left' or 'right' = placement. href = external link. type: 'docSidebar' = link to docs.

Colors and Theming

Edit docusaurus.config.ts:

themeConfig: {
  colorMode: {
    defaultMode: 'light',
    disableSwitch: false,
    respectPrefersColorScheme: true,
  },
  colors: {
    primaryColor: '#0066cc',        // Primary blue
    primaryColorDark: '#0052a3',    // Darker blue
    accentColor: '#ff6b6b',         // Red accent
  },
}

Or edit CSS directly in src/css/custom.css:

:root {
  --ifm-color-primary: #0066cc;
  --ifm-color-primary-dark: #0052a3;
  --ifm-color-primary-light: #3399ff;
  --ifm-font-family-base: 'Arial, sans-serif';
}

[data-theme='dark'] {
  --ifm-color-primary: #5eb3ff;
  --ifm-color-primary-dark: #3399ff;
}

Footer Customization

footer: {
  style: 'dark',
  links: [
    {
      title: 'Docs',
      items: [
        { label: 'C# Tutorial', to: '/docs/csharp/' },
        { label: '.NET Guide', to: '/docs/dotnet/' },
      ],
    },
    {
      title: 'Community',
      items: [
        { label: 'GitHub', href: 'https://github.com/TeamSahasra' },
        { label: 'Email', href: 'mailto:info@nexcoding.in' },
      ],
    },
  ],
  copyright: `Copyright © ${new Date().getFullYear()} NexCoding`,
}

Search Integration

Docusaurus includes Algolia search (free tier available):

algolia: {
  appId: 'YOUR_APP_ID',
  apiKey: 'YOUR_SEARCH_KEY',
  indexName: 'nexcoding',
  contextualSearch: true,
}

Algolia indexes site automatically. No code needed, just API keys.

Sidebar Configuration

Edit sidebars.ts:

const sidebars: SidebarsConfig = {
  docsSidebar: [
    {
      type: 'category',
      label: 'Getting Started',
      items: ['intro', 'setup'],
    },
    {
      type: 'category',
      label: 'API Reference',
      items: ['api/students', 'api/exams', 'api/fees'],
    },
  ],
};

category = folder in sidebar. label = display name. items = document paths (without .mdx).

Static Assets

Add images, PDFs, downloads to static/:

static/
├── img/
│   ├── logo.svg
│   ├── logo.png
│   └── screenshots/
├── files/
│   └── sample-data.csv
└── downloads/
    └── api-postman.json

Reference in content:

![Logo](/img/logo.svg)
[Download CSV](/files/sample-data.csv)
<a href="/downloads/api-postman.json">Postman Collection</a>

Deployment

GitHub Pages

Push to GitHub, Pages auto-deploys:

# Install GitHub Pages plugin
npm install --save-dev @docusaurus/core

# Add to package.json
"homepage": "https://teamsahasra.github.io/nexcoding",
"deploy": "docusaurus deploy"

# Deploy
npm run deploy

Vercel

Connect GitHub repo to Vercel. Auto-deploys on push.

No configuration needed. Vercel auto-detects Docusaurus.

Netlify

# netlify.toml
[build]
  command = "npm run build"
  publish = "build"

[context.production.environment]
  NODE_VERSION = "18"

Push. Netlify builds and deploys.

Custom Domain

1. Register domain (GoDaddy, Namecheap, Route53)
2. Add DNS records pointing to hosting provider
3. Configure CNAME in hosting (GitHub Pages, Vercel, Netlify)
4. Set domain in Docusaurus config if needed

Typically automatic with Vercel/Netlify.

Environment Variables

Create .env.local:

ALGOLIA_APP_ID=your_app_id
ALGOLIA_API_KEY=your_api_key
GOOGLE_ANALYTICS_ID=G-XXXX

Reference in config:

const apiKey = process.env.ALGOLIA_API_KEY;

Don't commit .env.local to git.

Build and Test

# Build production site
npm run build

# Test locally
npm run serve

# Visit http://localhost:3000

SMS Documentation Site Example

NexCoding structure:

docs/
├── csharp/          → /docs/csharp/
├── dotnet/          → /docs/dotnet/
├── aspnet-core/     → /docs/aspnet-core/
└── frontend/
    ├── html/        → /docs/frontend/html/
    ├── css/         → /docs/frontend/css/
    ├── javascript/  → /docs/frontend/javascript/
    └── typescript/  → /docs/frontend/typescript/

Sidebar shows all tracks. User navigates between them.

Colors: Blue (#0066cc) for primary, SMS examples throughout.

Key Takeaways

• docusaurus.config.ts = main configuration
• Customize navbar, footer, colors, logo
• sidebars.ts = sidebar structure
• Static assets in static/ folder
• Deploy to GitHub Pages, Vercel, or Netlify
• Algolia search for site-wide search
• .env.local for secrets

💡 Backend Developer Tip

Docusaurus handles all frontend complexity. You focus on documentation content. Branding changes = one config file. This is why NexCoding uses Docusaurus for tutorials and API docs.

⚠️ Common Issues

1. baseUrl mismatch — Config says /docs/ but deploying to root
2. Image paths broken — Use /img/ not img/ for static assets
3. Sidebar links wrong — Document paths need exact match
4. Build fails — Check MDX syntax (unclosed JSX tags)

🤖Use AI to Learn Faster

Use ChatGPT, Claude, or Copilot to go deeper on Docusaurus Customization. Try these prompts:

• "How do you change the site colors?"
• "What's the difference between Vercel and GitHub Pages?"
• "How do you add a custom domain?"
• "Quiz me on Docusaurus configuration"

💡 Tip: After reading this article, paste your own code into AI and ask "What could go wrong here and why?" — fastest way to find edge cases and deepen understanding.