linkPlugins

Plugins in CODEDOC are basically configuration helpers, filling in the gaps of your project's configuration. They can add custom markdown components, init scripts to your bundle or HTML post processors, which makes them powerful tools in adding to the feature-set of your documentation project.

linkAdding Plugins

You can simply add plugins by adding them to plugins list in your config in .codedoc/config.ts:

.codedoc/config.ts
1linkimport { configuration } from '@codedoc/core';

2linkimport { formulaPlugin } from '@codedoc/core/components';

3link

4link// ...

5link

6linkexport const config = /*#__PURE__*/configuration({

7link  // ...

8link  plugins: [

9link    // ...

10link    formulaPlugin

11link  ],

12link  // ...

13link});

linkPriority of Plugins

Each plugin basically is a function that provides some additional configuration for your project. A plugin CANNOT override already defined configuration values, it can merely provide something that is not defined. This is to ensure that you have full explicit control over your project's configuration, and to avoid situations where you configure something manually but don't see its effect because some plugin is sneakily overriding it.

This priority rule also applies to plugins themselves, so a plugin that comes earlier in the plugins list basically gets priority over plugins that come later.

The following properties are an exception to this rule. All of these config properties are arrays, and value provided by any plugin for them will be concatenated with the value provided directly in .codedoc/config.ts:

• bundle.init
• page.meta.keywords
• page.scripts
• page.stylesheets
• page.post

Additionally, the following dictionary values will also be aggregated amongst all values provided by plugins and values defined directly in .codedoc/config.ts, though in case of colliding keys, the same priority rule applies (.codedoc/config.ts takes priority, then any plugin that comes first):

• markdown.customComponents
• markdown.customInlineComponents
• tocMarkdown.customComponents
• tocMarkdown.customInlineComponents

This basically allows plugins to provide their own custom markdown components, but still ensuring you can override any particular component provided by any plugin via .codedoc/config.ts.

linkWriting a Plugin

It is super easy to write your own plugin. For example, imagine you would want to create a Google Analytics plugin:

ga-plugin.tsx
1linkimport { StaticRenderer } from '@connectv/sdh';

2linkimport register from 'jsdom-global';

3linkimport { ConfigOverride } from '@codedoc/core';

4link

5linkconst renderer = new StaticRenderer();                   // --> create a static renderer

6linkregister();                                              // --> register jdom global so that we can create DOM elements

7link

8link

9linkexport function googleAnalytics(gacode: string) {

10link  return function(): ConfigOverride {

11link    return {

12link      page: {

13link        scripts: [

14link          <script>{`

15link          window.ga=window.ga||function(){(ga.q=ga.q||[]).push(arguments)};ga.l=+new Date;

16link          ga('create', 'UA-${gacode}-Y', 'auto');

17link          ga('send', 'pageview');

18link          `}</script>,

19link          <script async src='https://www.google-analytics.com/analytics.js'/>

20link        ]

21link      }

22link    }

23link  };

24link}

This simple plugin just adds two scripts to each page, which is how you should add Google Analytics to any webpage. To consume it, you would simply do this:

.codedoc/config.ts
1linkimport { configuration } from '@codedoc/core';

2linkimport { googleAnalytics } from 'ga-plugin';

3link

4link// ...

5link

6linkexport const config = /*#__PURE__*/configuration({

7link  // ...

8link  plugins: [

9link    // ...

10link    googleAnalytics('XXXX')             // --> your google analytics ID goes here

11link  ],

12link  // ...

13link});

For a more involved example, lets take a look at the actual code of formulaPlugin, which enables TeX formulas in CODEDOC:

src/components/formula/plugin.ts
1linkimport { ConfigOverride } from '../../config/override.type';

2link

3linkimport { Formula } from './component';                   // --> get the formula component

4linkimport { InlineFormula } from './inline';                // --> get the inline-formula component

5linkimport { enableFormula } from './post';                  // --> get the post-processor adding necessary styles and scripts

6linkimport { zoomOnFormula$ } from './zoom-on-formula';      // --> get the bundle script that enables zooming on formulas

7link

8link

9linkexport function formulaPlugin(): ConfigOverride {

10link  return {

11link    markdown: {

12link      customComponents: { Formula },                     // --> add formula component

13link      customInlineComponents: { Formula: InlineFormula } // --> add formula inline component

14link    },

15link    tocMarkdown: {

16link      customComponents: { Formula },                     // --> add formula component to ToC (b/c why not)

17link      customInlineComponents: { Formula: InlineFormula } // --> add formula inline component to ToC

18link    },

19link    page: {

20link      post: [enableFormula]                              // --> add the post-processor

21link    },

22link    bundle: {

23link      init: [zoomOnFormula$]                             // --> add the bundle script

24link    }

25link  }

26link}