@docusaurus, @site, and baseUrl

In Docusaurus, @docusaurus, @site, and baseUrl each serve specific purposes related to path management and resource access within your project. Here's a detailed comparison:

1. @docusaurus

• Purpose:

  • @docusaurus is an alias used to import core Docusaurus modules, components, utilities, and plugins. It provides a straightforward way to access built-in Docusaurus features without needing to know their exact file paths.

• Scope:

  • It is used primarily in your JavaScript or MDX files to import Docusaurus-specific functionality.

• Use Cases:

  • Importing Components: Access Docusaurus components like Link, Tabs, etc.

    import Link from '@docusaurus/Link';
  • Accessing Utilities: Use Docusaurus utilities, such as useBaseUrl, which helps resolve paths relative to the baseUrl.

    import useBaseUrl from '@docusaurus/useBaseUrl';

• Examples:

  • Importing and using a Docusaurus component in a React file:

    import Tabs from '@docusaurus/Tabs';
    import TabItem from '@docusaurus/TabItem';

2. @site

• Purpose:

  • @site is an alias used to reference the root directory of your Docusaurus project. It simplifies the process of importing files, assets, or components that reside at the root of your project directory.

• Scope:

  • It is used in your project code (JavaScript, MDX) to import or reference resources from the root directory of your project.

• Use Cases:

  • Importing Assets: Easily import images, JSON files, or other resources from the project’s root directory.

    import logo from '@site/static/img/logo.png';
  • Referencing Files in MDX: Reference or import other Markdown or MDX files from the project root.

    import Component from '@site/src/components/Component';

• Examples:

  • Including an image in a React component:

    import myImage from '@site/static/img/my-image.png';

3. baseUrl

• Purpose:

  • baseUrl is a configuration option in docusaurus.config.js that defines the base path for all URLs generated by your site. It ensures that paths to pages, assets, and links are correctly resolved based on where your site is deployed.

• Scope:

  • It applies globally across your site, influencing how URLs are generated in content, configuration, and links.

• Use Cases:

  • Deployment Configuration: Set the baseUrl when deploying your site to a subdirectory rather than the root of a domain.

    module.exports = {
      baseUrl: '/docs/',
    };
  • Link and Asset Generation: Ensure that all internal links and assets include the correct base path, making them work regardless of the deployment location.

    ![My Image](/docs/img/my-image.png)

• Examples:

  • If your site is deployed at https://example.com/docs/, you would set:

    module.exports = {
      baseUrl: '/docs/',
    };

Summary of Differences

• @docusaurus:

  • Purpose: Import Docusaurus core modules, components, and utilities.
  • Scope: Used in code to access built-in Docusaurus features.
  • Example: import Link from '@docusaurus/Link';

• @site:

  • Purpose: Reference the root directory of your project in imports.
  • Scope: Used in code to import files or assets from the project root.
  • Example: import logo from '@site/static/img/logo.png';

• baseUrl:

  • Purpose: Configure the base path for all URLs in your site for proper resolution upon deployment.
  • Scope: Set in docusaurus.config.js to manage deployment paths.
  • Example: baseUrl: '/docs/' in docusaurus.config.js.

These three elements work together to manage paths and resources in Docusaurus, ensuring that your site’s content is correctly linked, assets are properly referenced, and Docusaurus features are easily accessible.