|
| 1 | +# CLAUDE.md |
| 2 | + |
| 3 | +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. |
| 4 | + |
| 5 | +## Commands |
| 6 | + |
| 7 | +```bash |
| 8 | +# Build the production site |
| 9 | +npm run build |
| 10 | + |
| 11 | +# Serve locally with live reload (default) |
| 12 | +npm run serve |
| 13 | + |
| 14 | +# Serve with tracing output |
| 15 | +npm run default |
| 16 | + |
| 17 | +# Serve docs/demo site (dev, beta, production variants) |
| 18 | +npm run dev # docs/_config.dev.yml |
| 19 | +npm run demo-dev # docs/_config.yml (dev env) |
| 20 | +npm run demo-prod # docs/_config.yml (production env) |
| 21 | + |
| 22 | +# Lint JS in _includes/**/*.js |
| 23 | +npm run eslint |
| 24 | +npm run eslint-fix |
| 25 | + |
| 26 | +# Lint SCSS in _sass/**/*.scss |
| 27 | +npm run stylelint |
| 28 | +npm run stylelint-fix |
| 29 | + |
| 30 | +# Build & publish gem (release flow only) |
| 31 | +npm run gem-build |
| 32 | +npm run gem-push |
| 33 | + |
| 34 | +# Docker-based development |
| 35 | +npm run docker-dev:default |
| 36 | +npm run docker-dev:dev |
| 37 | +npm run docker-dev:demo-dev |
| 38 | + |
| 39 | +# Docker production build + serve |
| 40 | +npm run docker-prod:build |
| 41 | +npm run docker-prod:serve |
| 42 | +``` |
| 43 | + |
| 44 | +**CI**: Travis builds the docs site via `JEKYLL_ENV=production bundle exec jekyll build --config ./docs/_config.yml` and deploys to `gh-pages` branch. |
| 45 | + |
| 46 | +**Commit style**: Conventional Commits via commitlint (`feat:`, `fix:`, `docs:`, `refactor:`, `release:`, etc.). |
| 47 | + |
| 48 | +## Project Architecture |
| 49 | + |
| 50 | +### Skin System |
| 51 | +6 built-in skins (`default`, `dark`, `forest`, `ocean`, `chocolate`, `orange`) + 5 highlight themes. A skin is a SCSS file at `_sass/skins/_<name>.scss` that defines CSS custom properties (colors, fonts, borders). Selected via `text_skin` in `_config.yml`. The main entry point `assets/css/main.scss` dynamically `@import`s the active skin. |
| 52 | + |
| 53 | +### Layout Inheritance |
| 54 | +Layouts in `_layouts/` form a chain: `none` ← `base` ← `page` ← `article` / `home` / `landing` / `articles` / `archive` / `404`. `base.html` is the root — it sets up the HTML shell, analytics, head, and core JS utilities. Page-level layouts extend it and add content wrappers. |
| 55 | + |
| 56 | +### Include System |
| 57 | +`_includes/` is organized by concern: |
| 58 | +- **article/** — header, footer, info, list components |
| 59 | +- **aside/** — sidebar content (TOC, affix) |
| 60 | +- **scripts/** — vanilla JS (no framework): lib/ (third-party), utils/, components/ (search, lightbox, sidebar) |
| 61 | +- **head/**, **footer/**, **sidebar/** — structural includes |
| 62 | +- **comments-providers/**, **analytics-providers/**, **search-providers/**, **sharing-providers/**, **pageview-providers/** — pluggable third-party integrations |
| 63 | + |
| 64 | +### JavaScript Architecture |
| 65 | +Vanilla JS (no build step, no framework). Scripts are included directly via Liquid `{%- include scripts/...js -%}` in `base.html`. The JS is split into: |
| 66 | +- **lib/** — isolated utilities (lazyload, throttle, affix, TOC, swiper, modal, gallery, scroll-to) |
| 67 | +- **components/** — stateful UI (search, lightbox, sidebar) |
| 68 | +- **utils/** — helpers (image loading, general utils) |
| 69 | +- Page-level scripts: `article.js`, `page.js`, `home.js`, `archieve.js` |
| 70 | + |
| 71 | +No bundler — all JS is served raw from `_includes/scripts/`. |
| 72 | + |
| 73 | +### SCSS Organization |
| 74 | +`_sass/` is structured as: |
| 75 | +- **skins/** — color/font themes (each skin is a standalone variable file) |
| 76 | +- **common/** — shared variables, functions, classes, reset, print styles, reusable components (button, card, modal, gallery, etc.) |
| 77 | +- **components/** — page-level component styles (header, footer, search, lightbox, etc.) |
| 78 | +- **layout/** — page layout styles (base, page, article, home, archive, etc.) |
| 79 | +- **additional/** — optional utility styles (alerts, tags, photo frames) |
| 80 | +- **animate/** — keyframe animations (fade-in variants) |
| 81 | +- **custom.scss** — user overrides placeholder |
| 82 | + |
| 83 | +### Content & Data |
| 84 | +- `_data/` — YAML files for authors, licenses, locale (i18n), navigation, and theme variables |
| 85 | +- `_posts/` — sample/blog posts directory |
| 86 | +- `docs/` — standalone documentation site (has its own `_config.yml`, posts, sample pages, and shared `_includes` from root via Travis `before_script`) |
| 87 | +- `test/` — minimal test site (used for smoke testing the theme) |
| 88 | + |
| 89 | +### Building a Release |
| 90 | +1. Update version in `jekyll-text-theme.gemspec`, `package.json`, and `_includes/scripts/variables.html` |
| 91 | +2. Update `CHANGELOG.md` |
| 92 | +3. Run `npm run gem-build && npm run gem-push` |
| 93 | +4. Tag and push with `release: vx.x.x` commit message |
0 commit comments