How to access the site configuration from markdown pages?

[ilg-ul]

I'm trying to add some custom fields by parsing a JSON file at the beginning of docusaurus.config.ts:

...
import { getCustomFields } from './src/lib/customFields';
import logger from '@docusaurus/logger'

export const customFields = getCustomFields();
logger.info(customFields)

const config: Config = {
...
}

The code uses the node.js modules 'url', 'fs' and 'path', but webpack 5 no longer includes support for them.

The error messages are:

Module not found: Error: Can't resolve 'url' in '/Users/ilg/MyProjects/xpack-dev-tools.github/xPacks/openocd-xpack.git/website/src/lib'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "url": require.resolve("url/") }'
        - install 'url'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "url": false }

--------------------------

Module not found: Error: Can't resolve 'path' in '/Users/ilg/MyProjects/xpack-dev-tools.github/xPacks/openocd-xpack.git/website/src/lib'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "path": require.resolve("path-browserify") }'
        - install 'path-browserify'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "path": false }

Where should I add the resolve.fallback: {} statements? I tried a webpack.config.js, but it was not effective.

Or, even better, how can I run my initialisation code only when the static site is generated and not in the browser?

Sorry if these are silly questions, my knowledge of webpack is close to none... :-(

Thank you,

Liviu

[slorber]

docusaurus.config.ts does not run in the browser, and is not bundled by Webpack, so adding and requiring code here does not involve Webpack. At best the content of this file is sent serialized to the browser as JSON.

You can add resolve.fallback by writing a Docusaurus plugin with a configureWebpack lifecycle method.

---

Or, even better, how can I run my initialisation code only when the static site is generated and not in the browser?

I don't even know what this means 😅

---

I can only advise on such things if I see a minimal repro. Here it's very unclear what you are trying to do. And I'm not even sure the error message you get is related.

[ilg-ul]

I can only advise on such things if I see a minimal repro

• https://codesandbox.io/p/devbox/ecstatic-silence-k3pjwr

As you can see via git diff, I changed two files, I added a customFields object in docusaurus.config.ts and displayed it in docs/intro.mdx.

If you comment out the reference to url in the configuration file, the error no longer triggers.

The purpose of the whole issue is to find a way to dynamically compute some custom fields from an external JSON file (actually the package.json of the project where the website is included).

Any idea how to make references to node.js modules work in the configuration file?

[slorber]

I do not have access to that sandbox

Any idea how to make references to node.js modules work in the configuration file?

Can you prove what you say in a minimal repro?

Here's my minimal repro showing that it works perfectly fine putting that code in the config: https://stackblitz.com/edit/github-xtae9b?file=docusaurus.config.js

import url from 'node:url';

console.log(
  'url test',
  url.parse('https://user:[email protected]:8080/p/a/t/h?query=string#hash')
);

The problem is likely that your repro is not minimal.

Please always create a truly minimal repro to validate your assumptions, otherwise you put the burden on me to investigate your whole project and find out potentially related problems.

---

Most likely, you are trying to import the config file (nodejs side) from the browser side (MDX/React). If you need to read the config file from the browser side, you should use useDocusaurusContext().siteConfig instead (as a last resort you can import from the serialized @generated/config).

Yes, importing Node.js APIs in the browser side does not give good outcomes. Imagine you use fs.writeFile() on that config file, and it now runs in the browser, do you expect the browser to be able to write files on visitor's file system? You can't use Node APIs in the browser.

[ilg-ul]

I do not have access to that sandbox ...

Can you provide a link to a documentation page explaining how to create a minimal repro that you can use to check my assumptions?

The only documentation I found was https://docusaurus.io/docs/playground. I clicked the TypeScript button there, got the project created, then added a few lines to two files and the build crashed.

Then I passed you the link.

If there is something more that must be done, please document it properly.

---

I tried to change the visibility of that project to public, but I have no idea if this is enough. If not, please provide more details on what you expect me to do. I have no prior experience with Sandbox or Blitz.

The new url seems to be the same:

• https://codesandbox.io/p/devbox/ecstatic-silence-k3pjwr

---

Can you prove what you say in a minimal repro?

Yes. When you'll be able to see the repro you'll see yourself if this is a minimal repro or not.

I only added this to the docusaurus.config.ts configuration:

// ...
import type * as Preset from "@docusaurus/preset-classic";

import logger from "@docusaurus/logger";
import { fileURLToPath } from "url";

const customFields = {
  myField: "Baburiba",
};

logger.info(customFields);

// Commenting out this line fixes the error.
logger.info(fileURLToPath(import.meta.url));

const config: Config = {
  title: "My Site",
  tagline: "Dinosaurs are cool",
  // ...
  customFields: customFields,
};

And changed the first paragraph in docs/intro.md to display the title and my field from the configuration:

import siteConfig from '@site/docusaurus.config';

# Tutorial Intro

Let's discover **Docusaurus in less than 5 minutes**. { siteConfig.title } { siteConfig.customFields.myField }

If importing siteConfig directly is not possible, can you provide a functional alternative?

Yes, importing Node.js APIs in the browser side does not give good outcomes.

I do not want to import any Node.js API from the browser side, and generally I do not want to have anything to do with the browser side.

I just want to be able to generate at build time, by running some code in the docusaurus.config.ts file, a customFields object with some application specific values by reading a package.json file located in a top folder.

The minimal repro just uses the url module to display the current folder. It is the first step in locating, reading and parsing the JSON file, but I did not get that far, the simple presence of a reference to url crashes the build:

 *  Executing task: CodeSandbox: start 

yarn run v1.22.19
$ docusaurus start
[INFO] Starting the development server...
[INFO] {"myField":"Baburiba"}
[INFO] /project/sandbox/docusaurus.config.ts
[SUCCESS] Docusaurus website is running at: http://localhost:3000/

✖ Client
  Compiled with some errors in 16.41s

Module not found: Error: Can't resolve 'url' in '/project/sandbox'
BREAKING CHANGE: webpack < 5 used to include polyfills for node.js core modules by default.
This is no longer the case. Verify if you need this module and configure a polyfill for it.

If you want to include a polyfill, you need to:
        - add a fallback 'resolve.fallback: { "url": require.resolve("url/") }'
        - install 'url'
If you don't want to include a polyfill, you can use an empty module like this:
        resolve.fallback: { "url": false }
client (webpack 5.91.0) compiled with 1 error

[ilg-ul]

you should use useDocusaurusContext().siteConfig

I could not find any documentation on how to use this expression in a markdown page, where only imports seem available.

I tried some tricks with exports, they seemed accepted when running npm start, but failed in npm build with some errors related to useDocusaurusContext() (however the exact error might be different, this was yesterday and I don't remember the details).

as a last resort you can import from the serialized @generated/config

I tried this in docs/intro.mdx:

import siteConfig from '@generated/config';

# Tutorial Intro

Let's discover **Docusaurus in less than 5 minutes**. { siteConfig.title } { siteConfig.customFields.myField }

The result was:

ERROR in ./docs/intro.mdx 36:0-43
Module not found: Error: Can't resolve '@generated/config' in '/Users/ilg/tmp/dd/website-3.4/docs'

[slorber]

Can you provide a link to a documentation page explaining how to create a minimal repro that you can use to check my assumptions?

The concept of minimal repro is not a Docusaurus concept, and can be found on google

Here's a great resource to read and understand how you can save me time when I spend that time helping you achieve something:

https://antfu.me/posts/why-reproductions-are-required

The sandbox you provided looks fine and minimal enough, my assumption was wrong and based on our past interactions. Sorry about that.

---

And changed the first paragraph in docs/intro.md to display the title and my field from the configuration:

import siteConfig from '@site/docusaurus.config';

That's what I explained above: you can't do that. The config file is a Node.js file, and the MDX docs will run in the browser. The config file has access to the full power of Node.js, and the browser files (MDX + React files) have to limit themselves to browser features, and only importing files using browser features.

(side note: this is also why I thought your repro was not minimal: because you didn't explain that part in your initial support request, yet this very line is the actual problem here, so I assumed your sandbox would contain more than what you claimed).

I do not want to import any Node.js API from the browser side, and generally I do not want to have anything to do with the browser side.

In practice this is what you do: the docs (rendered in the browser with React) import the node config, which uses the url API which is a Node.js API.

---

I could not find any documentation on how to use this expression in a markdown page, where only imports seem available.

A Markdown page is using MDX, which allows you to use ESM import/export and React features in Markdown, including using or declaring React components, and using hooks.

Things are documented here, unfortunately Docusaurus can't teach you everything about MDX and React, and you'd have to read their respective documentation.

https://docusaurus.io/docs/next/markdown-features/react
https://docusaurus.io/docs/next/docusaurus-core#useDocusaurusContext

For example, use the MDX playground to see how MDX compiles your document into a React component, possibly using an imported hook:

---

I was wrong, the import is not @generated/config but @generated/docusaurus.config. Note this is not the recommended approach but probably the most convenient for what you want to do if you don't know React well.

---

Note, it's also possible to create a remark plugin yourself to automatically import things in MDX docs. In the future I plan to provide this feature out of the box so you could assume the variable already exists and is accessible in all markdown docs:

# My Doc

xyz: {context.siteConfig.customFields.xyz}

[ilg-ul]

the import is not @generated/config but @generated/docusaurus.config.

That was useful. After this change, the code parsing the package.json is functional. It looks like this:

• https://github.com/xpack-dev-tools/openocd-xpack/blob/7d337bf3c877c79734af25172cc4d9b3e7cb7822/website/docusaurus.config.ts#L13-L43

And the code that uses the configuration looks like this:

• https://github.com/xpack-dev-tools/openocd-xpack/blob/7d337bf3c877c79734af25172cc4d9b3e7cb7822/website/docs/install/_common/_automated-install.mdx?plain=1#L3-L13

Note this is not the recommended approach but probably the most convenient for what you want to do if you don't know React well.

This is a bit concerning. In my site there are a lot of files, all in markdown, that need to show the custom fields, and this is only the first of a set of +20 related sites, so if this is not recommended, and at a later time will no longer work, updating all sites will require quite a lot of work.

So any solution that reduces this risk is welcome. (writing my own remark plugin is a bit too much).

[slorber]

The recommended way is to use the only documented public API (useDocusaurusContext().siteConfig), usually by declaring a React component, but in practice using the hook inline also works

But using @generated/docusaurus.config is fine, just less common and less testable (harder to mock if you write unit tests), probably not a big deal.

https://stackblitz.com/edit/github-xjq8sm?file=docusaurus.config.js,src%2Fpages%2Findex.mdx

import useDocusaurusContext from '@docusaurus/useDocusaurusContext';

# Hello, world!

## Render custom fields through a React component

export function DisplayCustomFields() {
  const { siteConfig } = useDocusaurusContext();
  return <>{JSON.stringify(siteConfig.customFields)}</>;
}

<DisplayCustomFields />

## Render custom fields inline

{JSON.stringify(useDocusaurusContext().siteConfig.customFields)}

Or you can write a remark plugin that makes it needless to import it: {docusaurusContext.siteConfig.customFields.xyz}. The remark plugin would just inject the @generated/docusaurus.config automatically at the top of each file.

[ilg-ul]

The recommended way is to use the only documented public API (useDocusaurusContext().siteConfig), usually by declaring a React component,

Writing components each time the fields are used is a significant overhead.

but in practice using the hook inline also works
{ useDocusaurusContext().siteConfig.customFields.myField }

Right, just that this gets very long and hard to read.

I would prefer something like {context.siteConfig.customFields.xyz}.

If @generated/docusaurus.config is acceptable, I'll probably stick to it for now.

[slorber]

Writing components each time the fields are used is a significant overhead.

Agree, but you can also create a generic component that does not, and register it globally so that you just have to write <CustomField name="xyz"/>

https://docusaurus.io/docs/markdown-features/react#mdx-component-scope

Right, just that this gets very long and hard to read.

You are free to create your own custom hooks to make it shorter

function useField(name) {
  return useDocusaurusContext().siteConfig.customFields[name];
}

Then just write {useField("xyz")} in markdown content.

Similarly you could expose any additional JS module interface between your mdx content and the @generated/docusaurus.config import:

import config from "@generated/docusaurus.config"

export const fields = config.myCustomFields;

import {fields} from "@site/src/myCustomFieldsIntermediateFile"

# Title 

{fields.xyz}

---

TLDR: we expose low-level APIs but you have a lot of possibilities to make it more concise and convenient to use. We only present a few here.

[ilg-ul]

You are free to create your own custom hooks to make it shorter

That was useful, I created a function customField(name) and I updated the site to use it, the code seems slightly more readable now.

Thank you!

[ilg-ul]

Can you provide a link to a documentation page explaining how to create a minimal repro that you can use to check my assumptions?

The concept of minimal repro is not a Docusaurus concept, and can be found on google

We have some communication issues.

The question was not how to write a minimal repro, the Playground page provides the buttons to create the minimal repro, and I assume the resulting projects are minimal.

The question was how to use the tools that you recommend there, in such a way that they are useful for you.

For example for CodeSandbox you should mention how to make the project public, and explain how to pass back a link to the project (the generated project permalinks are confusing).

I also tried StackBlitz, but could not make it work, so probably there are more explanations needed for it.

Otherwise, if you assume all users are experts in using these tools, don't be surprised if you get links to broken projects.

[slorber]

The tool doesn't matter, and evolve over time. Codesandbox didn't have this public/private thing initially.

You can also provide a GitHub repo based on the init template.

If you give me a GitHub repo like this: https://github.com/slorber/docusaurus-starter
I can just add pr.new in front and open it in Stackblitz: https://pr.new/github.com/slorber/docusaurus-starter

What matters here is not the tool, but that the project doesn't contain noise that I have to inspect. You can choose the tool you are most familiar with.

People tend to share a link to super large real product websites with complexity and third-party dependencies I didn't create and assume I have time to investigate. I simply want to avoid that.

StackBlitz is a quite innovative technology and may not work well in all browsers versions, notably Safari.

But I agree, I should write docs on how to submit a good repro, because it's time consuming to explain all this many time.

[ilg-ul]

But I agree, I should write docs on how to submit a good repro, because it's time consuming to explain all this many time.

I'm glad you reached to this conclusion, since trying to figure out how to use these tools is time consuming for the users too.