linkImages and Assets

You probably have some images, scripts, stylesheets, etc. to serve alongside your docs and want to use them inside your docs. Though specifics of how they are served is actually up to your hosting provider (for example GitHub Pages), CODEDOC comes with some utilities to make referencing your assets in your docs easier.

By default, CODEDOC assumes that your assets are to be served from the root of your project. This helps you access any static file you might have in your repository, and also keeps the local dev server in sync with how GitHub Pages behaves. So if you have the following files:

1link$my-project/.codedoc/...

2link$my-project/docs/md/index.md

3link$my-project/docs/md/whatever/stuff.md

4link$my-project/banner.svg

5link$my-project/images/funny.png

You can use images in your docs like this:

docs/md/index.md
1link![Banner](/banner.svg)

2link![Funny Image](/images/banner.svg)

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>.

CODEDOC abstracts away this concern for you, so that you DO NOT NEED TO change your URLs based on your hosting environment. You need to simply configure .codedoc/config.ts accordingly:

.codedoc/config.ts
1link// ...

2linkexport const config = configuration({

3link  // ...

4link  dest: {

5link    // ...

6link    namespace: '/my-project',

7link  },

8link  // ...

9link});

And keep using the URLs as if you do not have a namespace:

docs/md/index.md
1link![Banner](/banner.svg)

2link![Funny Image](/images/banner.svg)

info UNDER THE HOOD

Codedoc basically automatically incorporates the project namespace into any link, image source, script source or anchor element whose URL starts with /.

Learn More

linkLocal Dev Server

By default, the codedoc dev server (i.e. codedoc serve) serves all your assets from the root folder of your project. It will automatically add the project namespace to the static URLs and require it when serving the files to fully emulate the behaviour described above.

linkCustom Setup

You can override the root folder of your assets via .codedoc/config.ts:

.codedoc/config.ts
1link// ...

2linkexport const config = configuration({

3link  // ...

4link  dest: {

5link    // ...

6link    assets: 'images',

7link  },

8link  // ...

9link});

With this configuration, the local dev server will now serve my-project/images/funny.png on /funny.png (or /my-project/funny.png, if you have a project namespace /my-project). Note that this DOES NOT AFFECT YOUR HOSTING PROVIDER, and you would need to modify your host configuration accordingly for the deployed version to work properly as well (configure it so that funny.png would be available on /funny.png when you do not have a namespace and /my-project/funny.png when you do).

warning ATTENTION warning

A custom setup as described above DOES NOT WORK on GitHub pages since there is no way to configure GitHub Pages to serve your static assets on a different URL. Only use this when you have a custom host that have specific configuration requirements.