V2

Use this guide to migrate your project from Doks v1 to Doks v2.

Prerequisites#

• Hugo (latest extended or extended/deploy edition)
• Dart Sass (latest version)
• Node.js/npm (latest LTS version)

Updating#

Follow the steps below to update your project.

1. Remove currently installed dependencies to avoid version conflicts:

   npm run clean:install

   pnpm run clean:install

   yarn run clean:install

   bun run clean:install

2. Update package.json

   Replace the contents of your project’s package.json with the following template:

   {
     "name": "doks",
     "version": "0.0.0",
     "description": "Doks theme",
     "author": "Thulite",
     "license": "MIT",
     "scripts": {
       "create": "hugo new",
       "dev": "hugo server --disableFastRender --noHTTPCache",
       "portless": "portless run thulite-portless",
       "format": "prettier **/** -w -c",
       "build": "hugo --minify --gc",
       "preview": "vite preview --outDir public"
     },
     "engines": {
       "node": ">=20.11.0"
     }
   }

3. Install the latest Thulite and Doks dependencies in your project:

   npm install thulite@latest @thulite/doks-core@latest

   pnpm install thulite@latest @thulite/doks-core@latest

   yarn add thulite@latest @thulite/doks-core@latest

   bun add thulite@latest @thulite/doks-core@latest

4. Install the latest versions of Portless, Prettier, and Vite as devDependencies:

   npm install -D portless@latest prettier@latest vite@latest

   pnpm install -D portless@latest prettier@latest vite@latest

   yarn add -D portless@latest prettier@latest vite@latest

   bun add -d portless@latest prettier@latest vite@latest

5. Install the recommended integrations in your project:

   npm install @thulite/seo@latest @thulite/images@latest @thulite/inline-svg@latest

   pnpm install @thulite/seo@latest @thulite/images@latest @thulite/inline-svg@latest

   yarn add @thulite/seo@latest @thulite/images@latest @thulite/inline-svg@latest

   bun add @thulite/seo@latest @thulite/images@latest @thulite/inline-svg@latest

6. Add the following to layouts/_partials/head/dartsass.html:

   {{- /* Transpile SCSS with Dart Sass and silence legacy dependency warnings. */ -}}
   {{ with resources.Get . -}}
     {{ $opts := dict
       "enableSourceMap" hugo.IsDevelopment
       "outputStyle" (cond hugo.IsDevelopment "expanded" "compressed")
       "transpiler" "dartsass"
       "includePaths" (slice "node_modules")
       "silenceDeprecations" (slice "import" "if-function" "global-builtin" "color-functions")
       "silenceDependencyDeprecations" true
     -}}
     {{ with . | css.Sass $opts -}}
       {{ if hugo.IsDevelopment -}}
         <link rel="stylesheet" href="{{ .RelPermalink }}">
       {{ else -}}
         {{/* PostProcess defers PostCSS until hugo_stats.json is complete. */ -}}
         {{ with . | postCSS (dict "config" "config/postcss.config.js") | fingerprint | resources.PostProcess -}}
           <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
         {{ end -}}
       {{ end -}}
     {{ end -}}
   {{ end -}}

Configuration#

Review your project configuration for Doks, Thulite, and the recommended integrations:

• Doks
• Thulite
• SEO
• Images
• SVG

Known Issues#

ENOENT#

If you get an ENOENT error, run the following command:

npm run clean:install && npm install

pnpm run clean:install && pnpm install

yarn run clean:install && yarn install

bun run clean:install && bun install