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
1linkimport { 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.ts
1linkimport { 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.ts
1linkimport { 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.ts
1linkimport { 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:

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
1linkimport { 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:

.gitignore
1link$# ...

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.yml
1linkname: 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.yml
1linkname: '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 FilesHTML FilesAssetsProject NamespaceBuild Files on Git

Home Overview CLI Theme

Markdownchevron_right
Code Featureschevron_right

Images & Assets

Configurationchevron_right
Customizationchevron_right