Star

MIT License
Copyright © 2020
CONNECT-platform

linkOverview

A CODEDOC project consists of three main components:

Assume you have the following markdown files:

1docs/md/some-folder/overview.md

2docs/md/some-folder/spec.md

3docs/md/index.md

Then, in order to build them, you need to run

1codedoc build

And following HTML files will be generated:

1some-folder/overview.html

2some-folder/spec.html

3index.html

You can change the default source and destination folders by modifying .codedoc/config.ts:

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

2

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

4

5

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

7 theme,

8 src: { // --> configure source files

9 base: 'src/markdowns' // --> base the source to `src/markdowns`

10 },

11 dest: { // --> configure destination files

12 html: 'dist/html' // --> base the destination of htmls to `dist/html`

13 },

14 page: {

15 title: {

16 base: 'My Project'

17 },

18 },

19});

With this configuration, the following list of markdown files:

1src/markdowns/whatever/stuff.md

2src/markdowns/whatever/other-stuff.md

3src/markdowns/index.md

would be transformed to following HTML files:

1dist/html/whatever/stuff.html

2dist/html/whatever/other-stuff.html

3dist/html/index.html


warning WARNING

The default configuration for destination files is optimized for publishing to GitHub Pages. If you do intend to publish to GitHub Pages, modify them only if you know what you are doing.

linkExclusions

By default, markdown files whose name starts with _ or are located in a folder starting with _ will be excluded from transformation. This feature is useful for having markdown files that are to be somehow incorporated in other docs instead of being transformed into stand-alone HTML files.

You can override this config via .codedoc/config.ts as well:

.codedoc/config.ts
1export const config = /*#__PURE__*/configuration({

2 // ...

3 src: {

4 base: 'src/markdowns'

5 drop: /(^\.)|(\/\.)/ // --> exclude files and folders whose name starts with a `.`

6 },

7 // ...

8});


linkTable of Contents

The table of contents, which is accessible via the menu icon on the footer by default, is also read from a markdown file. This special markdown file is by default located on docs/md/_toc.md, though you can change that in .codedoc/config.ts as well:

.codedoc/config.ts
1export const config = /*#__PURE__*/configuration({

2 // ...

3 src: {

4 base: 'src/markdowns'

5 toc: 'stuff/_le_table.md' // --> now ToC is read from `src/markdowns/stuff/_le_table.md`

6 },

7 // ...

8});


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.


The contents of a ToC markdown file typically looks something like this:

docs/_toc.md
1[Home](/)

2[Overview](/some-folder/overview)

3[Spec](/some-folder/spec)

As you can see, for linking to other documents, you simply need to use their path relative to the base source folder as an absolute URL. This is not exclusive to the table of contents either, so you can link to any document from any document via the same rule.

Though links are styled a bit differently in the table of contens, you can still add your own custom content (for example add some text and a button for donations):

docs/_toc.md
1[Home](/)

2[Stuff](/some-folder/overview)

3[Other Stuff](/some-folder/spec)

4

5---

6

7This project relies on donations for maintenance and stuff. Help us out

8if you enjoy using it!

9

10> :Buttons

11> > :Button label=DONATE, url=opencollective.com/johndoe

You can also use the Collapse component for organizing long tables of contents:

docs/_toc.md
1[Home](/)

2

3> :Collapse label=Stuff

4>

5> [Overview](/some-folder/overview)

6> [Spec](/some-folder/spec)

Or use Collapse in a nested manner:

docs/_toc.md
1[Home](/)

2

3> :Collapse label=Stuff

4>

5> [Overview](/some-folder/overview)

6> > :Collapse label=Spec

7> > [Spec Overview](/some-folder/spec/overview)

8> > [Spec of This](/some-folder/spec/this)


Read More about Collapse

If you want to have the nice Previous and Next buttons in a page automatically deduced using the ToC, you need to use the ToCPrevNext component:

docs/md/some-folder/overview.md
1

2Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor

3incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud

4exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute

5irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur.

6Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt

7mollit anim id est laborum.

8

