Star

MIT License
Copyright © 2020
CONNECT-platform

linkOverview

A CODEDOC project consists of three main components:

Assume you have the following markdown files:

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

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

3link$docs/md/index.md

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

1link$codedoc build

And following HTML files will be generated:

1link$some-folder/overview.html

2link$some-folder/spec.html

3link$index.html

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

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

2link

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

4link

5link

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

7link theme,

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

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

10link },

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

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

13link },

14link page: {

15link title: {

16link base: 'My Project'

17link },

18link },

19link});

With this configuration, the following list of markdown files:

1link$src/markdowns/whatever/stuff.md

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

3link$src/markdowns/index.md

would be transformed to following HTML files:

1link$dist/html/whatever/stuff.html

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

3link$dist/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
1linkexport const config = /*#__PURE__*/configuration({

2link // ...

3link src: {

4link base: 'src/markdowns'

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

6link },

7link // ...

8link});


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
1linkexport const config = /*#__PURE__*/configuration({

2link // ...

3link src: {

4link base: 'src/markdowns'

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

6link },

7link // ...

8link});


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
1link[Home](/)

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

3link[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
1link[Home](/)

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

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

4link

5link---

6link

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

8linkif you enjoy using it!

9link

10link> :Buttons

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

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

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

2link

3link> :Collapse label=Stuff

4link>

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

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

Or use Collapse in a nested manner:

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

2link

3link> :Collapse label=Stuff

4link>

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

6link> > :Collapse label=Spec

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

8link> > [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
1link

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

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

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

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

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

7linkmollit anim id est laborum.

8link

9link > :ToCPrevNext


linkHeader

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

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

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

3link

4link

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

6link return (

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

8link <fragment>

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

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

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

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

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

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

15link <br/><br/>

16link </fragment>

17link : ''}

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

19link </_Header>

20link )

21link}

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
1linkimport { CodedocConfig } from '@codedoc/core';

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

3link

4link

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

6link let github$;

7link if (config.misc?.github)

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

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

10link

11link let community$;

12link if (config.misc?.gitter)

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

14link

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

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

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

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

19link}

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
1linkimport { CodedocConfig } from '@codedoc/core';

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

3link

4link

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

6link return <_Footer>

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

8link <hr/>

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

10link <hr/>

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

12link </_Footer>;

13link}


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