linkOutput Files

You can configure the output of CODEDOC via .codedoc/config.ts like this:

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

2link// ...

3link

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

5link  //...

6link  dest: {

7link    html: '.',                           // --> the base folder for HTML files

8link    assets: '.',                         // --> the base folder for assets

9link    bundle: 'docs/assets',               // --> where to store codedoc's bundle (relative to `assets`)

10link    styles: 'docs/assets',               // --> where to store codedoc's styles (relative to `assets`)

11link    namespace: '',                       // --> project namespace

12link  },

13link  //...

14link});

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

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

2link// ...

3link

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

5link  //...

6link  dest: {

7link    html: 'dist/html',

8link    bundle: 'docs/codedoc',

9link    styles: 'docs/codedoc',

10link  },

11link  //...

12link});

linkHTML Files

The html field determines where the HTML files will be output. If you have the following files:

1link$docs/md/index.md

2link$docs/md/whatever/stuff.md

with this configuration:

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

2link// ...

3link

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

5link  //...

6link  dest: {

7link    html: 'dist/html',

8link  },

9link  //...

10link});

Then CODEDOC will create the following HTML files:

1link$dist/html/index.html

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

warning WARNING
The default configuration for output 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.

linkAssets

assets determines where CODEDOC dev server should look for static files, and also where it will generate its own static files.

I would highly recommend only overriding bundle and styles properties for controlling where codedoc assets will be put in. bundle property controls where the client-side javascript required by codedoc will be put (relative to assets), and styles property controls where the CSS required by codedoc will be put (relative to assets). Only modify assets itself IF you have specific requirements by your hosting service.

Learn More about Assets

linkProject Namespace

It is possible that your project won't be hosted on the root URL of your domain. For example, your domain might be https://dude.cute.cloud, but your docs are served on https://dude.cute.cloud/my-project/. This is for example the case if you are using GitHub Pages without using a custom domain, where your docs would be served on https://<user>.github.io/<repo>.

The namespace property basically abstracts away this concern. It must be set to the URL prefix of your docs relative to the root URL of your domain, for example when your docs are served on https://dude.cute.cloud/my-project/, then your namespace must be set to /my-project, or in case of GitHub Pages (without a custom domain), your namespace must be set to /<repo> (the CLI will configure this automatically for you on initialization).

Imagine you have configured your project namespace like this:

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

2link// ...

3link

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

5link  //...

6link  dest: {

7link    namespace: '/my-project',

8link  },

9link  //...

10link});

Then the following will happen:

CODEDOC dev server will serve your static files on /my-project/, for example if you have an image named banner.svg in the root folder of your project, it will be served locally on /my-project/banner.svg
/my-project will be prepended to all anchors <a> whose URL (href) starts with /
/my-project will be prepended to all scripts <script> whose URL (src) starts with /
/my-project will be prepended to all links <link> whose URL (href) starts with /
/my-project will be prepended to all images <img> whose URL (src) starts with /

This simply means that the namespace will automatically be taken care of without you needing to modify your links, anchors, image sources, etc. For example, if you start with a GitHub Page without a custom domain, you simply set the namespace property to /<repo>, and then when you get a custom domain for your docs, update the namespace to '' (or remove it from config).

linkBuild Files on Git

For deploying to GitHub Pages, you would need the generated HTML, CSS, and Javascript files to also be put on your repository. This can be incovenient, since random stubs are used across these files which means they will be different everytime you change them, which can make it difficult to track changes to your markdown files.

One solution is to put build files on gh-pages branch and setup GitHub Pages to use that branch. A more complete solution, as proposed by Lukas Frost, is to put all build files in a folder that is ignored by git, and then use GitHub Actions to automatically push the contents of that folder to gh-pages.

To achieve this, do the following steps:

STEP 1: Configure GitHub Pages to gh-pages.

STEP 2: Configure codedoc to put its build files in dist folder, via .codedoc/config.ts:

.codedoc/config.ts1linkimport { configuration } from '@codedoc/core';

2link

3link// ...

4link

5link

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

7link  // ...

8link  dest: {

9link    // ...

10link    html: 'dist',

11link    assets: 'dist',

12link  },

13link  // ...

14link});

STEP 3: Add dist folder to .gitignore:

.gitignore1link$# ...

2link$

3link$dist

4link$

5link$# ...

If you use GitHub's default gitignore for Node, it includes this config.

STEP 4: Add GitHub Actions pipeline to .github/workflows/deploy-to-gh-pages.yml:

.github/workflows/deploy-to-gh-pages.yml1linkname: Deploy to GitHub Pages

2linkon:

3link  push:

4link    branches:

5link      - master

6linkjobs:

7link  build-and-deploy:

8link    runs-on: ubuntu-latest

9link    steps:

10link      - name: Checkout

11link        uses: actions/checkout@v2

12link

13link      - name: Build

14link        run: |

15link          # install .codedoc dependencies

16link          (cd .codedoc && npm install)

17link          # install codedoc

18link          npm install @codedoc/cli

19link          # build repo

20link          (PATH=$(npm bin):$PATH && codedoc build)

21link      - name: Deploy

22link        uses: JamesIves/github-pages-deploy-action@releases/v3

23link        with:

24link          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

25link          BRANCH: gh-pages

26link          FOLDER: dist

warning WARNING

If you are using images and figures in your docs, you should also configure your build pipeline to copy them to dist/ folder before pushing to gh-pages branch as well:

.github/workflows/deploy-to-gh-pages.yml1linkname: 'Deploy to Github Pages'

2linkon:

3link  push:

4link    branches:

5link      master

6linkjobs:

7link  build-and-deploy:

8link  # ...

9link  steps:

10link    # ...

11link

12link    - name: Build

13link      run: |

14link      # install .codedoc dependencies

15link      (cd .codedoc && npm install)

16link      # install codedoc

17link      npm install @codedoc/cli

18link      # build repo

19link      (PATH=$(npm bin):$PATH && codedoc build)

20link      # copy assets

21link      cp repo-banner.svg dist/

22link      cp repo-banner-dark.svg dist/

23link      cp favicon.ico dist/

24link

25link    # ...

Additionally, to have the assets available on your local testing as well, you should copy them to dist/ folder too:

1link$cp repo-banner.svg dist/

2link$cp repo-banner-dark.svg dist/

3link$cp favicon.ico dist/

You can also checkout this repository by LukasFrost or the repo of these docs for examples of how to do this setup.

Output Files HTML Files Assets Project Namespace Build Files on Git