Skip to content

Commit ec06701

Browse files
markdumaymarkdumay
authored
Merge pull request #1654 from gethinode/develop
Develop
2 parents 41005f1 + 540e5e3 commit ec06701

File tree

6 files changed

+393
-141
lines changed

6 files changed

+393
-141
lines changed

‎CLAUDE.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Overview
6+
7+
Hinode is a Hugo theme for documentation and blog sites built on Bootstrap 5. It uses Hugo's module system to manage dependencies and includes Bookshop for component-based development. The theme is designed for performance, security (with CSP headers), and SEO.
8+
9+
## Common Development Commands
10+
11+
### Development Server
12+
13+
```bash
14+
npm start # Start Hugo server with module vendoring
15+
npm run start:example # Start server using exampleSite
16+
npm run start:prod # Start server in production mode
17+
npm run start:example:prod # Start exampleSite in production mode
18+
```
19+
20+
### Building
21+
22+
```bash
23+
npm run build # Build site with minification
24+
npm run build:example # Build exampleSite
25+
npm run build:debug # Build with debug output
26+
npm run build:headers # Generate Netlify/server headers
27+
```
28+
29+
### Linting & Testing
30+
31+
```bash
32+
npm test # Run all linters
33+
npm run lint # Run all linters
34+
npm run lint:scripts # ESLint for JavaScript (assets/js)
35+
npm run lint:styles # Stylelint for SCSS
36+
npm run lint:markdown # Markdownlint for Markdown files
37+
```
38+
39+
### Module Management
40+
41+
```bash
42+
npm run mod:vendor # Vendor Hugo modules to _vendor/
43+
npm run mod:update # Update all Hugo modules
44+
npm run mod:tidy # Clean up unused module dependencies
45+
npm run mod:clean # Remove module cache
46+
```
47+
48+
### Maintenance
49+
50+
```bash
51+
npm run clean:public # Remove generated public/ directories
52+
npm run clean:install # Remove node_modules and package-lock.json
53+
npm run upgrade # Update npm and Hugo module dependencies
54+
```
55+
56+
## Architecture
57+
58+
### Hugo Module System
59+
60+
The theme uses Hugo's module system extensively. All modules are vendored to `_vendor/` for reproducible builds. Key modules include:
61+
62+
- `mod-bootstrap` - Bootstrap 5 framework
63+
- `mod-flexsearch` - Full-text search functionality
64+
- `mod-fontawesome` - Icon support
65+
- `mod-utils` - Utility functions and helpers
66+
- `mod-katex`, `mod-mermaid`, `mod-leaflet`, `mod-lottie` - Optional feature modules
67+
- `cloudcannon/bookshop` - Component library system
68+
69+
Module configuration is in `config/_default/hugo.toml` under `[module.imports]`. Always run `npm run mod:vendor` after module changes.
70+
71+
### Component Library (Bookshop)
72+
73+
Components live in `component-library/components/`. Each component has:
74+
75+
- `*.hugo.html` - Hugo template
76+
- `*.scss` - Component styles
77+
- `*.bookshop.yml` - Schema definition
78+
79+
Components are mounted to multiple locations via `hugo.toml`:
80+
81+
- `layouts/partials/bookshop/` - Templates
82+
- `data/structures/` - Schemas
83+
- `assets/scss/modules/bookshop/` - Styles
84+
85+
### Directory Structure
86+
87+
- `layouts/` - Theme templates and shortcodes
88+
- `baseof.html` - Base template with navbar, footer, and content blocks
89+
- `_partials/` - Reusable template components
90+
- `_shortcodes/` - Hugo shortcodes for content (accordion, alert, card, etc.)
91+
- `assets/` - Source assets (JS, SCSS, images, icons)
92+
- `scss/` - Organized into components/, layouts/, theme/, helpers/
93+
- `js/` - JavaScript modules
94+
- `config/` - Hugo configuration
95+
- `_default/hugo.toml` - Main config with module imports
96+
- `postcss.config.js` - PostCSS with PurgeCSS and autoprefixer
97+
- `content/` - Theme content (minimal, main content in exampleSite)
98+
- `data/` - Data files for theme configuration
99+
- `i18n/` - Translation files (en, nl, fr, de, pl, pt-br, zh-hans, zh-hant)
100+
- `exampleSite/` - Full example site for testing theme
101+
- `static/` - Static assets copied directly to output
102+
103+
### CSS Pipeline
104+
105+
CSS uses PostCSS with:
106+
107+
1. **Autoprefixer** - Adds vendor prefixes
108+
2. **cssnano** - Minification
109+
3. **PurgeCSS** - Removes unused CSS based on `hugo_stats.json`
110+
111+
PurgeCSS safelist is defined in `config/postcss.config.js`. When adding new dynamic classes or Bootstrap components, update the safelist to prevent removal.
112+
113+
### Version Management
114+
115+
The theme supports versioned documentation with sidebar menus per version. Version detection happens in `baseof.html` using `utilities/GetVersion.html` partial.
116+
117+
### Shortcodes System
118+
119+
Extensive shortcode library in `layouts/_shortcodes/` provides Bootstrap components accessible in Markdown:
120+
121+
- Layout: accordion, card, carousel, collapse, navbar, tabs
122+
- UI: alert, badge, button, spinner, toast, tooltip
123+
- Content: image, video, table, timeline
124+
- Typography: abbr, kbd, mark, sub, sup
125+
126+
### Content Security Policy
127+
128+
CSP headers are auto-generated via Hugo's segments feature. The theme includes `mod-csp` for Content Security Policy management. Headers are defined in `netlify.toml` and generated via `npm run build:headers`.
129+
130+
### Internationalization
131+
132+
Multi-language support with translations in `i18n/`. Default language is English (`en-us`). Language configuration in `config/_default/hugo.toml`.
133+
134+
## Key Configuration Files
135+
136+
- `hugo.toml` - Main Hugo config with modules, mounts, build settings
137+
- `package.json` - npm scripts and dependencies
138+
- `go.mod` - Hugo module dependencies (Go modules)
139+
- `postcss.config.js` - PostCSS pipeline with PurgeCSS safelist
140+
- `netlify.toml` - Netlify build config and security headers
141+
- `.eslintrc.yml` - JavaScript linting (ES6, browser environment)
142+
- `.stylelintrc.json` - SCSS linting (standard-scss)
143+
- `.markdownlint-cli2.jsonc` - Markdown linting rules
144+
145+
## Important Development Notes
146+
147+
### When Modifying Components
148+
149+
1. Components in `component-library/` need three files: `.hugo.html`, `.scss`, `.bookshop.yml`
150+
2. Update PurgeCSS safelist in `config/postcss.config.js` if adding dynamic classes
151+
3. Component styles are automatically mounted via `hugo.toml` module mounts
152+
153+
### When Adding Hugo Modules
154+
155+
1. Add to `go.mod` requires section
156+
2. Add to `[module.imports]` in `hugo.toml`
157+
3. Run `npm run mod:vendor` to vendor the module
158+
4. If module has styles, add to PurgeCSS safelist in `postcss.config.js`
159+
160+
### When Working with Layouts
161+
162+
- `baseof.html` is the main template; it sets up version-aware menus, content blocks, overlay mode
163+
- Partials in `_partials/` are organized: `head/`, `footer/`, `page/`, `utilities/`, `assets/`
164+
- The theme uses `.Scratch` extensively for passing data between partials
165+
166+
### Build Process
167+
168+
1. `hugo mod vendor` - Vendors modules to `_vendor/`
169+
2. Hugo build generates `hugo_stats.json` with used classes/tags/ids
170+
3. PostCSS processes SCSS, using `hugo_stats.json` to purge unused CSS
171+
4. Final output in `public/` or `exampleSite/public/`
172+
173+
### Testing Changes
174+
175+
Test with both main site and exampleSite:
176+
177+
- `npm start` - Test theme directly
178+
- `npm run start:example` - Test with full example content
179+
- `npm run lint` - Check code quality before committing
180+
181+
### Git Workflow
182+
183+
- Main branch: `main` (production releases)
184+
- Development branch: `develop`
185+
- Uses semantic-release for automated versioning
186+
- Commits follow conventional commits (enforced by commitlint)
187+
- Husky pre-commit hooks run linters