9 > :ToCPrevNext


linkHeader

The header of each page is generated using a TSX-based component located in .codedoc/content/header.tsx:

.codedoc/content/header.tsx
1import { CodedocConfig } from '@codedoc/core';

2import { Header as _Header, GithubButton, Watermark } from '@codedoc/core/components';

3

4

5export function Header(config: CodedocConfig, renderer: any) {

6 return (

7 <_Header>{config.misc?.github ?

8 <fragment>

9 <GithubButton action={config.misc.github.action || 'Star'} {/* --> show a github button in the header if github is configured.*/}

10 repo={config.misc.github.repo}

11 user={config.misc.github.user}

12 large={config.misc.github.large === true}

13 count={config.misc.github.count !== false}

14 standardIcon={config.misc.github.standardIcon !== false}/>

15 <br/><br/>

16 </fragment>

17 : ''}

18 <Watermark/> {/* --> show the CODEDOC watermark. */ }

19 </_Header>

20 )

21}

So for example by commenting out the highlighted line, you can take out the CODEDOC watermark.

These TSX-based components are in fact CONNECTIVE SDH components, so checkout those docs if you want to confidently further customize them.


linkFooter

Similar to the header, the footer is a TSX-based component (a CONNECTIVE SDH component) located in .codedoc/content/footer.tsx:

.codedoc/content/footer.tsx
1import { CodedocConfig } from '@codedoc/core';

2import { Footer as _Footer, GitterToggle$, Watermark} from '@codedoc/core/components';

3

4

5export function Footer(config: CodedocConfig, renderer: any) {

6 let github$;

7 if (config.misc?.github)

8 github$ = <a href={`https://github.com/${config.misc.github.user}/${config.misc.github.repo}/`}

9 target="_blank">GitHub</a>; // --> if github is configured, show a link to the repo in footer

10

11 let community$;

12 if (config.misc?.gitter)

13 community$ = <GitterToggle$ room={config.misc.gitter.room}/> // --> if gitter is configured, add its integration

14

15 if (github$ && community$) return <_Footer>{github$}<hr/>{community$}</_Footer>;

16 else if (github$) return <_Footer>{github$}</_Footer>;

17 else if (community$) return <_Footer>{community$}</_Footer>;

18 else return <_Footer><Watermark/></_Footer>; // --> if neither github nor gitter are configured, show the watermark.

19}

So for example we could just change the content of the footer to a link to our repo's GitHub page, a link to its NPM package, and a link to its twitter page:

.codedoc/content/footer.tsx
1import { CodedocConfig } from '@codedoc/core';

2import { Footer as _Footer } from '@codedoc/core/components';

3

4

5export function Footer(_: any, renderer: any) {

6 return <_Footer>

7 <a href="https://github.com/CONNECT-platform/codedoc">GitHub</a> {/* --> link to github*/}

8 <hr/>

9 <a href="https://www.npmjs.com/package/@codedoc/core">NPM</a> {/* --> link to NPM*/}

10 <hr/>

11 <a href="https://twitter.com/CONNECT_pltfrm">Twitter</a> {/* --> link to twitter*/}

12 </_Footer>;

13}


linkCollaboration

If you want to work on a CODEDOC project collaboratively, i.e. you want to work with other people on the markdown files / codedoc configs., it is recommended to not submit changes in build files (the generated HTML files) to the repo, and instead only submit changes to markdown files / codedoc configs, then build the files per merge and push the changes subsequently.

In situations where the build files need to be present on repo, for example when deploying to GitHub Pages, this can be challenging, since you would need to manually remove build files from each commit.

However, you can simply isolate the build files to an ignored folder and then create a branch that only contains the contents of that folder. For example, you can put all of your build files in dist/ folder (which is ignored by git), have your gh-pages branch only contain contents of dist/ folder, and configure your GitHub Pages to use the gh-pages branch of your repo. You can even automate this process using GitHub Actions, so that you don't need to manually build and push after each iteration.

See How In Detail
OverviewExclusionsTable of ContentsHeaderFooterCollaboration

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right