Docusaurus: Feature: referencing variables from markdown pages

[julen]

First of all, thanks for sharing and supporting Docusaurus! It's been pretty easy to get started.

I'm posting a feature request — I haven't found anything similar in the issue tracker so forgive me if it's been discussed before.

Motivation: sometimes docs need to reference information such as version numbers, URLs etc. and having them manually typed in the markdown pages is not ideal because this type of information often gets referenced multiple times.

Taking that into account, it would be great if Docusaurus supported passing variables into pages (from e.g. siteConfig). It already supports special Markdown markup via the <AUTOGENERATED_TABLE_OF_CONTENTS> marker, and it could potentially do something similar for variables.

For example, typing in<VAR:projectName> would get replaced with the value of siteConfig.projectName. Ideally this works in code blocks too (```).

[JoelMarcey]

Interesting idea. We did something similar for nuclide.io using JS and referencing the package.json file. I think this is something that could definitely be implemented for some upcoming version of Docusaurus.

[tibdex]

That would be an awesome feature!

Julen mentioned "version numbers, URLs, etc." but it would also be great to insert automatically computed markup from JSDoc for instance. Thus, if you decide to implement it, it would be nice to support the injection of Markdown (or HTML) markup and not only scalar values.

[gedeagas]

HI, @JoelMarcey I am planning to take this after finishing https://github.com/facebook/Docusaurus/pull/694 but I think I will work with scalar values first. Is that okay?

[JoelMarcey]

@gedeagas Sounds great! I think this is a feature that can be done in increments.

[zenflow]

Isn't this another thing best left to markdown plugins?

[endiliey]

While I agree with @zenflow, if @gedeagas intends to build his own plugin, that's welcome too☺

[gedeagas]

Hi @zenflow @endiliey, I am planning to do just that 😄 .
Making a plugin for remarkable to support this on docusaurus 📦

[zenflow]

Ok, but just to be clear: that plugin will not be included as a dependency of Docusaurus, right? It would be configured by users in their siteConfig.markdownPlugins?

I'm just a bit confused by the fact that this is a feature request for Docusaurus when nothing actually needs to change in Docusaurus for this to be supported

[tibdex]

Here's how variable injection can be done:

Put this in siteConfig.js:

const {Plugin: Embed} = require('remarkable-embed');

// Our custom remarkable plugin factory.
const createVariableInjectionPlugin = variables => {
  // `let` binding used to initialize the `Embed` plugin only once for efficiency.
  // See `if` statement below.
  let initializedPlugin;

  const embed = new Embed();
  embed.register({
    // Call the render method to process the corresponding variable with
    // the passed Remarkable instance.
    // -> the Markdown markup in the variable will be converted to HTML.
    inject: key => initializedPlugin.render(variables[key])
  });

  return (md, options) => {
    if (!initializedPlugin) {
      initializedPlugin = {
        render: md.render.bind(md),
        hook: embed.hook(md, options)
      };
    }

    return initializedPlugin.hook;
  };
};

const siteVariables = {
  scalar: 'https://example.com',
  // Since the variables are processed by Docusaurus's Markdown converter,
  // this will become a nice syntax-highlighted code block.
  markdown: [
    '```javascript',
    'const highlighted = true;',
    '```',
  ].join('\n'),
  // We can use HTML directly too as HTML is valid Markdown.
  html: [
    '<details>',
    '  <summary>More details</summary>',
    '  <pre>Some details</pre>',
    '</details>'
  ].join('\n')
};

const siteConfig = {
  markdownPlugins: [
    createVariableInjectionPlugin(siteVariables)
  ],

  // rest of the config
};

module.exports = siteConfig;

Then, in one of the doc page, write:

## Scalar injection
{@inject: scalar}

## Markdown injection
{@inject: markdown}

## HTML injection
{@inject: html}

And this is what Docusaurus would render:

As you can see, by leveraging remarkable-embed, the implementation of the custom plugin for variable injection is quite small. I'm not even sure it's worth making a dedicated npm package out of it.

The only drawback I can see is that the injected markup isn't pre-processed by Docusaurus. For instance, if one of the variables contains a Markdown title such as ## Custom title, this title won't appear in the secondary on-page navigation.

[gedeagas]

Awesome @tibdex.
I guess my comment above is obsolete 😄

[cmdcolin]

This is really sweet tibdex...it is not replacing variables that are inside of a markdown code block though. I guess those are kind of regarded as literals but as I might want some code to depend on a variable, is there anything I should do?

Edit: also realized the original post requests having this feature available in code blocks

[endiliey]

This issue is closed due to stale activity.

If you think there is a need for it, please open up a new issue with new template.

[camcamd]

First of all, thanks @tibdex for this plugin example !
Is there a way to have the injected markdown processed by docusaurus, so that we could inject markdown with docusaurus code tabs for instance ?

[tibdex]

An option is to preprocess the markdown files outside of Docusaurus. You can develop a pipeline that reads the unprocessed markdown files from another directory, process them, write them to the Docusaurus's markdown files directory, and then build your website with Docusaurus.

[anidotnet]

Is there any official way to reference variables in v2?

[JoelMarcey]

What type of variables are you trying to reference?

[anidotnet]

Hi @JoelMarcey, I want to declare a global javascript variable, say version, which I can reference and replace in doc files. This will be useful while writing download link or library version in the doc. I don't have to manually change the version in the doc every time I make a release. So is there any support of such kind in v2?

[JoelMarcey]

@yangshun Did this ever get implemented for v2, do you know?

cc @slorber

[yangshun]

Yeah you can write JS in MDX so you can import anything and use variables.

[JoelMarcey]

https://v2.docusaurus.io/docs/markdown-features

@anidotnet See if you can get that to work, and, if you are so inclined, you could send a pull request to update the documentation to talk about how to make it work.

[anidotnet]

Hi @JoelMarcey thanks. But I never used react and a newbie in js world. So if I write my version in a .env file like

VERSION=1.0

or write it in a version.js file at the root of the project like

export const siteVariables = {
    versionNumber: '1.0.0'
};

how do I use any one of these in an mdx file?

Mainly I am trying to replace a javascript variable in a code block like

<Tabs
  groupId="installation"
  defaultValue="java"
  values={[
    { label: 'Java', value: 'java', },
  ]
}>
<TabItem value="java">
    ```groovy
compile 'mylib:mylib:$versionNumber'
     ```
</TabItem>
</Tabs>

Any help would be highly appreciated.

[yangshun]

I don't know if you can use variables within the markdown syntax (fenced code blocks), but you can use it within JSX.

import {siteVariables} from '@site/src/versions';

// ...

<Tabs
  groupId="installation"
  defaultValue="java"
  values={[
    { label: 'Java', value: 'java', },
  ]
}>
<TabItem value="java">
// Cannot use Markdown syntax here
<code>compile 'mylib:mylib:{siteVariables.versionNumber}'</code>

</TabItem>
</Tabs>

[anidotnet]

@yangshun thanks a lot for the pointer. I have used below code to achieve seamless effect of fenced code block.

<pre><code parentName="pre" {...{
            "className": "language-groovy"
          }}>{`compile 'mylib:mylib:${siteVariables.versionNumber}'
`}</code></pre>

Thanks again for prompt help.