Star

MIT License
Copyright © 2020
CONNECT-platform

linkPage Configuration

Page configuration determines properties of each generated HTML page. You can change this configuration via .codedoc/config.ts:

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

2import { guessTitle } from '@codedoc/core/transport';

3// ...

4

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

6 //...

7 page: {

8 title: { // --> configuration for page title

9 base: 'Codedoc Sample Page', // --> the base term of page title

10 connector: ' | ', // --> the connector of different parts of the page title

11 extractor: (content, config) => // --> the page-specific title extractor

12 guessTitle(

13 content,

14 config.page.title.base,

15 config.page.title.connector

16 ),

17 },

18 favicon: undefined, // --> link to your fav icon

19 meta: { // --> meta tags of each page

20 subject: undefined, // --> the subject meta tag for each page

21 description: undefined, // --> description meta tag for each page

22 keywords: [], // --> a list of SEO keywords

23 themeColor: '#212121', // --> the browser bar color of your docs

24 appleMobileWebStatusBarStyle: // --> same as above, but for iOS Safari

25 'black-translucent'

26 },

27 fonts: { // --> font settings

28 text: { // --> font used for texts

29 url: // --> URL of font used for texts

30 'https://fonts.googleapis.com/css?family=Hind:400,700&display=swap',

31 name: 'Hind', // --> name of font used for texts

32 fallback: 'sans-serif' // --> the fallback font for texts

33 },

34 code: { // --> font used for codes

35 url: // --> URL of font used for codes

36 'https://fonts.googleapis.com/css?family=Source+Code+Pro:300,400&display=swap',

37 name: 'Source Code Pro', // --> name of the font used for codes

38 fallback: // --> fallback font for codes

39 `'Courier New', Courier, monospace`

40 },

41 icon: { // --> the icon font

42 url: // --> url of hte icon font (and perhaps the outline icon font)

43 'https://fonts.googleapis.com/icon?family=Material+Icons|Material+Icons+Outlined',

44 name: 'Material Icons', // --> name of the icon font

45 outline: // --> name of the outline icon font

46 'Material Icons Outlined'

47 }

48 },

49 scripts: [], // --> a list of script elements to be added to the head

50 stylesheets: [], // --> a list of stylesheet elements to be added to the head

51 post: [], // --> a list of functions for post-processing each generated HTML page

52 },

53 //...

54});

You can provide any of these properties. Properties not provided will fallback to values outline above:

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

2// ...

3

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

5 //...

6 page: {

7 title: {

8 base: 'My Project',

9 connector: ' > ',

10 },

11 favicon: '/favicon.ico',

12 meta: {

13 subject: 'An Awesome Project',

14 description: 'Pure awsomeness that helps you become awsome as well',

15 keywords: ['project', 'meine', 'awesome'],

16 },

17 },

18 //...

19});


linkPage Title

The title property determines the title of each page. It has three components:

So for example the following configuration:

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

2// ...

3

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

5 //...

6 page: {

7 title: {

8 base: 'My Project',

9 connector: ' > ',

10 extractor: (_, config, file) =>

11 [

12 config.page.title.base,

13 ...file.path.substr(0, file.path.length - 3) // --> remove the extension

14 .split('/') // --> split by slash

15 .map(_ => _[0].toUpperCase() + _.substr(1)) // --> camel case each part

16 ].join(config.page.title.connector) // --> join by the connector

17 },

18 //...

19 },

20 //...

21});

would create the following titles for these markdown files:

1my-project/docs/md/index.md -------------------> My Project > Index

2my-project/docs/md/whatever/stuff.md ----------> My Project > Whatever > Stuff

The default extractor function is guessTitle(), which will assume the content of the first heading of the markdown file as the title of the corresponding page. So for a page like this:

docs/md/whatever/stuff.md
1![banner](/banner.svg)

2

3# Whatevs!

4Hellow, and whatever.

the title would become My Project > Whatevs!.


linkMeta

You can configure the meta tags of each page via the meta property:

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

2// ...

3

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

5 //...

6 page: {

7 // ...

8 meta: {

9 subject: 'An Awesome Project',

10 description: 'Pure awsomeness that helps you become awsome as well',

11 keywords: ['project', 'meine', 'awesome'],

12 themeColor: '#212121', // @see [Google's docs](https://developers.google.com/web/updates/2014/11/Support-for-theme-color-in-Chrome-39-for-Android)

13 appleMobileWebStatusBarStyle: 'black-translucent' // @see [Apple's docs](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariHTMLRef/Articles/MetaTags.html)

14 },

15 // ...

16 },

17 //...

18});

It is highly recommended to set subject, description and keywords tags since these meta tags are pretty important for search engine indexing.

touch_app NOTICE

You can also provide page-specific meta information for subject, description and keywords properties using MetaOverride markdown component.

