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:
1linkimport { configuration } from '@codedoc/core';
2linkimport { codingBlog } from '@codedoc/coding-blog-plugin'; // --> import the plugin
3link
4link// ...
5link
6linkexport const config = /*#__PURE__*/configuration({
7link // ...
8link plugins: [
9link // ...
10link codingBlog({ // --> plug the plugin in
11link assets: [ // --> indicate your assets
12link 'favicon.ico', // --> indicate your assets
13link 'docs/img', // --> indicate your assets
14link ] // --> indicate your assets
15link })
16link ],
17link // ...
18link});
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:
1linkimport { configuration } from '@codedoc/core';
2link
3link// ...
4link
5linkexport const config = /*#__PURE__*/configuration({
6link // ...
7link page: {
8link favicon: '/favicon.ico' // --> link to the favicon
9link // ...
10link }
11link // ...
12link});
Or you can use the images in docs/img folder like this:
1link<!-- ... -->
2link
3link
4link
5link<!-- ... -->
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:
1linkimport { configuration } from '@codedoc/core';
2linkimport { codingBlog } from '@codedoc/coding-blog-plugin'; // --> import the plugin
3link
4link// ...
5link
6linkexport const config = /*#__PURE__*/configuration({
7link // ...
8link dest: {
9link assets: '.', // --> so the local dev-server fetches assets from the root folder of repo
10link // ...
11link },
12link // ...
13link plugins: [
14link // ...
15link codingBlog({ // --> plug the plugin in
16link assets: [ // --> indicate your assets
17link 'favicon.ico', // --> indicate your assets
18link 'docs/img', // --> indicate your assets
19link ] // --> indicate your assets
20link })
21link ],
22link // ...
23link});
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:
1linkimport { configuration } from '@codedoc/core';
2link
3link// ...
4link
5linkexport const config = /*#__PURE__*/configuration({
6link // ...
7link dest: {
8link namespace: '/<your-repo-name>', // --> in case you are not using a custom domain with your GitHub Pages
9link html: 'dist', // --> build everything to `dist`
10link assets: process.env.GITHUB_BUILD === 'true' ? 'dist' : '.', // --> build assets to `dist` if building for GitHub Pages
11link bundle: process.env.GITHUB_BUILD === 'true' ? 'bundle' : 'dist/bundle', // --> build assets to `dist` if building for GitHub Pages
12link styles: process.env.GITHUB_BUILD === 'true' ? 'styles' : 'dist/styles', // --> build assets to `dist` if building for GitHub Pages
13link // ...
14link },
15link // ...
16link});
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 # copy assets
22link cp favicon.ico dist/
23link ...
24link env: # --> set the environment variable
25link GITHUB_BUILD: true # --> set the environment variable
26link
27link - name: Deploy
28link uses: JamesIves/github-pages-deploy-action@releases/v3
29link with:
30link GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
31link BRANCH: gh-pages
32link FOLDER: dist
Hero image by Mr Cup / Fabien Barral from Unsplash