Codeholics

Static site source for codeholics.com, built with Pelican.

• Content lives in content/.
• The generated site is written to output/.
• The active theme is themes/pelican-bootstrap-5/.
• Pelican plugins are expected in a sibling checkout at ../pelican-plugins.
• Local Python dependencies are managed with pyproject.toml and uv.lock.

Clone both repositories side by side:

git clone git@github.com:Codeholics/codeholics.git
git clone git@github.com:Codeholics/pelican-plugins.git

The resulting layout should look like this:

parent-directory/
├── codeholics/
└── pelican-plugins/

Install dependencies with Astral uv:

cd codeholics
uv venv
uv sync

If you do not want to use uv, install the project dependencies with your preferred Python environment manager using the packages declared in pyproject.toml.

Build the site:

uv run pelican -s pelicanconf.py

Serve the generated output locally:

uv run pelican --listen -s pelicanconf.py

Pelican serves the site at http://127.0.0.1:8000/ by default.

Watch and rebuild automatically while editing:

uv run pelican -r -s pelicanconf.py

Clean rebuild:

uv run pelican -d -s pelicanconf.py

Most day-to-day edits are in content/. After changing markdown or images:

uv run pelican -s pelicanconf.py

Use the production config before deploy-related changes:

uv run pelican -s publishconf.py

publishconf.py imports pelicanconf.py and applies production overrides such as RELATIVE_URLS = False and DELETE_OUTPUT_DIRECTORY = True.

The theme has separate frontend tooling under themes/pelican-bootstrap-5/frontend-tools.

Install Node dependencies:

cd themes/pelican-bootstrap-5/frontend-tools
npm install

Run the default asset pipeline:

npx gulp

Useful individual tasks:

npx gulp scssTask
npx gulp deliverCssTask
npx gulp jsMinifyTask
npx gulp deliverJsTask
npx gulp cleanTask

The default Gulp task copies built assets into the theme's static/assets directories and tries to trigger a Pelican rebuild via ../../../build.sh. If that script is not present, go back to the repo root and rebuild manually:

cd /path/to/codeholics
uv run pelican -s pelicanconf.py

codeholics/
├── content/                         # Markdown content and images
├── output/                          # Generated site output
├── themes/
│   └── pelican-bootstrap-5/        # Active theme
│       └── frontend-tools/         # Node/Gulp asset pipeline
├── pelicanconf.py                  # Main development config
├── publishconf.py                  # Production overrides
├── pyproject.toml                  # Python dependencies
└── uv.lock                         # Locked Python dependencies

Local development commands:

uv run pelican -s pelicanconf.py
uv run pelican -d -s pelicanconf.py
uv run pelican -r -s pelicanconf.py
uv run pelican --listen -s pelicanconf.py
uv run pelican -s publishconf.py

Docker workflow:

docker-compose -f docker/docker-compose.yml build
docker-compose -f docker/docker-compose.yml up

Tests and linting:

• No automated test suite is configured right now.
• No linter is configured right now.

GitHub Actions workflows live in .github/workflows/.

• build.yml builds on pushes to dev.
• deploy.yml runs the shared build workflow, rebuilds the site, and copies output/* to the server with appleboy/scp-action.
• Both workflows check out this repo and Codeholics/pelican-plugins.

Example manual deploy command:

scp -r output/* user@production-host:/var/www/codeholics/

Current CI note:

• Workflow files use actions/setup-python, astral-sh/setup-uv, uv sync, and uv run pelican ....

tasks.py contains Invoke tasks that wrap common Pelican commands, but the primary documented workflow for this project is to run Pelican directly.

• Pelican: https://getpelican.com/
• Astral uv: https://docs.astral.sh/uv/

This repository also contains a migrated Astro site in the astro/ subdirectory. Use the Astro workflow when developing the modern, Tailwind-powered site.

Recommended Node: see astro/package.json (engines). Example (nvm):

nvm use 22

Quick start (inside repo root):

cd astro
npm install
npm run dev      # start local dev server (hot reload)

To set the canonical site URL used during builds, pass SITE_URL. When unset, builds keep the production default:

cd astro
SITE_URL=https://dev.codeholics.com npm run build

To make the Astro dev server emit generated asset URLs from a different origin, set ASSET_URL:

cd astro
ASSET_URL=https://cdn-dev.codeholics.test npm run dev

Notes:

• SITE_URL controls canonical build output such as RSS absolute links and defaults to https://www.codeholics.com.
• ASSET_URL changes the origin Astro uses for dev-served assets, and the current layout also applies it to favicon URLs from public/.
• Other hand-authored root-relative paths from public/ or templates still need to opt into the same helper if you move them behind that origin.
• Production builds still use the default local asset paths.

The Astro markdown pipeline normalizes fenced-code language labels before highlighting. This keeps legacy posts working without mass content edits.

• Canonical language IDs currently supported by project config: bash, c, cpp, cs, css, diff, dockerfile, go, html, ini, java, javascript, json, lua, make, markdown, plaintext, python, rust, scss, sql, text, toml, typescript, xml, yaml.
• Alias mappings convert common variants (for example Python/py/python3 -> python, HTML/html5 -> html, Shell/sh/zsh -> bash, ts/tsx -> typescript, yml -> yaml).
• Unknown language labels fall back to text so blocks still render safely.
• Unknown labels emit warnings during local and CI builds to make missing mappings visible.

Inline-code delimiter quality now follows a phased policy:

• Transition (warning mode): malformed inline-code delimiters are reported but do not fail builds.
• Steady state (blocking mode): malformed inline-code delimiters fail lint/build gates.
• During transition, deterministic legacy patterns (for example a dangling trailing backtick after a closed inline span) are normalized at render time and logged.
• Ambiguous malformed patterns are never auto-corrected; they are diagnosed for manual markdown fixes.

Lint commands:

cd astro
npm run lint:inline-code          # warning mode (default)
npm run lint:inline-code:strict   # blocking mode

Build commands:

cd astro
npm run build                     # includes warning-mode inline-code lint
npm run build:inline-code-strict  # fails on malformed inline delimiters

Promotion threshold from warning to blocking:

• Promote CI/default build checks to blocking mode when npm run lint:inline-code reports zero findings in two consecutive default-branch CI runs and known legacy findings have been remediated.

If you need a new language:

1. Add the canonical language ID to astro/src/lib/markdown-code.mjs.
2. Add any desired aliases in the same file.
3. Rebuild Astro (cd astro && npm run build) and verify the resulting post output.

Build and preview the static site:

cd astro
npm run build
npm run preview  # serves the built output

Run Playwright end-to-end tests (includes navbar/link checks):

cd astro
npm run test:e2e

Run the targeted canonical URL build checks:

cd astro
npm run test:site-url

Notes:

• npm run build generates a production-ready static site with Astro.
• If you want CI integration, run npm ci && npm run build && npm run test:e2e in the astro/ folder.