Star

MIT License
Copyright © 2020
CONNECT-platform

linkCustom Components

Lets create a simple Card component and add it to our markdowns. Let's first create the two following files:

1.codedoc/components/card/index.tsx # --> main component code

2.codedoc/components/card/style.ts # --> component styles


linkComponent Code

Codedoc uses CONNECTIVE SDH for its component system, alongside CONNECTIVE JSS themes for theming (which is in turn based on JSS). As a result, a simple cards document would look like this:

.codedoc/components/card/index.tsx
1import { ThemedComponentThis } from '@connectv/jss-theme'; // @see [CONNECTIVE JSS Theme](https://github.com/CONNECT-platform/connective-jss-theme)

2import { RendererLike } from '@connectv/html'; // @see [CONNECTIVE HTML](https://github.com/CONNECT-platform/connective-html)

3import { CodedocTheme } from '@codedoc/core'; // --> Type helper for theme object

4

5import { CardStyle } from './style'; // @see tab:style.ts

6

7

8export interface CardOptions { // --> a nice interface for possible props

9 raise: string; // --> which is the raise level of our cards. Note that all props MUST be of type `string`

10}

11

12

13export function Card(

14 this: ThemedComponentThis, // --> keep typescript strict typing happy

15 options: CardOptions, // --> the component props (attributes)

16 renderer: RendererLike<any, any>, // --> our beloved renderer

17 content: any, // --> the content of the component

18) {

19 const classes = this.theme.classes(CardStyle); // --> fetch the theme-based classes

20 let raise = 'raised-0';

21 if (options && options.raise === '1') raise = 'raised-1'; // --> determine the proper raise level based on given attributes

22 if (options && options.raise === '2') raise = 'raised-2';

23

24 return <div class={`${classes.card} ${raise}`}>

25 {content}

26 </div>;

27}

.codedoc/components/card/style.ts
1import { themedStyle } from '@connectv/jss-theme'; // @see [Connective JSS Theme](https://github.com/CONNECT-platform/connective-jss-theme)

2import { CodedocTheme } from '@codedoc/core';

3

4

5export const CardStyle = themedStyle<CodedocTheme>(theme => ({

6card: {

7 display: 'inline-block',

8 verticalAlign: 'middle',

9 borderRadius: 8,

10 padding: 8,

11 maxWidth: 320,

12 margin: 16,

13 overflow: 'hidden',

14 cursor: 'pointer',

15 transition: 'box-shadow .3s, transform .3s',

16

17 '&.raised-0': { boxShadow: '0 1px 3px rgba(0, 0, 0, .12)' }, // --> different styles for different raise-levels

18 '&.raised-1': { boxShadow: '0 3px 6px rgba(0, 0, 0, .18)' },

19 '&.raised-2': { boxShadow: '0 6px 18px rgba(0, 0, 0, .25)' },

20 '&:hover': {

21 boxShadow: '0 6px 18px rgba(0, 0, 0, .25)',

22 transform: 'translateY(-8px)'

23 },

24

25 '& img': {

26 margin: -8,

27 marginTop: -24,

28 width: 'calc(100% + 16px)',

29 maxWidth: 'none',

30 },

31

32 '& strong': {

33 fontSize: 18,

34 display: 'block',

35 color: theme.light.primary, // --> so lets make the title's of the primary color

36 'body.dark &': { color: theme.dark.primary }, // --> but also do respect dark-mode settings

37 '@media (prefers-color-scheme: dark)': { // --> this is to ensure proper dark-mode colors even before the scripts are loaded and user overrides are fetched

38 'body:not(.dark-mode-animate) &': {

39 color: theme.dark.primary,

40 },

41 },

42 },

43 }

44}));


linkConfiguration

To add this card component to our codedoc config, lets modify .codedoc/config.ts like this:

.codedoc/config.ts
1

2import {

3 configuration,

4 DefaultMarkdownCustomComponents // --> make sure to import the default components

5} from '@codedoc/core';

6

7import { theme } from './theme';

8import { Card } from './components/card'; // --> import the card component itself

9

10

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

12 // ...