‎exampleSite/content/en/blog/components.md‎

Lines changed: 31 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -33,38 +33,38 @@ As an example, the following shortcode displays a responsive table that uses adv
3333
<!-- markdownlint-disable MD037 MD058 -->
3434
{{< example lang="markdown" >}}
3535
{{</* table sortable="true" paginate="true" searchable="true" pagination=5 */>}}
36-
| # | Heading |
36+
| # | Heading |
3737
|-----|---------|
38-
| 1. | Item 1 |
39-
| 2. | Item 2 |
40-
| 3. | Item 3 |
41-
| 4. | Item 4 |
42-
| 5. | Item 5 |
43-
| 6. | Item 6 |
44-
| 7. | Item 7 |
45-
| 8. | Item 8 |
46-
| 9. | Item 9 |
47-
| 10. | Item 10 |
48-
| 11. | Item 11 |
49-
| 12. | Item 12 |
50-
| 13. | Item 13 |
51-
| 14. | Item 14 |
52-
| 15. | Item 15 |
53-
| 16. | Item 16 |
54-
| 17. | Item 17 |
55-
| 18. | Item 18 |
56-
| 19. | Item 19 |
57-
| 20. | Item 20 |
58-
| 21. | Item 21 |
59-
| 22. | Item 22 |
60-
| 23. | Item 23 |
61-
| 24. | Item 24 |
62-
| 25. | Item 25 |
63-
| 26. | Item 26 |
64-
| 27. | Item 27 |
65-
| 28. | Item 28 |
66-
| 29. | Item 29 |
67-
| 30. | Item 30 |
38+
| 1. | Item 1 |
39+
| 2. | Item 2 |
40+
| 3. | Item 3 |
41+
| 4. | Item 4 |
42+
| 5. | Item 5 |
43+
| 6. | Item 6 |
44+
| 7. | Item 7 |
45+
| 8. | Item 8 |
46+
| 9. | Item 9 |
47+
| 10. | Item 10 |
48+
| 11. | Item 11 |
49+
| 12. | Item 12 |
50+
| 13. | Item 13 |
51+
| 14. | Item 14 |
52+
| 15. | Item 15 |
53+
| 16. | Item 16 |
54+
| 17. | Item 17 |
55+
| 18. | Item 18 |
56+
| 19. | Item 19 |
57+
| 20. | Item 20 |
58+
| 21. | Item 21 |
59+
| 22. | Item 22 |
60+
| 23. | Item 23 |
61+
| 24. | Item 24 |
62+
| 25. | Item 25 |
63+
| 26. | Item 26 |
64+
| 27. | Item 27 |
65+
| 28. | Item 28 |
66+
| 29. | Item 29 |
67+
| 30. | Item 30 |
6868
{{</* /table */>}}
6969
{{< /example >}}
7070
<!-- markdownlint-enable MD037 -->

