Star

MIT License
Copyright © 2020
CONNECT-platform

linkOutput Files

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

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

2// ...

3

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

5 //...

6 dest: {

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

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

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

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

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

12 },

13 //...

14});

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

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

2// ...

3

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

5 //...

6 dest: {

7 html: 'dist/html',

8 bundle: 'docs/codedoc',

9 styles: 'docs/codedoc',

10 },

11 //...

12});


linkHTML Files

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

1docs/md/index.md

2docs/md/whatever/stuff.md

with this configuration:

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

2// ...

3

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

5 //...

6 dest: {

7 html: 'dist/html',

8 },

9 //...

10});

Then CODEDOC will create the following HTML files:

1dist/html/index.html

2dist/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.ts
1import { configuration } from '@codedoc/core';

2// ...

3

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

5 //...

6 dest: {

7 namespace: '/my-project',

8 },

9 //...

10});

Then the following will happen:

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.ts
1import { configuration } from '@codedoc/core';

2

3// ...

4

5

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

7 // ...

8 dest: {

9 // ...

10 html: 'dist',

11 assets: 'dist',

12 },

13 // ...

14});


STEP 3: Add dist folder to .gitignore:

.gitignore
1# ...

2

3dist

4

5# ...

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.yml
1name: Deploy to GitHub Pages

2on:

3 push:

4 branches:

5 - master

6jobs:

7 build-and-deploy:

8 runs-on: ubuntu-latest

9 steps:

10 - name: Checkout

11 uses: actions/checkout@v2

12

13 - name: Build

14 run: |

15 # install .codedoc dependencies

16 (cd .codedoc && npm install)

17 # install codedoc

18 npm install @codedoc/cli

19 # build repo

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

21 - name: Deploy

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

23 with:

24 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

25 BRANCH: gh-pages

26 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.yml
1name: 'Deploy to Github Pages'

2on:

3 push:

4 branches:

5 master

6jobs:

7 build-and-deploy:

8 # ...

9 steps:

10 # ...

11

12 - name: Build

13 run: |

14 # install .codedoc dependencies

15 (cd .codedoc && npm install)

16 # install codedoc

17 npm install @codedoc/cli

18 # build repo

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

20 # copy assets

21 cp repo-banner.svg dist/

22 cp repo-banner-dark.svg dist/

23 cp favicon.ico dist/

24

25 # ...

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

1cp repo-banner.svg dist/

2cp repo-banner-dark.svg dist/

3cp 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 FilesHTML FilesAssetsProject NamespaceBuild Files on Git

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right