13 markdown: { // --> update markdown config

14 customComponents: { // --> add to custom components

15 ...DefaultMarkdownCustomComponents, // --> make sure to add default markdown components. otherwise the default components will not work!

16 Card, // --> add our own card component

17 }

18 },

19 // ...

20});


linkUsing The Component

Now we can use our card component in our markdown files:

some-doc.md
1> :Card

2>

3> ![Card Hero](https://i.etsystatic.com/14457190/r/il/3cb8ff/1676245710/il_570xN.1676245710_ba0u.jpg)

4>

5> **Banksy**

6> Banksy is an anonymous England-based street artist, vandal, political activist, and film director, active since the 1990s.

7> His satirical street art and subversive epigrams combine dark humour with graffiti executed in a distinctive stenciling technique.

8> > :Buttons

9> > > :Button label=Wiki, url=https://en.wikipedia.org/wiki/Banksy

10

11> :Card raise=1

12>

13> ![Card Hero](https://www.tate.org.uk/art/images/work/T/T00/T00384_9.jpg)

14>

15> **Jackson Pollock**

16> Paul Jackson Pollock was an American painter and a major figure in the abstract expressionist movement.

17> He was widely noticed for his technique of pouring or splashing liquid household paint onto a horizontal surface,

18> enabling him to view and paint his canvases from all angles

19> > :Buttons

20> > > :Button label=Wiki, url=https://en.wikipedia.org/wiki/Jackson_Pollock

Card Hero

Banksy Banksy is an anonymous England-based street artist, vandal, political activist, and film director, active since the 1990s. His satirical street art and subversive epigrams combine dark humour with graffiti executed in a distinctive stenciling technique.

Wiki

Card Hero

Jackson Pollock Paul Jackson Pollock was an American painter and a major figure in the abstract expressionist movement. He was widely noticed for his technique of pouring or splashing liquid household paint onto a horizontal surface, enabling him to view and paint his canvases from all angles

Wiki

linkCustom Inline Components

You can similarly create your own inline custom components:

.codedoc/components/tag/index.tsx
1import { ThemedComponentThis } from '@connectv/jss-theme';

2import { RendererLike } from '@connectv/html';

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

4

5import { TagStyle } from './style'; // @see tab:Style Code

6

7

8export function Tag(

9 this: ThemedComponentThis<CodedocTheme>,

10 _: any,

11 renderer: RendererLike<any, any>,

12 content: any

13) {

14 const classes = this.theme.classes(TagStyle);

15 return <span class={classes.tag}># {content}</span>

16}

.codedoc/components/tag/style.ts
1import { themedStyle } from '@connectv/jss-theme';

2import { CodedocTheme } from '@codedoc/core';

3

4

5export const TagStyle = themedStyle<CodedocTheme>(theme => ({

6 tag: {

7 display: 'inline-flex',

8 alignItems: 'center',

9 verticalAlign: 'middle',

10 height: 16,

11 borderRadius: 16,

12 padding: 8,

13 background: theme.light.primary,

14 color: theme.light.primaryContrast,

15

16 'body.dark &': {

17 background: theme.dark.primary,

18 color: theme.dark.primaryContrast,

19 },

20 }

21}));

.codedoc/config.ts
1import {

2 configuration,

3 DefaultMarkdownCustomInlineComponents // --> make sure to import the default components

4} from '@codedoc/core';

5

6import { theme } from './theme';

7import { Tag } from './components/tag'; // --> import the tag component itself

8

9

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

11 // ...

12 markdown: { // --> update markdown config

13 customInlineComponents: { // --> add to custom components

14 ...DefaultMarkdownInlineCustomComponents, // --> make sure to add default markdown components. otherwise the default components will not work!

15 Tag, // --> add our own tag component

16 }

17 },

18 // ...

19});

Which can be used like this:

docs/md/some-doc.md
1<!-- ... -->

2And now lets use [Some Tags](:Tag) inside our text.

3<!-- ... -->

And now lets use # Some Tags inside our text.

Custom ComponentsComponent CodeConfigurationUsing The ComponentCustom Inline Components

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right