Learn More

linkFavicon

The favicon property names the URL of your doc's fav icon. For the default setup, it is recommended to keep this file in the root of your project, named favicon.ico, and setting the favicon to /favicon.ico:

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

2// ...

3

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

5 //...

6 page: {

7 // ...

8 favicon: '/favicon.ico',

9 // ...

10 },

11 //...

12});

Read More about Images and Assets

linkFonts

You can configure the fonts via fonts property:

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

2// ...

3

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

5 //...

6 page: {

7 //...

8 fonts: { // --> font settings

9 text: { // --> font used for texts

10 url: // --> URL of font used for texts

11 'https://fonts.googleapis.com/css?family=Hind:400,700&display=swap',

12 name: 'Hind', // --> name of font used for texts

13 fallback: 'sans-serif' // --> the fallback font for texts

14 },

15 code: { // --> font used for codes

16 url: // --> URL of font used for codes

17 'https://fonts.googleapis.com/css?family=Source+Code+Pro:300,400&display=swap',

18 name: 'Source Code Pro', // --> name of the font used for codes

19 fallback: // --> fallback font for codes

20 `'Courier New', Courier, monospace`

21 }

22 },

23 },

24 //...

25});

For example, changing the text font to Comic Neue would look like this:

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

2// ...

3

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

5 //...

6 page: {

7 //...

8 fonts: {

9 text: {

10 url:

11 'https://fonts.googleapis.com/css2?family=Comic+Neue:ital,wght@0,300;0,400;0,700;1,300;1,400;1,700&display=swap',

12 name: 'Comic Neue',

13 fallback: 'cursive'

14 },

15 },

16 },

17 //...

18});

Similarly, you could override the code property to change the font used for code snippets and in-line codes.


linkIcon Font

You can also modify the icon font using icon property:

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

2// ...

3

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

5 //...

6 page: {

7 //...

8 fonts: {

9 icon: {

10 url: '<URL to my icon font and optionally its outline version>',

11 name: '<Name of the icon font>',

12 outline: '<Name of the outline icon font>' // --> if not provided, this will default to `<name> Outlined`

13 },

14 },

15 },

16 //...

17});


warning CAUTION warning

When providing an icon font, you MUST ENSURE IT HAS THE GLYPHS THAT ARE USED BY CODEDOC BY DEFAULT. The following glyphs are used by codedoc:

If all these glyphs are not provided by the icon-font, then some features of CODEDOC will appear pretty broken (since the icon font will be missing). You can take a look at Material Icons to see how each of these icons should look. The safest approach would be to import all the SVGs from Material Icons into your icon font and override those who you want to.


linkScripts and Stylesheets

You can add custom script and stylesheets to each page via scripts and stylesheets properties. For example, imagine you want to add google analytics to your docs:

STEP 1
Rename .codedoc/config.ts to .codedoc/config.tsx so that we can easily create the necessary script elements using TSX.

STEP 2
Then, modify .codedoc/config.tsx like this:

.codedoc/config.tsx
1import { configuration } from '@codedoc/core';

2import { StaticRenderer } from '@connectv/sdh'; // --> import a static renderer for easily creating the script elements

3import register from 'jsdom-global'; // --> also lets create a global document object for that purpose

4

5const renderer = new StaticRenderer(); // --> initialize renderer

6register(); // --> register global document object

7

8// ...

9

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

11 //...

12 page: {

13 // ...

14 scripts: [

15 <script>{`

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

17 ga('create', 'UA-XXXXX-Y', 'auto');

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

19 `}</script>,

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

21 ]

22 },

23 //...

24});


touch_app NOTE

Note that members of scripts and stylesheets must be HTMLElements. This is why we used TSX, alongside the TSX renderer of CONNECTIVE SDH for creating them in the exmaple above.


linkPost Processing

You can conduct post-processing on generated HTMLs before they are saved to disk via post property. This property should be an array of post-processor functions, each of which will be applied to each HTML document before it is stored on the filesystem.

Each post-processor will be passed an HTMLDocument object as its first argument and a File object as its second argument, whose .path property is the path the HTML file is going to be stored on (relative to the base HTML output folder).

So for example the following configuration:

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

2// ...

3

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

5 //...

6 page: {

7 //...

8 post: [

9 (html, file) => {

10 html.body.setAttribute('data-path', file.path);

11 }

12 ]

13 },

14 //...

15});

Will set the path of the source markdown file on the data-path attribute of body.

Post processor functions are executed in the order provided, after CODEDOC itself has conducted its own post-processing (adding necessary script and stylesheet imports, fixing local links according to project namespace). They can be asynchronous functions, in which case each will block the queue until it is resolved.

Page ConfigurationPage TitleMetaFaviconFontsIcon FontScripts and StylesheetsPost Processing

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right