Skip to main content

Setting Up My Documentation Site with Docusaurus

· 4 min read
learnwy
Documentation Maintainer

In this post, I'll walk through how I set up this documentation site using Docusaurus, a modern static website generator. I'll cover the installation process, configuration changes, and customizations I made along the way.

Initial Setup​

I started by creating a new Docusaurus project using the following commands:

npx create-docusaurus@latest l-docs classic --typescript
cd l-docs
pnpm install

Project Structure​

The project follows Docusaurus's recommended structure:

  • /docs: Contains all documentation files
    • /notes: General notes and concepts
    • /langs: Programming language documentation
    • /frameworks: Framework-specific documentation
  • /blog: Blog posts and related configuration
  • /src: Custom components and pages
  • /static: Static assets like images

Configuration​

I made several customizations to docusaurus.config.ts:

Site Metadata​

const config: Config = {
  title: 'learnwy',
  tagline: 'A comprehensive collection of learning notes and documentation',
  favicon: 'img/favicon.svg',
  url: 'https://docs.learnwy.com',
  baseUrl: '/',
  organizationName: 'learnwy',
  projectName: 'l-docs',
};

Theme Configuration​

theme: {
  colorMode: {
    defaultMode: 'light',
    disableSwitch: false,
    respectPrefersColorScheme: true,
  },
  navbar: {
    title: 'learnwy',
    logo: {
      alt: 'learnwy Logo',
      src: 'img/logo.svg',
    },
    items: [
      {to: '/docs/notes/getting-started', label: 'Notes', position: 'left'},
      {to: '/docs/langs/getting-started', label: 'Languages', position: 'left'},
      {to: '/docs/frameworks/getting-started', label: 'Frameworks', position: 'left'},
      {to: '/blog', label: 'Blog', position: 'left'},
      {
        href: 'https://github.com/learnwy/l-docs',
        label: 'GitHub',
        position: 'right',
      },
    ],
  },
  footer: {
    style: 'dark',
    links: [
      {
        title: 'Docs',
        items: [
          {label: 'Notes', to: '/docs/notes/getting-started'},
          {label: 'Languages', to: '/docs/langs/getting-started'},
          {label: 'Frameworks', to: '/docs/frameworks/getting-started'},
        ],
      },
      {
        title: 'Community',
        items: [
          {label: 'GitHub', href: 'https://github.com/learnwy/l-docs'},
        ],
      },
    ],
    copyright: `Copyright © ${new Date().getFullYear()} learnwy. Built with Docusaurus.`,
  },
};

Plugins and Presets​

presets: [
  [
    'classic',
    {
      docs: {
        sidebarPath: './sidebars.ts',
        editUrl: 'https://github.com/learnwy/l-docs/tree/main/',
      },
      blog: {
        showReadingTime: true,
        editUrl: 'https://github.com/learnwy/l-docs/tree/main/',
      },
      theme: {
        customCss: './src/css/custom.css',
      },
    } as Options,
  ],
];

Custom Styling​

I added custom styles in src/css/custom.css to match our branding:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-color-primary-dark: #29784c;
  --ifm-color-primary-darker: #277148;
  --ifm-color-primary-darkest: #205d3b;
  --ifm-color-primary-light: #33925d;
  --ifm-color-primary-lighter: #359962;
  --ifm-color-primary-lightest: #3cad6e;
  --ifm-code-font-size: 95%;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.1);
}

[data-theme='dark'] {
  --ifm-color-primary: #25c2a0;
  --ifm-color-primary-dark: #21af90;
  --ifm-color-primary-darker: #1fa588;
  --ifm-color-primary-darkest: #1a8870;
  --ifm-color-primary-light: #29d5b0;
  --ifm-color-primary-lighter: #32d8b4;
  --ifm-color-primary-lightest: #4fddbf;
  --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
}

Deployment​

I set up GitHub Actions for automatic deployment to GitHub Pages:

name: Deploy to GitHub Pages

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: 18
          cache: pnpm
      - name: Install dependencies
        run: pnpm install
      - name: Build website
        run: pnpm build
      - name: Deploy to GitHub Pages
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./build

With these configurations in place, we have a fully functional documentation site that's easy to maintain and extend. The site features a clean, modern design with dark mode support, responsive navigation, and automated deployments.

In sidebars.ts, I set up auto-generated sidebars for each documentation section:

const sidebars = {
  notesSidebar: [
    {
      type: 'autogenerated',
      dirName: 'notes',
    },
  ],
  // Similar configuration for langs and frameworks
};

Blog Configuration​

I configured the blog with:

  • Reading time display
  • RSS feed support
  • Author information
  • Tag system for better content organization

Theme Customization​

The site uses Docusaurus's classic theme with several customizations:

Favicon​

I created a custom favicon that matches our site's branding:

<svg width="32" height="32" viewBox="0 0 32 32" fill="none" xmlns="http://www.w3.org/2000/svg">
  <rect width="32" height="32" rx="6" fill="#FF6B6B"/>
  <text x="50%" y="50%" text-anchor="middle" dy=".3em" fill="white" font-family="Arial" font-weight="bold" font-size="20">L</text>
</svg>

The favicon uses our primary color (#FF6B6B) with a bold "L" in white, creating a simple yet distinctive icon for the site.

Color Scheme​

I've implemented a custom color scheme using warm, engaging colors:

/* Light mode colors */
--ifm-color-primary: #ff6b6b;
--ifm-color-primary-dark: #ff4040;
--ifm-color-primary-darker: #ff2b2b;
--ifm-color-primary-darkest: #f00000;

/* Dark mode colors */
--ifm-color-primary: #ff8080;
--ifm-color-primary-dark: #ff5555;
--ifm-color-primary-darker: #ff4040;
--ifm-color-primary-darkest: #ff0000;

Theme Features​

  • Automatic theme switching based on system preferences
  • Manual light/dark mode toggle
  • Responsive design for all screen sizes
  • Enhanced code block syntax highlighting

Internationalization (i18n)​

To make our documentation accessible to a wider audience, I've added support for multiple languages:

Configuration​

i18n: {
  defaultLocale: 'en',
  locales: ['en', 'zh-CN', 'de-DE', 'ja-JP', 'en-GB'],
}

Translation Workflow​

  1. Generate translation files:
pnpm docusaurus write-translations

  1. Translate content in the following directories:

    • i18n/<locale>/docusaurus-plugin-content-docs
    • i18n/<locale>/docusaurus-plugin-content-blog
    • i18n/<locale>/docusaurus-theme-classic

  2. Access translated content via the language dropdown in the navigation bar.

Next Steps​

Future improvements planned:

  1. Adding search functionality
  2. Implementing versioning for documentation
  3. Adding more interactive components
  4. Enhancing the mobile experience

This setup provides a solid foundation for maintaining and growing our documentation site. The modular structure makes it easy to add new content and features as needed.