Star

MIT License
Copyright © 2020
CONNECT-platform

linkEntry Files

Entry files are the markdown files that CODEDOC reads and transforms to HTML files. You can configure them via .codedoc/config.ts:

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

2// ...

3

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

5 //...

6 src: {

7 base: 'docs/md', // --> the base folder for all markdowns

8 not_found: '404.md', // --> markdown file for 404 page, relative to `base`

9 toc: '_toc.md', // --> markdown file for toc, relative to `base`

10 pick: /\.md$/, // --> which files to pick (default: .md files)

11 drop: /(^_)|(\/_)/, // --> which files to drop (default: _something.md files)

12 },

13 //...

14});

You can provide any of these properties. Not provided properties will fallback to values outlined above:

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

2// ...

3

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

5 //...

6 src: {

7 base: 'my-markdowns', // --> read markdowns from `my-markdowns` folder

8 drop: /(^\.)|(\/\.)/, // --> drop those who start with a dot

9 },

10 //...

11});


linkBase Folder

The base folder is where CODEDOC will search for your markdown files. If you have following files:

1my-project/docs/md/index.md

2my-project/docs/md/stuff/stuff.md

3my-project/docs/wrong-place.md

and the following config:

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

2// ...

3

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

5 //...

6 src: {

7 base: 'docs/md',

8 },

9 //...

10});

Then the following files will be processed by CODEDOC:

And my-project/docs/wrong-place.md will be ignored.

Overview of How Codedoc Works

linkToC File

The table of contents is read from a special markdown file. The address of this file is configured via toc field of entry files configuration:

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

2// ...

3

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

5 //...

6 src: {

7 base: 'docs/md',

8 toc: '_toc.md', // --> toc markdown is on `docs/md/_toc.md`

9 },

10 //...

11});

With this configuration, docs/md/_toc.md will be loaded and parsed for filling in the ToC.

touch_app NOTE

If you customize the address of the table of contents file, make sure to either name it to something that starts with _, or is located in a folder whose name starts with an _, or is skipped via your custom exclusion rule. Otherwise a stand-alone HTML file will be created for it as well.


linkIncluding and Excluding Files

pick and drop are regular expressions that determine which markdown files are to be included/excluded. CODEDOC will search the base folder, select files whose path (relative to base) matches pick regex, and from those exclude ones whose path (relative to base) matches drop regex. So the following config:

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

2// ...

3

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

5 //...

6 src: {

7 base: 'docs/md',

8 pick: /\.md$/,

9 drop: /(^_)|(\/_)/,

10 },

11 //...

12});

simply means


linkThe 404 Page

not_found specifies the markdown to be used for creating a 404 page. The same markdown rules will be applied to this page as with the rest of the markdown files, it is even processed just like another markdown file. This setting is used by the local dev server to serve it properly, and can be used by any CI/CD pipeline to serve the proper html when needed.

Note that you might need to configure your hosting provider to serve this file as well, and this is sometimes not possible. For example, github will simply serve 404.html, so the default config will work on GitHub Pages, but custom configs won't.

Entry FilesBase FolderToC FileIncluding and Excluding FilesThe 404 Page

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right