‎exampleSite/content/fr/blog/components.md‎

Lines changed: 31 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -34,38 +34,38 @@ Hinode propose plusieurs shortcodes en plus des [éléments Bootstrap]({{% relre
3434
<!-- markdownlint-disable MD037 MD058 -->
3535
{{< example lang="markdown" >}}
3636
{{</* table sortable="true" paginate="true" searchable="true" pagination=5 */>}}
37-
| # | Heading |
37+
| # | Heading |
3838
|-----|---------|
39-
| 1. | Item 1 |
40-
| 2. | Item 2 |
41-
| 3. | Item 3 |
42-
| 4. | Item 4 |
43-
| 5. | Item 5 |
44-
| 6. | Item 6 |
45-
| 7. | Item 7 |
46-
| 8. | Item 8 |
47-
| 9. | Item 9 |
48-
| 10. | Item 10 |
49-
| 11. | Item 11 |
50-
| 12. | Item 12 |
51-
| 13. | Item 13 |
52-
| 14. | Item 14 |
53-
| 15. | Item 15 |
54-
| 16. | Item 16 |
55-
| 17. | Item 17 |
56-
| 18. | Item 18 |
57-
| 19. | Item 19 |
58-
| 20. | Item 20 |
59-
| 21. | Item 21 |
60-
| 22. | Item 22 |
61-
| 23. | Item 23 |
62-
| 24. | Item 24 |
63-
| 25. | Item 25 |
64-
| 26. | Item 26 |
65-
| 27. | Item 27 |
66-
| 28. | Item 28 |
67-
| 29. | Item 29 |
68-
| 30. | Item 30 |
39+
| 1. | Item 1 |
40+
| 2. | Item 2 |
41+
| 3. | Item 3 |
42+
| 4. | Item 4 |
43+
| 5. | Item 5 |
44+
| 6. | Item 6 |
45+
| 7. | Item 7 |
46+
| 8. | Item 8 |
47+
| 9. | Item 9 |
48+
| 10. | Item 10 |
49+
| 11. | Item 11 |
50+
| 12. | Item 12 |
51+
| 13. | Item 13 |
52+
| 14. | Item 14 |
53+
| 15. | Item 15 |
54+
| 16. | Item 16 |
55+
| 17. | Item 17 |
56+
| 18. | Item 18 |
57+
| 19. | Item 19 |
58+
| 20. | Item 20 |
59+
| 21. | Item 21 |
60+
| 22. | Item 22 |
61+
| 23. | Item 23 |
62+
| 24. | Item 24 |
63+
| 25. | Item 25 |
64+
| 26. | Item 26 |
65+
| 27. | Item 27 |
66+
| 28. | Item 28 |
67+
| 29. | Item 29 |
68+
| 30. | Item 30 |
6969
{{</* /table */>}}
7070
{{< /example >}}
7171
<!-- markdownlint-enable MD037 -->

‎exampleSite/content/nl/blog/components.md‎

Lines changed: 31 additions & 31 deletions
Original file line numberDiff line numberDiff line change
@@ -32,38 +32,38 @@ Het volgende voorbeeld gebruikt een shortcode om een responsieve tabel met geava
3232
<!-- markdownlint-disable MD037 MD058 -->
3333
{{< example lang="markdown" >}}
3434
{{</* table sortable="true" paginate="true" searchable="true" pagination=5 */>}}
35-
| # | Kop |
35+
| # | Kop |
3636
|-----|---------|
37-
| 1. | Item 1 |
38-
| 2. | Item 2 |
39-
| 3. | Item 3 |
40-
| 4. | Item 4 |
41-
| 5. | Item 5 |
42-
| 6. | Item 6 |
43-
| 7. | Item 7 |
44-
| 8. | Item 8 |
45-
| 9. | Item 9 |
46-
| 10. | Item 10 |
47-
| 11. | Item 11 |
48-
| 12. | Item 12 |
49-
| 13. | Item 13 |
50-
| 14. | Item 14 |
51-
| 15. | Item 15 |
52-
| 16. | Item 16 |
53-
| 17. | Item 17 |
54-
| 18. | Item 18 |
55-
| 19. | Item 19 |
56-
| 20. | Item 20 |
57-
| 21. | Item 21 |
58-
| 22. | Item 22 |
59-
| 23. | Item 23 |
60-
| 24. | Item 24 |
61-
| 25. | Item 25 |
62-
| 26. | Item 26 |
63-
| 27. | Item 27 |
64-
| 28. | Item 28 |
65-
| 29. | Item 29 |
66-
| 30. | Item 30 |
37+
| 1. | Item 1 |
38+
| 2. | Item 2 |
39+
| 3. | Item 3 |
40+
| 4. | Item 4 |
41+
| 5. | Item 5 |
42+
| 6. | Item 6 |
43+
| 7. | Item 7 |
44+
| 8. | Item 8 |
45+
| 9. | Item 9 |
46+
| 10. | Item 10 |
47+
| 11. | Item 11 |
48+
| 12. | Item 12 |
49+
| 13. | Item 13 |
50+
| 14. | Item 14 |
51+
| 15. | Item 15 |
52+
| 16. | Item 16 |
53+
| 17. | Item 17 |
54+
| 18. | Item 18 |
55+
| 19. | Item 19 |
56+
| 20. | Item 20 |
57+
| 21. | Item 21 |
58+
| 22. | Item 22 |
59+
| 23. | Item 23 |
60+
| 24. | Item 24 |
61+
| 25. | Item 25 |
62+
| 26. | Item 26 |
63+
| 27. | Item 27 |
64+
| 28. | Item 28 |
65+
| 29. | Item 29 |
66+
| 30. | Item 30 |
6767
{{</* /table */>}}
6868
{{< /example >}}
6969
<!-- markdownlint-enable MD037 MD058 -->

0 commit comments

Comments
 (0)