linkOverview

A CODEDOC project consists of three main components:

Some markdown files, which codedoc will search through and transform into HTML files. Codedoc expects to find these source or input or entry files by default in docs/md, though you can reconfigure that.
The resulting HTML files, alongside the bundle and styles required by those HTML files. Codedoc creates a stand-alone HTML file for each of your entry markdown files (except those who are exempt by exclusion rules) and puts them in some destination folder, which is by default the root folder of your project, maintaining their relative paths to each other. You can reconfigure this destination folder as well.
Codedoc configruations, scripts and components. These are ALWAYS located in .codedoc/ folder of your project.

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.ts1linkimport { 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.ts1linkexport 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.ts1linkexport 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.md1link[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.md1link[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.md1link[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.md1link[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.md1link

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

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

.codedoc/content/header.tsx1linkimport { 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.

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

.codedoc/content/footer.tsx1linkimport { 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.tsx1linkimport { 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

Overview Exclusions Table of Contents Header Footer Collaboration

linkOverview

linkExclusions

linkTable of Contents

linkHeader

linkFooter

linkCollaboration