Hugoifier

hugoifier / docs / architecture.md

Source Blame History 97 lines

04b8794…	lmata	1	# Architecture
04b8794…	lmata	2
04b8794…	lmata	3	## Pipeline
04b8794…	lmata	4
04b8794…	lmata	5	```mermaid
04b8794…	lmata	6	flowchart TD
04b8794…	lmata	7	A[Input path] --> B{Hugo theme?}
04b8794…	lmata	8	B -- Yes --> C[find_hugo_theme]
04b8794…	lmata	9	B -- No --> D[find_raw_html_files]
04b8794…	lmata	10
04b8794…	lmata	11	C --> E[Copy theme → themes/name/]
04b8794…	lmata	12	E --> F[Copy exampleSite content/data/static]
04b8794…	lmata	13	F --> G[Write hugo.toml]
04b8794…	lmata	14	G --> H[patch_theme + patch_config]
04b8794…	lmata	15	H --> I[decapify]
04b8794…	lmata	16
04b8794…	lmata	17	D --> J[hugoify_html via AI]
04b8794…	lmata	18	J --> K[Write layouts/]
04b8794…	lmata	19	K --> L[Copy CSS/JS/images]
04b8794…	lmata	20	L --> M[Write minimal hugo.toml]
04b8794…	lmata	21	M --> I
04b8794…	lmata	22
04b8794…	lmata	23	I --> N[output/theme-name/]
04b8794…	lmata	24	```
04b8794…	lmata	25
04b8794…	lmata	26	## Module Map
04b8794…	lmata	27
04b8794…	lmata	28	\| Module \| Responsibility \|
04b8794…	lmata	29	\|--------\|---------------\|
04b8794…	lmata	30	\| `src/cli.py` \| Argument parsing, logging setup, error handling \|
04b8794…	lmata	31	\| `src/config.py` \| Multi-backend AI routing (`call_ai`) \|
04b8794…	lmata	32	\| `src/utils/complete.py` \| Full pipeline orchestration \|
04b8794…	lmata	33	\| `src/utils/theme_finder.py` \| Locate Hugo theme + exampleSite within messy extracted directories \|
04b8794…	lmata	34	\| `src/utils/hugoify.py` \| AI-powered HTML → Hugo layout conversion \|
04b8794…	lmata	35	\| `src/utils/decapify.py` \| Generate Decap CMS `index.html` + `config.yml` \|
04b8794…	lmata	36	\| `src/utils/theme_patcher.py` \| Patch deprecated Hugo APIs in layout files and config \|
04b8794…	lmata	37	\| `src/utils/analyze.py` \| Theme structure reporting + AI-powered HTML analysis \|
04b8794…	lmata	38	\| `src/utils/translate.py` \| AI content translation \|
04b8794…	lmata	39	\| `src/utils/deploy.py` \| Cloudflare deployment _(stub)_ \|
04b8794…	lmata	40	\| `src/utils/cloudflare.py` \| Cloudflare configuration _(stub)_ \|
04b8794…	lmata	41	\| `src/utils/parser.py` \| HTML/CSS linting _(stub)_ \|
04b8794…	lmata	42
04b8794…	lmata	43	## AI Backends
04b8794…	lmata	44
04b8794…	lmata	45	All AI calls route through a single `call_ai(prompt, system)` function in `src/config.py`. Switch backends via `HUGOIFIER_BACKEND`:
04b8794…	lmata	46
04b8794…	lmata	47	\| Backend \| Default Model \| Env Var \|
04b8794…	lmata	48	\|---------\|--------------\|---------\|
04b8794…	lmata	49	\| `anthropic` (default) \| `claude-sonnet-4-6` \| `ANTHROPIC_API_KEY` \|
04b8794…	lmata	50	\| `openai` \| `gpt-4-turbo` \| `OPENAI_API_KEY` \|
04b8794…	lmata	51	\| `google` \| `gemini-1.5-pro` \| `GOOGLE_API_KEY` \|
04b8794…	lmata	52
04b8794…	lmata	53	## Hugo API Patching
04b8794…	lmata	54
04b8794…	lmata	55	`theme_patcher.py` handles breaking changes in Hugo ≥ v0.128:
04b8794…	lmata	56
04b8794…	lmata	57	Template patches:
04b8794…	lmata	58
04b8794…	lmata	59	\| Old \| New \|
04b8794…	lmata	60	\|-----\|-----\|
04b8794…	lmata	61	\| `.Site.DisqusShortname` \| `.Site.Config.Services.Disqus.Shortname` \|
04b8794…	lmata	62	\| `.Site.GoogleAnalytics` \| `.Site.Config.Services.GoogleAnalytics.ID` \|
04b8794…	lmata	63
04b8794…	lmata	64	Config patches (`hugo.toml`):
04b8794…	lmata	65
04b8794…	lmata	66	\| Old \| New \|
04b8794…	lmata	67	\|-----\|-----\|
04b8794…	lmata	68	\| `paginate = N` \| `[pagination] pagerSize = N` \|
04b8794…	lmata	69	\| `googleAnalytics = "UA-..."` \| `[services.googleAnalytics] id = "UA-..."` \|
04b8794…	lmata	70	\| `disqusShortname = "..."` \| `[services.disqus] shortname = "..."` \|
04b8794…	lmata	71
04b8794…	lmata	72	## Decap CMS Generation
04b8794…	lmata	73
04b8794…	lmata	74	`decapify.py` introspects `content/` to build Decap collections:
04b8794…	lmata	75
04b8794…	lmata	76	- Folder collection — subdirectory with `.md` files at any depth (blog, posts, etc.)
04b8794…	lmata	77	- File collection — subdirectory with only `_index.md` (about, contact, etc.)
04b8794…	lmata	78
04b8794…	lmata	79	Field types are inferred from YAML frontmatter values: `string`, `text`, `datetime`, `image`, `list`, `boolean`, `number`, `markdown`.
04b8794…	lmata	80
04b8794…	lmata	81	## Output Structure
04b8794…	lmata	82
04b8794…	lmata	83	```
04b8794…	lmata	84	output/{theme-name}/
04b8794…	lmata	85	├── hugo.toml # Site config (modernized)
04b8794…	lmata	86	├── content/ # From exampleSite or minimal stub
04b8794…	lmata	87	├── data/ # From exampleSite (if present)
04b8794…	lmata	88	├── static/
04b8794…	lmata	89	│ └── admin/
04b8794…	lmata	90	│ ├── index.html # Decap CMS UI
04b8794…	lmata	91	│ └── config.yml # Decap collections config
04b8794…	lmata	92	└── themes/
04b8794…	lmata	93	└── {theme-name}/ # Patched Hugo theme
04b8794…	lmata	94	├── layouts/
04b8794…	lmata	95	├── static/
04b8794…	lmata	96	└── archetypes/
04b8794…	lmata	97	```

Hugoifier

Keyboard Shortcuts