Star

MIT License
Copyright © 2020
CONNECT-platform

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:

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):

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}

PluginsAdding PluginsPriority of PluginsWriting a Plugin

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right