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
1import { configuration } from '@codedoc/core';

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

3

4// ...

5

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

7 // ...

8 plugins: [

9 // ...

10 formulaPlugin

11 ],

12 // ...

13});


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
1import { StaticRenderer } from '@connectv/sdh';

2import register from 'jsdom-global';

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

4

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

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

7

8

9export function googleAnalytics(gacode: string) {

10 return function(): ConfigOverride {

11 return {

12 page: {

13 scripts: [

14 <script>{`

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

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

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

18 `}</script>,

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

20 ]

21 }

22 }

23 };

24}

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
1import { configuration } from '@codedoc/core';

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

3

4// ...

5

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

7 // ...

8 plugins: [

9 // ...

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

11 ],

12 // ...

13});

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
1import { ConfigOverride } from '../../config/override.type';

2

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

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

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

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

7

8

9export function formulaPlugin(): ConfigOverride {

10 return {

11 markdown: {

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

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

14 },

15 tocMarkdown: {

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

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

18 },

19 page: {

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

21 },

22 bundle: {

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

24 }

25 }

26}

PluginsAdding PluginsPriority of PluginsWriting a Plugin

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right