Star

linkAssets

If you want to host your own static assets (images, stylesheets, scripts, etc) and reference them in your blog posts, you need to tell coding.blog's build pipeline to pull them from your repo and put them alongside the rest of your content on the CDNs.

You can simply do that by providing a list of files/folders that should be pulled from the root of your blog's repo to the plugin function:

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

2import { codingBlog } from '@codedoc/coding-blog-plugin'; // --> import the plugin

3

4// ...

5

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

7 // ...

8 plugins: [

9 // ...

10 codingBlog({ // --> plug the plugin in

11 assets: [ // --> indicate your assets

12 'favicon.ico', // --> indicate your assets

13 'docs/img', // --> indicate your assets

14 ] // --> indicate your assets

15 })

16 ],

17 // ...

18});

You can subsequently link to your assets using /<path-to-asset-from-repo-root> format. For example, with the config setup above, you can set the fav icon of your blog like this:

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

2

3// ...

4

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

6 // ...

7 page: {

8 favicon: '/favicon.ico' // --> link to the favicon

9 // ...

10 }

11 // ...

12});

Or you can use the images in docs/img folder like this:

some-blog.md
1<!-- ... -->

2

3![Image Alt Text](/docs/img/something.png)

4

5<!-- ... -->


linkDev Setup

Since coding.blog fetches and routes to static files relative to the root of your repo, in order to keep your CODEDOC dev server in sync, you should also set the root of the assets that it would fetch to the root of the repo:

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

2import { codingBlog } from '@codedoc/coding-blog-plugin'; // --> import the plugin

3

4// ...

5

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

7 // ...

8 dest: {

9 assets: '.', // --> so the local dev-server fetches assets from the root folder of repo

10 // ...

11 },

12 // ...

13 plugins: [

14 // ...

15 codingBlog({ // --> plug the plugin in

16 assets: [ // --> indicate your assets

17 'favicon.ico', // --> indicate your assets

18 'docs/img', // --> indicate your assets

19 ] // --> indicate your assets

20 })

21 ],

22 // ...

23});

info NOTE

By default, you do not have to configure this as this is the default configuration of CODEDOC.


linkOther Hosting Providers

The assets config of this property is only designed to inform coding.blog's build pipeline on how to manage your assets. For other hosting providers, you would need to figure out how to configure their settings to properly serve your assets, and keep your local dev config in sync with that for dev convenience.

For example, GitHub Pages by default will also serve static files from the root of the repo. This is in sync with how coding.blog and CODEDOC's default work, so you wouldn't need any extra configuration to make your blog simultaenously publishable on coding.blog and GitHub Pages.

That said, it is sometimes useful to be able to have different configurations for different hosting environments at the same time. For example, in case of GitHub Pages, it is recommended practice to isolate build files into a git ignored folder such as dist and then use GitHub Actions to build using CODEDOC on each push and deploy contents of dist folder to root of gh-pages branch, as this would help keep generated files separate from the master branch which eases version control and collaboration (read this for more info on this setup).

The recommended solution for such a situation is using environment variables to mark build for different environments. In case of the aforementioned setup, you could for example configure CODEDOC and GitHub Actions like this to be able to publish to GitHub Pages and coding.blog at the same time:

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

2

3// ...

4

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

6 // ...

7 dest: {

8 namespace: '/<your-repo-name>', // --> in case you are not using a custom domain with your GitHub Pages

9 html: 'dist', // --> build everything to `dist`

10 assets: process.env.GITHUB_BUILD === 'true' ? 'dist' : '.', // --> build assets to `dist` if building for GitHub Pages

11 bundle: process.env.GITHUB_BUILD === 'true' ? 'bundle' : 'dist/bundle', // --> build assets to `dist` if building for GitHub Pages

12 styles: process.env.GITHUB_BUILD === 'true' ? 'styles' : 'dist/styles', // --> build assets to `dist` if building for GitHub Pages

13 // ...

14 },

15 // ...

16});

.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 # copy assets

22 cp favicon.ico dist/

23 ...

24 env: # --> set the environment variable

25 GITHUB_BUILD: true # --> set the environment variable

26

27 - name: Deploy

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

29 with:

30 GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

31 BRANCH: gh-pages

32 FOLDER: dist


Hero image by Mr Cup / Fabien Barral from Unsplash


AssetsDev SetupOther Hosting Providers

Home Hero Images Titles Author Info Article Cards Miscellaneous Assets