linkPage Configuration

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

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

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

3link// ...

4link

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

6link  //...

7link  page: {

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

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

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

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

12link        guessTitle(

13link          content, 

14link          config.page.title.base, 

15link          config.page.title.connector

16link        ),

17link    },

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

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

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

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

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

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

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

25link        'black-translucent'

26link    },

27link    fonts: {                             // --> font settings

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

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

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

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

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

33link      },

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

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

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

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

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

39link          `'Courier New', Courier, monospace`

40link      },

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

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

43link          'https://fonts.googleapis.com/icon?family=Material+Icons%7CMaterial+Icons+Outlined',

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

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

46link          'Material Icons Outlined'

47link      }

48link    },

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

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

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

52link  },

53link  //...

54link});

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

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

2link// ...

3link

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

5link  //...

6link  page: {

7link    title: {

8link      base: 'My Project',

9link      connector: ' > ',

10link    },

11link    favicon: '/favicon.ico',

12link    meta: {

13link      subject: 'An Awesome Project',

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

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

16link    },

17link  },

18link  //...

19link});

linkPage Title

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

Base
Denoted by base property, is the base title for all of your docs, e.g. "My Project"
Connector
Denoted by connector property, is used to connect the base to page-specific part of the title. For example, if you have titles like My Project > Stuff, then " > " is your connector
Extractor
Denoted by extractor property, is a function that determines the final page-specific title, based on the HTML content, codedoc configuration and the markdown file.

So for example the following configuration:

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

2link// ...

3link

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

5link  //...

6link  page: {

7link    title: {

8link      base: 'My Project',

9link      connector: ' > ',

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

11link        [

12link          config.page.title.base,

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

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

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

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

17link    },

18link    //...

19link  },

20link  //...

21link});

would create the following titles for these markdown files:

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

2linkmy-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.md1link![banner](/banner.svg)

2link

3link# Whatevs!

4linkHellow, 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.ts1linkimport { configuration } from '@codedoc/core';

2link// ...

3link

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

5link  //...

6link  page: {

7link    // ...

8link    meta: {

9link      subject: 'An Awesome Project',

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

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

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

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

14link    },

15link    // ...

16link  },

17link  //...

18link});

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

2link// ...

3link

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

5link  //...

6link  page: {

7link    // ...

8link    favicon: '/favicon.ico',

9link    // ...

10link  },

11link  //...

12link});

linkFonts

You can configure the fonts via fonts property:

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

2link// ...

3link

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

5link  //...

6link  page: {

7link    //...

8link    fonts: {                             // --> font settings

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

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

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

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

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

14link      },

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

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

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

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

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

20link          `'Courier New', Courier, monospace`

21link      }

22link    },

23link  },

24link  //...

25link});

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

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

2link// ...

3link

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

5link  //...

6link  page: {

7link    //...

8link    fonts: {

9link      text: {

10link        url:

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

12link        name: 'Comic Neue',

13link        fallback: 'cursive'

14link      },

15link    },

16link  },

17link  //...

18link});

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

2link// ...

3link

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

5link  //...

6link  page: {

7link    //...

8link    fonts: {

9link      icon: {

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

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

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

13link      },

14link    },

15link  },

16link  //...

17link});

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:
wb_incandescent
touch_app
chevron_right
chevron_left
link
open_in_new
close
arrow_back_ios
arrow_forward_ios
search
list
filter_none
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.tsx1linkimport { configuration } from '@codedoc/core';

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

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

4link

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

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

7link

8link// ...

9link

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

11link  //...

12link  page: {

13link    // ...

14link    scripts: [

15link      <script>{`

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

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

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

19link      `}</script>,

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

21link    ]

22link  },

23link  //...

24link});

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

2link// ...

3link

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

5link  //...

6link  page: {

7link    //...

8link    post: [

9link      (html, file) => {

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

11link      }

12link    ]

13link  },

14link  //...

15link});

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 Configuration Page Title Meta Favicon Fonts Icon Font Scripts and Stylesheets Post Processing