Skip to main content

Aliases

Key aliases​

  • @site: This alias points to the root of your Docusaurus site's src directory. It is typically used for importing components, assets, or data that are specific to your individual Docusaurus project and reside within src. 
    import MyComponent from '@site/components/MyComponent';
  • @theme: This alias points to the topmost component in the Docusaurus "component stack" for a given component name. This means if you have swizzled a component (e.g., CodeBlock) by placing a custom version in website/src/theme, then @theme/CodeBlock will point to your custom version. Otherwise, it will point to the version provided by the Docusaurus theme or plugins. 
    import Navbar from '@theme/Navbar';
  • @theme-original: This alias points to the topmost non-swizzled component in the Docusaurus component stack. It is useful when you have swizzled a component and want to access the original, un-swizzled version within your custom component. For example, if you swizzle CodeBlock, you can import @theme-original/CodeBlock within your custom CodeBlock to render the base functionality and then add your enhancements. 
    import OriginalCodeBlock from '@theme-original/CodeBlock';
  • @theme-init: This alias points to the bottommost component in the Docusaurus component stack, which is typically the initial version provided by the Docusaurus theme or plugin that first introduced that component. This alias is primarily useful for plugin/theme authors who want to enhance a component without directly modifying the topmost version, ensuring they are building upon the foundational implementation. Site creators should generally use @theme or @theme-original instead. 
    import InitialCodeBlock from '@theme-init/CodeBlock';
  • @generated: Points to the directory where Docusaurus generates various files, such as client modules. 
    import '@generated/client-modules';
  • @docusaurus: Refers to the Docusaurus core packages.
  • ~docs, ~blog, ~pages, ~debug: These aliases are used internally by Docusaurus for specific content types and debugging.

Adding Custom Webpack Aliases​

You can also use a plugin with configureWebpack to add your own Webpack aliases.

export default function MyAliasPlugin(context, options) {
  return {
    name: 'my-alias-plugin',
    configureWebpack() {
      return {
        resolve: {
          alias: {
            "@myAlias", "/my/aliased/path"
          },
        },
      };
    },
  };
}

You can add your own custom Webpack aliases in Docusaurus using the docusaurus-plugin-module-alias package. Install the plugin:

npm install docusaurus-plugin-module-alias
# or
yarn add docusaurus-plugin-module-alias

Configure in docusaurus.config.ts:

const path = require('path');

module.exports = {
  // ...
  plugins: [
    [
      'docusaurus-plugin-module-alias',
      {
        alias: {
          '@local/component': path.resolve(__dirname, './src/components/MyComponent.js'),
          '@utils': path.resolve(__dirname, './src/utils'),
        },
      },
    ],
  ],
};

Important Considerations​

  • Do not override core Docusaurus aliases: Aliases like @site, @generated, @docusaurus, ~docs, ~blog, ~pages, and ~debug are reserved and should not be overridden with custom configurations.
  • IDE Integration: For better developer experience, ensure your IDE (e.g., VS Code, WebStorm) is configured to recognize these Webpack aliases to enable proper autocompletion and module resolution. This often involves creating or configuring a jsconfig.json or tsconfig.json file.