CONNECT-platform

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:

1linkdocs/md/some-folder/overview.md2linkdocs/md/some-folder/spec.md3linkdocs/md/index.md

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

1linkcodedoc build

And following HTML files will be generated:

1linksome-folder/overview.html2linksome-folder/spec.html3linkindex.html

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

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';2link3linkimport { theme } from './theme';4link5link6linkexport const config = /*#__PURE__*/configuration({7link  theme,8link  src: {                       // --> configure source files9link    base: 'src/markdowns'      // --> base the source to src/markdowns10link  },11link  dest: {                      // --> configure destination files12link    html: 'dist/html'          // --> base the destination of htmls to dist/html13link  },14link  page: {15link    title: {16link      base: 'My Project'17link    },18link  },19link});

With this configuration, the following list of markdown files:

1linksrc/markdowns/whatever/stuff.md2linksrc/markdowns/whatever/other-stuff.md3linksrc/markdowns/index.md

would be transformed to following HTML files:

1linkdist/html/whatever/stuff.html2linkdist/html/whatever/other-stuff.html3linkdist/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.

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});

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.md6link  },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)4link5link---6link7linkThis project relies on donations for maintenance and stuff. Help us out8linkif you enjoy using it!9link10link> :Buttons11link> > :Button label=DONATE, url=opencollective.com/johndoe

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

docs/_toc.md1link[Home](/)2link3link> :Collapse label=Stuff4link>5link> [Overview](/some-folder/overview)6link> [Spec](/some-folder/spec)

Or use Collapse in a nested manner:

docs/_toc.md1link[Home](/)2link3link> :Collapse label=Stuff4link>5link> [Overview](/some-folder/overview)6link> > :Collapse label=Spec7link> > [Spec Overview](/some-folder/spec/overview)8link> > [Spec of This](/some-folder/spec/this)

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.md1link2linkLorem 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.8link9link > :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';3link4link5linkexport 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';3link4link5linkexport 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 footer10link11link let community$;12link  if (config.misc?.gitter)13link    community$= <GitterToggle$ room={config.misc.gitter.room}/>     // --> if gitter is configured, add its integration14link15link  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';3link4link5linkexport 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}

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.

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right