Create plugin a custom plugin

[201flaviosilva]

Hey there,

I'm trying to create a local custom plugin to convert JsDoc to docusaurus, based on this (using-plugins), and this (plugin-methods) official documentation I think I have done all right, but the plugin doesn’t work 😅

• My custom plugin:
  https://github.com/201flaviosilva/Impacto/blob/e575ac973452af4468a56279ee3d0a797d96e9fa/docs/plugins/jsdoc2docusaurus.js
• My docusaurus.config.js: https://github.com/201flaviosilva/Impacto/blob/e575ac973452af4468a56279ee3d0a797d96e9fa/docs/docusaurus.config.js

(Pls I need help, I can’t find what is wrong 😅)

[Advait251206]

Your plugin is very close, but it doesn’t work mainly because of wrong Docusaurus lifecycle usage + an immediate function call that breaks everything.

Below is a corrected, production-ready version and explanation.

---

❌ What is wrong in your current plugin

1. You are calling the function manually

generateDocs();

This runs outside Docusaurus lifecycle, so:

• context is undefined
• it runs before build/dev starts
• it bypasses plugin system completely

👉 This line must be removed.

---

2. loadContent() is misused

You wrote:

async loadContent() { return generateDocs(context, opts); }

But:

• loadContent() is for returning data
• your function does file writing (side effects)
• so Docusaurus ignores it or runs it unpredictably

---

3. Wrong lifecycle for your goal

You are doing:

“Generate markdown files from JSDoc and write to /docs”

That is a build-time file generation task, so correct hook is:

✔ postBuild() (BEST)
✔ or extendCli() (optional CLI command)

---

4. Unsafe path handling

This part is fragile:

relativePath.replace("../src/", "")

This will break on:

• Windows
• CI environments
• different folder structures

---

✅ FIXED FULL PLUGIN (WORKING VERSION)

const fs = require('fs');
const path = require('path');
const glob = require('glob');
const jsdoc2md = require('jsdoc-to-markdown');

function generateDocs() {
  console.log('Generating JSDoc documentation...');

  const files = glob.sync(path.join(process.cwd(), 'src/**/*.js'), {
    ignore: [
      '**/node_modules/**',
      '**/cypress/**',
      '**/__tests__/**',
      '**/*.test.js',
      '**/*_spec.js',
    ],
  });

  for (const file of files) {
    const fileName = path.basename(file, '.js');

    const markdown = jsdoc2md.renderSync({
      files: file,
      configure: path.join(process.cwd(), 'jsdoc.conf.json'),
      'heading-depth': 1,
    });

    if (!markdown) continue;

    const relativeDir = path.dirname(path.relative(process.cwd(), file));

    const outputDir = path.join(
      process.cwd(),
      'docs',
      'API',
      relativeDir
    );

    fs.mkdirSync(outputDir, { recursive: true });

    fs.writeFileSync(
      path.join(outputDir, `${fileName}.md`),
      markdown
    );
  }

  console.log('✔️ JSDoc docs generated');
}

function jsdoc2docusaurus() {
  return {
    name: 'jsdoc2docusaurus',

    async postBuild() {
      generateDocs();
    },
  };
}

module.exports = jsdoc2docusaurus;

---

✅ Docusaurus config usage

plugins: [
  require.resolve('./plugins/jsdoc2docusaurus'),
],

---

🚀 WHY THIS WORKS

✔ postBuild is correct because:

• runs after Docusaurus build
• safe filesystem access
• ideal for generating static docs
• does not interfere with dev server

---

🧠 OPTIONAL IMPROVEMENT

Instead of writing directly into /docs, a cleaner approach is:

Output to:

generated/api/

Then configure:

plugins: [
  [
    '@docusaurus/plugin-content-docs',
    {
      path: 'generated/api',
      routeBasePath: 'api',
    },
  ],
],

---

❌ Summary of your issues

• ❌ manual function call (generateDocs())
• ❌ misuse of loadContent
• ❌ wrong lifecycle hook
• ❌ unsafe path logic
• ❌ mixing runtime + build-time logic

---

✅ Final takeaway

Your plugin was structurally correct, but it was executed in the wrong phase of Docusaurus.

Switching to postBuild() fixes the entire system.

---

If this answer helped or pointed you in the right direction, I'd appreciate it if you could mark it as the accepted answer so it's easier for others with the same issue to find.

Also, if you found my contribution useful, I'd appreciate it if you could check out my GitHub profile, follow me, and star any repositories you find interesting.

GitHub: https://github.com/Advait251206