diff --git a/.astro/settings.json b/.astro/settings.json new file mode 100644 index 000000000..714078e25 --- /dev/null +++ b/.astro/settings.json @@ -0,0 +1,5 @@ +{ + "_variables": { + "lastUpdateCheck": 1757392445369 + } +} \ No newline at end of file diff --git a/.gitignore b/.gitignore index 118a81374..9f2a7dc0d 100644 --- a/.gitignore +++ b/.gitignore @@ -11,7 +11,6 @@ yarn-debug.log* yarn-error.log* pnpm-debug.log* - # environment variables .env .env.production @@ -20,4 +19,7 @@ pnpm-debug.log* .DS_Store icon.d.ts -*.cache \ No newline at end of file +*.cache + +# Crush files +.crush \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..523043b4e --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,25 @@ +# AGENTS.md - Odyssey Theme Development Guide + +## Commands +- `npm run dev` - Start dev server at localhost:4321 +- `npm run build` - Build production site to ./dist/ +- `npm run format` - Format code with Prettier (no lint/test commands configured) + +## Code Style +- **Prettier**: Tabs, single quotes, semicolons required, arrow functions without parens for single params +- **Naming**: Components (PascalCase), files (kebab-case), CSS classes (BEM: `feature-card__section`) +- **Imports**: Use path aliases (`@components/*`, `@layouts/*`, etc.), barrel exports from `odyssey-theme.js` + +## Architecture +- **Framework**: Astro v4.15.9 + TypeScript + MDX +- **Styling**: CSS custom properties in `src/styles/theme.css` +- **Config**: Centralized in `src/config/` (settings, nav, footer) +- **Components**: Functional grouping (core, sections, forms, blog) +- **Layouts**: Base → Page → Post hierarchy + +## Key Patterns +- Import Astro components with `.astro` extension +- Use `astro-icon` with `Icon` component for icons +- Theme switching via CSS custom properties +- Mobile-first responsive design +- No testing framework configured \ No newline at end of file diff --git a/BASELINE_CONTENT.md b/BASELINE_CONTENT.md new file mode 100644 index 000000000..86737a5bc --- /dev/null +++ b/BASELINE_CONTENT.md @@ -0,0 +1,7 @@ +# Baseline Content Inventory + +- src/pages/blog/posts: 3 MDX files +- src/pages/solutions/items: 1 MDX files +- src/pages/industries/items: 1 MDX files + +Generated: 2025-09-09T08:11:50.946Z diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 000000000..c78584e74 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,118 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is a customized version of the Astro Odyssey Theme, specifically configured for business marketing websites with added Solutions and Industries functionality. The theme has been modified from the original to include: + +- Custom dark theme as default (theme switcher disabled) +- Solutions section with dedicated components and pages +- Industries section with dedicated components and pages +- Enhanced component exports in odyssey-theme.js + +## Development Commands + +```bash +npm run dev # Start development server at localhost:4321 +npm run start # Alias for npm run dev +npm run build # Build production site to ./dist/ +npm run preview # Preview production build locally +npm run format # Format code with Prettier +``` + +## Architecture & Key Customizations + +### Theme Configuration +- **Default Theme**: Dark theme is now the default (not light) +- **Theme Switcher**: Disabled via `enableThemeSwitcher: false` in settings.js +- **Dark Theme Variables**: `:root` now contains dark theme values by default + +### Navigation Structure +The site navigation includes custom business sections: +- Solutions (`/solutions`) +- Industries (`/industries`) +- Standard sections: Home, Blog, About + +### Component Architecture + +#### New Business Components +- `SolutionsList.astro` & `SolutionCard.astro` - Solutions display components +- `IndustriesList.astro` & `IndustryCard.astro` - Industries display components +- Enhanced form fields: `FormInput.astro`, `FormTextarea.astro`, `FormSelect.astro` + +#### Component Export System +- `src/components/odyssey-theme.js` exports all reusable components +- Components are organized by category: sections, blog, solutions, industries, forms +- Use `import { ComponentName } from '@components/odyssey-theme'` pattern + +### TypeScript Path Mapping +```typescript +"@config": ["config/*"] // Site configuration +"@components/*": ["components/*"] // All components +"@layouts/*": ["layouts/*"] // Page layouts +"@styles/*": ["styles/*"] // CSS files +"@pages/*": ["pages/*"] // Page components +"@assets/*": ["assets/*"] // Static assets +"@utils/*": ["utils/*"] // Utility functions +"@icons/*": ["icons/*"] // Custom icons +``` + +### Configuration System +- `src/config/settings.js` - Global site settings (theme switcher disabled) +- `src/config/nav.js` - Main navigation including Solutions/Industries +- `src/config/footer.js` - Footer configuration + +### Styling System +- **Default Theme**: Dark theme values in `:root` +- **Theme Variables**: CSS custom properties in `src/styles/theme.css` +- **Shape Radius**: Set to 0 for straight edges in dark theme +- **Color Scheme**: Uses HSL values for precise color control + +## Key Implementation Details + +### Theme Switching Disabled +The theme switcher component exists but is disabled. The site uses a fixed dark theme configuration. + +### Business-Focused Structure +The codebase is structured for B2B marketing sites with: +- Solutions-focused content architecture +- Industry-specific components and pages +- Professional dark theme aesthetic + +### Component Usage Pattern +```astro +--- +import { + SolutionsList, + IndustriesList, + ThreeColumnTextSection, + CtaCardSection +} from '@components/odyssey-theme'; +--- + + + +``` + +### Form Components Enhanced +New form field components provide consistent styling: +- `FormInput` - Text inputs with theme integration +- `FormTextarea` - Multi-line text areas +- `FormSelect` - Dropdown selects + +## File Structure Notes + +### Recent Customizations +- Homepage (`src/pages/index.astro`) uses business-focused components +- Component exports updated to include Solutions/Industries components +- Navigation configured for business sections +- Dark theme set as default throughout + +### Integration Points +- Astro v4.15.9 with Lit components for interactivity +- MDX support for rich content pages +- Icon system using Iconify with Material Design and Outline icons +- Sitemap generation for SEO + +The codebase maintains the Odyssey theme's component-driven architecture while adding business-specific functionality and a professional dark theme aesthetic. \ No newline at end of file diff --git a/CRUSH.md b/CRUSH.md new file mode 100644 index 000000000..35b47517c --- /dev/null +++ b/CRUSH.md @@ -0,0 +1,20 @@ +# Development Commands +- `npm run dev` - Start dev server at localhost:4321 +- `npm run build` - Build production site to ./dist/ +- `npm run preview` - Preview production build locally +- `npm run format` - Format code with Prettier + +# Code Style +- **Formatting**: Tabs, single quotes, semicolons required, arrow functions without parens for single params +- **Components**: PascalCase (e.g., `SolutionsList.astro`) +- **Files**: kebab-case (e.g., `solution-card.astro`) +- **CSS Classes**: BEM notation (e.g., `feature-card__section`) +- **Imports**: Use path aliases from `@components/odyssey-theme` barrel export +- **Paths**: TypeScript aliases (`@config/*`, `@components/*`, `@layouts/*`, etc.) + +# Architecture +- **Framework**: Astro v4.15.9 + TypeScript + MDX + Lit components +- **Styling**: CSS custom properties in `src/styles/theme.css` +- **Theme**: Dark theme default, theme switcher disabled +- **Components**: Functional grouping (core, sections, forms, blog, solutions, industries) +- **No lint/test commands configured** - only format and build commands available \ No newline at end of file diff --git a/PLAN_SOLUTIONS_INDUSTRIES_PAGINATION_CLEANUP.md b/PLAN_SOLUTIONS_INDUSTRIES_PAGINATION_CLEANUP.md new file mode 100644 index 000000000..4b49aac3b --- /dev/null +++ b/PLAN_SOLUTIONS_INDUSTRIES_PAGINATION_CLEANUP.md @@ -0,0 +1,100 @@ +# Plan: Solutions & Industries Pagination Artifact Cleanup +Status: Draft (awaiting approval) +Owner: TBD +Last Updated: 2025-09-09 + +## 1. Objective +Remove legacy / experimental pagination implementation for Solutions (`/solutions/page/[page]`) and Industries (`/industries/page/[page]`) so that: +- Single canonical listing lives at `/solutions` and `/industries` (full list, no paging). +- No duplicate / orphan static pages (e.g., `/solutions/page/1`). +- No accidental future reintroduction via config or copy/paste. +- Optional: Graceful redirects for any external links that may have been shared already. + +## 2. Current State (Observed) +| Aspect | Solutions | Industries | Notes | +|--------|-----------|------------|-------| +Dynamic route file present | `src/pages/solutions/page/[page].astro` | `src/pages/industries/page/[page].astro` | Both auto-generate paths via `getStaticPaths` | +Index listing page | `src/pages/solutions/index.astro` | `src/pages/industries/index.astro` | Shows full list (no pagination UI) | +Pagination component usage | Only in dynamic files | Only in dynamic files | Not referenced elsewhere | +Config dependency | `theme.config.js` uses `pagination.pageSize = 10` | Same | Setting shared with Blog pagination | +Generated pages count (likely) | 1 (since only 1–2 MDX items) | 1 | Leads to duplicate content (/page/1) | +Inbound links to /page/* | None in repo (grep results) | None | Orphan pages (crawl depth low) | + +## 3. Why This Matters +| Area | Issue | Impact | +|------|-------|--------| +SEO | Duplicate content (`/solutions` vs `/solutions/page/1`) | Diluted signals, crawl waste | +DX | Dead / orphan routes add noise | Harder future maintenance | +Future taxonomy | Will centralize list shaping in unified utilities | Cleaner baseline needed | +Performance | Extra pages built (minor now) | Scales poorly if content grows | + +## 4. Decision Matrix +| Option | Description | Pros | Cons | Decision | +|--------|------------|------|------|----------| +Remove files (hard delete) | Delete dynamic route Astro files | Clean & simple | External links to /page/1 404 | Preferred | +Redirect (301) | Keep redirect rule `/solutions/page/* -> /solutions` | Preserves any shared links | Adds config complexity | Optional (add only if risk perceived) | +Soft guard | Keep files but early-return redirect | Minimal file churn | Leaves dead code around | Reject | + +## 5. Proposed Actions (High-Level) +1. Delete `src/pages/solutions/page/[page].astro` and `src/pages/industries/page/[page].astro`. +2. Grep for residual references to `/solutions/page` & `/industries/page` (should be none after deletion). +3. (Optional) Add Netlify redirects in `netlify.toml` for any `/solutions/page/:n` & `/industries/page/:n` → canonical listing (301). +4. Update documentation to explicitly state “Solutions & Industries are intentionally unpaginated until volume threshold > X.” +5. Add small regression guard comment inside each index listing file clarifying pagination intentionally omitted. +6. (Optional) Add test (future) verifying absence of generated paths (if a route list utility is introduced later). + +## 6. Redirect Strategy (Optional) +Netlify example (only if we believe links may exist): +``` +[[redirects]] + from = "/solutions/page/:n" + to = "/solutions" + status = 301 + force = false + +[[redirects]] + from = "/industries/page/:n" + to = "/industries" + status = 301 + force = false +``` +Decision to implement: DEFAULT = Skip (can be added later with near-zero cost). + +## 7. Risks & Mitigations +| Risk | Likelihood | Impact | Mitigation | +|------|------------|--------|-----------| +External bookmarks to /page/1 break | Low | Low | Add redirects if reported | +Unintended deletion of needed shared helper | Low | Low | Files are isolated; no shared exports | +Future reintroduction without awareness | Medium | Medium | Add comment + doc; codify rule in docs | + +## 8. Acceptance Criteria +- Visiting `/solutions/page/1` results in 404 (or redirect if optional redirect chosen). +- Repository contains no `src/pages/solutions/page` or `src/pages/industries/page` directories. +- `grep -R "solutions/page" .` returns only intentional documentation references (at most plan/history docs). +- Index pages render full lists exactly as before (no functional regression). +- Blog pagination unaffected. + +## 9. Out of Scope +- Blog pagination refinements (handled in separate plan). +- Future taxonomy or relationship-based filtering. +- Client-side filtering / search. + +## 10. Rollback Plan +If removal causes unexpected breakage: +1. Recreate the dynamic files from git history (use previous commit hash reference). +2. Re-run build & redeploy. +3. Investigate dependency wrongly relying on those routes. + +## 11. Implementation Order +1. Delete files. +2. Add optional redirects (if approved). +3. Add documentation note + source code inline comment. +4. Commit as `chore(cleanup): remove solutions/industries pagination artifacts`. +5. Open PR to `dark-theme-business` (if working on feature branch) OR commit directly if policy allows. + +## 12. Effort Estimate +Engineering: ~15–25 minutes. +Docs + commit review: ~10 minutes. + +--- +Awaiting approval before executing. diff --git a/TASKS_SOLUTIONS_INDUSTRIES_PAGINATION_CLEANUP.md b/TASKS_SOLUTIONS_INDUSTRIES_PAGINATION_CLEANUP.md new file mode 100644 index 000000000..0ce0cfd41 --- /dev/null +++ b/TASKS_SOLUTIONS_INDUSTRIES_PAGINATION_CLEANUP.md @@ -0,0 +1,47 @@ +# Task Breakdown: Solutions & Industries Pagination Cleanup +Status: Draft (pending approval) +Parent Plan: `PLAN_SOLUTIONS_INDUSTRIES_PAGINATION_CLEANUP.md` + +| ID | Task | Details / Commands | Owner | Effort | Depends On | Status | +|----|------|--------------------|-------|--------|------------|--------| +| T1 | Inventory confirmation | `ls src/pages/solutions/page` & `ls src/pages/industries/page` (expect `[page].astro`) | TBD | S | - | Pending | +| T2 | Delete dynamic pagination files | Remove both `[page].astro` files | TBD | S | T1 | Pending | +| T3 | Grep for residual refs | `grep -R "solutions/page" .` & `grep -R "industries/page" .` | TBD | S | T2 | Pending | +| T4 | Add optional redirects (if approved) | Edit `netlify.toml` (2 blocks) | TBD | S | Approval | Deferred* | +| T5 | Add documentation note | Append section to `docs/architecture.md` OR new `docs/content-lists.md` | TBD | M | T2 | Pending | +| T6 | Inline safeguard comments | Add comment in `src/pages/solutions/index.astro` & `src/pages/industries/index.astro` | TBD | XS | T2 | Pending | +| T7 | Commit & PR | Commit message: `chore(cleanup): remove solutions & industries pagination artifacts` | TBD | XS | T3 | Pending | +| T8 | Verify build locally | Run dev build; visit `/solutions`, `/industries`, check 404 on `/solutions/page/1` | TBD | S | T7 | Pending | +| T9 | Optional redirect verification | If T4 done: curl or browser test old URLs | TBD | XS | T4 | Deferred* | +| T10 | Close plan | Mark plan as completed in header | TBD | XS | T8 | Pending | + +Legend: Effort — XS (<5m), S (5–10m), M (10–20m), L (20–40m), XL (>40m) +*Deferred tasks only executed if redirect path approved. + +## Detailed Notes Per Task +### T2 Deletion +Paths to delete: +- `src/pages/solutions/page/[page].astro` +- `src/pages/industries/page/[page].astro` + +### T4 Redirect Block (Optional) +See plan for snippet; ensure no trailing slash mismatch. + +### T5 Documentation Guidance +Add rationale: “Unpaginated by design until content volume > threshold (e.g., > 25 items). At that point re-evaluate for performance + SEO list page depth.” + +### T6 Inline Comment Example +```astro + +``` + +### T8 Verification Checklist +- No build warnings about missing routes. +- `/blog/page/1` still works (blog unaffected). +- 404 page shows for removed URLs. + +### Risk Flags +If future taxonomy introduces slicing logic, ensure it doesn’t implicitly re-add pagination for these sections without explicit stakeholder buy‑in. + +--- +Awaiting approval. diff --git a/astro-odyssey-backpack/astro-poster-boards/pb-v1-sections/PLAN_SOLUTIONS_INDUSTRIES.md b/astro-odyssey-backpack/astro-poster-boards/pb-v1-sections/PLAN_SOLUTIONS_INDUSTRIES.md new file mode 100644 index 000000000..472593258 --- /dev/null +++ b/astro-odyssey-backpack/astro-poster-boards/pb-v1-sections/PLAN_SOLUTIONS_INDUSTRIES.md @@ -0,0 +1,103 @@ +# Solutions & Industries Expansion Plan + +(Approved on request) + +## 1. Goals +Add two new content sections: Solutions and Industries with MDX-based authoring like the Blog. Astro-only implementation. Clean routes: +- `/solutions` (listing) +- `/solutions/` (detail) +- `/industries` (listing) +- `/industries/` (detail) + +## 2. Structure +``` +src/pages/solutions/index.astro +src/pages/solutions/items/.mdx +src/pages/industries/index.astro +src/pages/industries/items/.mdx +src/layouts/Solution.astro +src/layouts/Industry.astro +src/components/solutions/{SolutionCard,SolutionsList}.astro +src/components/industries/{IndustryCard,IndustriesList}.astro +``` + +## 3. Frontmatter Schemas +Solution MDX: +``` +--- +layout: '../../../layouts/Solution.astro' +title: Pipeline Automation +description: Automate data integration tasks +publishDate: September 8, 2025 +excerpt: Short teaser sentence. +featuredImage: '/assets/images/solutions/pipeline-automation/featured.jpg' +industries: ['Healthcare', 'Finance'] +tags: ['Automation', 'Data'] +status: 'active' +--- +``` +Industry MDX: +``` +--- +layout: '../../../layouts/Industry.astro' +title: Healthcare +description: Tech enabling providers & payers +publishDate: September 8, 2025 +excerpt: Short teaser +featuredImage: '/assets/images/industries/healthcare/featured.jpg' +solutions: ['Pipeline Automation', 'Patient Analytics'] +segments: ['Providers', 'Payers'] +tags: ['Compliance'] +--- +``` + +## 4. Data Loading +Use `Astro.glob('./items/*.mdx')` in each index page, map to objects: `{title, description, excerpt, publishDate (parsed), featuredImage, href, industries/solutions, tags}`. Sort new → old. + +## 5. Layouts +Clone `Post.astro` minus blog tag links. Add optional related sections rendering frontmatter arrays. + +## 6. Components +Cards + Lists similar to blog list grid. Separate for clarity. + +## 7. Navigation +Add to `src/config/nav.js` before Blog: +``` +{ title: 'Solutions', slug: '/solutions' }, +{ title: 'Industries', slug: '/industries' }, +``` + +## 8. SEO +Per page SEO object. Index titles: `Solutions | Odyssey Theme`, `Industries | Odyssey Theme`. + +## 9. Edge Cases +- Missing publishDate: place at end. +- Missing image: fallback placeholder. +- Empty list: show friendly message. +- Duplicate titles: rely on unique filenames (document expectation). + +## 10. Phases +Phase 1 (MVP): Structure, example content, listing, layouts, nav. +Phase 2: Reverse relationship auto-generation, filters. +Phase 3: RSS, JSON-LD, search integration. + +## 11. Acceptance Criteria +- Adding new MDX appears in listing automatically. +- Detail pages render with correct layout. +- Related arrays display if present. +- Navigation updated. +- Build passes. +- No React/Tailwind introduced. + +## 12. Deferred Enhancements +- Auto reverse linking. +- Tag taxonomy reuse. +- Query param filters. +- Search indexing. + +## 13. Risks & Mitigations +- Inconsistent naming → slug conflict; mitigate with file-based slugs. +- Large lists future performance → paginate later if needed. + +## 14. Testing Strategy +Manual verification + adding second sample in each collection. Visual scan for layout integrity. Optionally Lighthouse quick check. diff --git a/astro-odyssey-backpack/astro-poster-boards/pb-v1-sections/TASKS_SOLUTIONS_INDUSTRIES.md b/astro-odyssey-backpack/astro-poster-boards/pb-v1-sections/TASKS_SOLUTIONS_INDUSTRIES.md new file mode 100644 index 000000000..ed57f4b4e --- /dev/null +++ b/astro-odyssey-backpack/astro-poster-boards/pb-v1-sections/TASKS_SOLUTIONS_INDUSTRIES.md @@ -0,0 +1,60 @@ +# Tasks: Solutions & Industries Implementation + +## Phase 0: Prep +- [ ] Ensure branch `feature/solutions-industries-section` active (created) +- [ ] Add placeholder images if needed + +## Phase 1: Structure & Example Content +- [ ] Create dirs: `src/pages/solutions/items/`, `src/pages/industries/items/` +- [ ] Add example: `pipeline-automation.mdx` +- [ ] Add example: `healthcare.mdx` + +## Phase 2: Layouts +- [ ] Create `src/layouts/Solution.astro` +- [ ] Create `src/layouts/Industry.astro` +- [ ] Mirror `Post.astro` minus blog tags; add related sections placeholders + +## Phase 3: Components +- [ ] `components/solutions/SolutionCard.astro` +- [ ] `components/solutions/SolutionsList.astro` +- [ ] `components/industries/IndustryCard.astro` +- [ ] `components/industries/IndustriesList.astro` + +## Phase 4: Index Pages +- [ ] `pages/solutions/index.astro` glob + map + sort + list +- [ ] `pages/industries/index.astro` glob + map + sort + list + +## Phase 5: Navigation +- [ ] Update `src/config/nav.js` +- [ ] Verify header renders new links + +## Phase 6: Related Data (MVP) +- [ ] Render frontmatter `industries` on Solution detail if present +- [ ] Render frontmatter `solutions` on Industry detail if present + +## Phase 7: SEO & Metadata +- [ ] Add SEO objects to index pages +- [ ] Add SEO object generation to new layouts + +## Phase 8: Fallbacks & Edge Cases +- [ ] Handle missing publishDate (push to end) +- [ ] Placeholder image logic +- [ ] Empty collection messages + +## Phase 9: QA +- [ ] Add 2nd solution MDX +- [ ] Add 2nd industry MDX +- [ ] Manual verify routes & nav +- [ ] Build passes (`pnpm build`) + +## Phase 10: (Deferred Enhancements) +- [ ] Reverse relationship auto-building +- [ ] Filters (query params) +- [ ] RSS / JSON-LD / Search integration + +## Completion Checklist +- [ ] All acceptance criteria met +- [ ] No console errors +- [ ] No unused imports +- [ ] No React/Tailwind introduced +- [ ] Branch ready for PR diff --git a/astro-odyssey-backpack/astro-poster-boards/pb-v2-seo/PLAN_BLOG_PAGINATION_REFINEMENTS.md b/astro-odyssey-backpack/astro-poster-boards/pb-v2-seo/PLAN_BLOG_PAGINATION_REFINEMENTS.md new file mode 100644 index 000000000..a12d418aa --- /dev/null +++ b/astro-odyssey-backpack/astro-poster-boards/pb-v2-seo/PLAN_BLOG_PAGINATION_REFINEMENTS.md @@ -0,0 +1,131 @@ +``` + ____ _ _ ____ _ _ _ +| __ )| | __ _ __ _| | ___ | _ \ __ _| |_ ___| |__ ___ / \ _ __ ___ +| _ \| |/ _` |/ _` | |/ _ \ | | | |/ _` | __/ __| '_ \ / _ \ / _ \ | '__/ _ \ +| |_) | | (_| | (_| | | __/ | |_| | (_| | || (__| | | | __// ___ \| | | __/ +|____/|_|\__,_|\__, |_|\___| |____/ \__,_|\__\___|_| |_|\___/_/ \_\_| \___| + |___/ +``` + +# Blog Pagination & Listing Refinements Plan (Future Development) +Status: Draft (awaiting scheduling) + +## 1. Goals +Enhance the current blog pagination implementation to reach production-grade quality while preserving performance and SEO integrity. + +## 2. Current State Summary +- Pagination implemented for `/blog` with dynamic route `/blog/page/[page]`. +- Page 1 content duplicated (accessible both at `/blog` and `/blog/page/1`). +- No canonical / prev / next link tags yet. +- No guard for invalid page numbers (e.g., `/blog/page/999`). +- Post mapping logic duplicated between index and dynamic page file. + +## 3. Scope of Refinements +| Area | Improvement | Rationale | +|------|------------|-----------| +SEO | Canonical link for page 1 & self-referencing canonicals for other pages | Prevent duplicate content indexing | +SEO | Rel prev/next `` tags | Improve crawler discovery & ranking signals | +Routing | 404 or redirect for out-of-range pages | UX integrity & avoids thin pages | +DX | Extract shared post normalization to helper | DRY & future reuse (taxonomy) | +DX | Add TypeScript-style JSDoc typings in helper | Editor intellisense & clarity | +Perf | Optional build-time cache for parsed dates | Slight build speed with scale | +UI | Optional pager truncation for large page counts | Avoid overwhelming navigation | +Analytics (optional) | Data attributes on pagination links | Click tracking integration | +Accessibility | Add ARIA labels, `aria-current` (already partly done) | Conformance & assistive tech benefits | + +## 4. Detailed Tasks +### 4.1 Canonical & Meta Enhancements +- Add `` for page 1 only. +- For page >1: canonical points to `/blog/page/N`. +- Add `` for invalid pages (if using redirect fallback, may be unnecessary). + +### 4.2 Prev/Next Link Tags +Insert in layout head slot (or inside each page frontmatter block): +```html + + +``` +Rules: +- Omit `prev` on page 1. +- Omit `next` on last page. + +### 4.3 Invalid Page Handling +Options: +1. Build-time: do not generate out-of-range paths (already true) + custom 404 guidance. +2. Defensive runtime: if `page > totalPages`, throw Astro.redirect('/blog') or return `Astro.response.status = 404`. +Decision: implement runtime guard for resilience. + +### 4.4 Shared Post Mapping Utility +Create `src/utils/posts.js`: +```js +import { parse, isBefore } from 'date-fns'; +export function loadBlogPosts(globPattern = './posts/*.mdx') { /* returns sorted normalized array */ } +``` +Supports options: `{ limit?, includeDrafts? }` (future). + +### 4.5 Pager Truncation (Optional Feature Flag) +Behavior when pages > 7: +`1 2 3 … 10 11 12` or `1 … 5 6 7 … 20` depending on current page. +Config flag in `theme.config.js`: +```js +pagination: { pageSize: 10, truncate: true, window: 2 } +``` + +### 4.6 Accessibility Pass +- Ensure nav has `role="navigation"` + `aria-label="Blog pagination"` if multiple navs present. +- Add `aria-disabled` for non-clickable ellipsis buttons if truncation used. + +### 4.7 Tests / Validation (Lightweight) +- Add unit test for helper (sorting order + date parsing resilience when date missing). +- Add slug stability test if reusing slugify for something new. + +### 4.8 Documentation +- Update `docs/architecture.md` pagination section. +- Add `docs/pagination.md` with examples & SEO notes. +- Add migration note: “If you previously linked to /blog/page/1 update to /blog.” + +### 4.9 Performance Considerations +- If post count grows: consider lazy importing frontmatter only (Astro.glob currently full load) — future phase. + +## 5. Implementation Order (Recommended) +1. Extract helper (no functional change). +2. Add canonical + prev/next tags. +3. Add invalid page guard. +4. Implement truncation (optional, behind flag). +5. Accessibility adjustments. +6. Tests & docs. + +## 6. Acceptance Criteria +- Page 1 has canonical `/blog` and no `prev`. +- Page N has canonical `/blog/page/N` plus correct `prev/next`. +- Visiting `/blog/page/999` with only 3 pages returns 404 or redirects (documented). +- Helper returns identical data as prior inline logic (verified by length & first/last entry comparison). +- Lighthouse SEO score unchanged or improved. +- No extra JS shipped for passive pages (pagination = static links only). + +## 7. Risks & Mitigations +| Risk | Mitigation | +|------|------------| +Canonical misconfiguration | Add unit test snapshot for head output | +Truncation confusion | Off by default via config | +Future taxonomy integration changes data shape | Keep helper return stable surface | + +## 8. Out of Scope (For Now) +- RSS feed generation (handled in broader SEO phase). +- Search integration. +- Tag-based pagination. + +## 9. Scheduling Suggestion +Effort: ~0.5–1 day engineering + 0.25 day docs/test polish. + +## 10. Go / No-Go Checklist Pre-Work +| Item | Status | +|------|--------| +Blog pagination active | ✅ | +Config file present | ✅ | +Slug utility available | ✅ | + +--- +Approve this plan to proceed with refinement implementation in a dedicated sub-phase branch or continue on current feature branch per strategy. + +``` \ No newline at end of file diff --git a/astro-odyssey-backpack/astro-poster-boards/pb-v2-seo/PLAN_PREMIER_UPGRADE.md b/astro-odyssey-backpack/astro-poster-boards/pb-v2-seo/PLAN_PREMIER_UPGRADE.md new file mode 100644 index 000000000..64384bca6 --- /dev/null +++ b/astro-odyssey-backpack/astro-poster-boards/pb-v2-seo/PLAN_PREMIER_UPGRADE.md @@ -0,0 +1,185 @@ +``` + ___ ____ _____ ____ ___ _ _ _ + / _ \/ ___|_ _| _ \ / _ \ _ _| |_ _ __ _ _ __| | ___ _ __ __| | ___ _ __ + | | | \___ \ | | | | | | | | | | | | __| '__| | | | / _` |/ _ \| '_ \ / _` |/ _ \| '__| + | |_| |___) || | | |_| | |_| | |_| | |_| | | |_| | | (_| | (_) | | | | (_| | (_) | | + \___/|____/ |_| |____/ \__\_\\__,_|\__|_| \__, | \__,_|\___/|_| |_|\__,_|\___/|_| + |___/ +``` + +# Premier Upgrade Plan – Astro Dark Business Theme (Reusable Template Evolution) + +> Status: DRAFT (awaiting approval) +> Scope: Remaining feature set to elevate the theme from “adapted fork” to a polished, reusable, extensible Astro business template. + +## 1. Objectives + +1. Unify content systems (Blog, Solutions, Industries) under a consistent taxonomy & relationship model. +2. Add production-grade enhancements: pagination, filtering, search, structured data, RSS, performance budgets. +3. Provide first-class documentation & developer experience (DX) with automation scripts. +4. Package the theme as a reusable template (internal + optional public distribution) without upstream fork ties. +5. Establish governance: branching strategy, release versioning, CI hooks, quality gates. + +## 2. High-Level Architecture (Target) + +```mermaid +flowchart TD + Author[Author adds MDX] --> ContentLayer[Glob + Normalizers] + ContentLayer --> TaxonomyIndex[Taxonomy Index Builder] + TaxonomyIndex --> Pages[Listing / Paginated Views] + TaxonomyIndex --> Relationships[Reverse Links] + Pages --> SEO[SEO + JSON-LD] + Relationships --> Render[Detail Layout Enhancement] + SearchIndexer[Search Index Build] --> RuntimeSearch[Client/Server Search] + ContentLayer --> SearchIndexer +``` + +## 3. Feature Breakdown + +| Feature | Description | Priority | Notes | +|---------|-------------|----------|-------| +| Pagination | Page through large listings (Blog, Solutions, Industries) | High | Static route generation with predictable URL pattern `/page/2` | +| Unified Taxonomy | Single tag/category model across all content types | High | Optional distinct scopes (`tagType`) later | +| Reverse Linking | Auto compute solution ↔ industry ↔ blog references | High | Deterministic build-time graph | +| Filtering | Multi-select filters (tags, industries, solutions) | Medium | Query param based (`?tags=a,b&industry=healthcare`) | +| Search | Lightweight static JSON search index + fuzzy client filter | Medium | Avoid large libs; optional Lunr/FlexSearch | +| RSS Feeds | Blog + Solutions (optional) feed | Medium | Atom/RSS standardized | +| JSON-LD | Structured data for Articles, Products (solutions), Industries (custom/Thing) | High | In layout head slots | +| Sitemap Enhancements | Segment priority & changefreq | Low | Config-based weights | +| Performance Budgets | Build script asserts max bundle & image sizes | Medium | Fails CI over threshold | +| Theming Tokens 2.0 | Formal design tokens (colors, spacing, radii, typography) | Medium | JSON source → CSS vars emit | +| CLI Scaffolder | `pnpm exec theme-cli new solution` | Medium | Template MDX generator | +| Config Centralization | `theme.config.(js|mjs)` for toggles (rss, search, etc.) | High | Single source of truth | +| DX Docs Overhaul | Full docs site MD content + diagrams | High | ASCII + Mermaid + usage playbooks | +| Release/Versioning | Conventional commits + CHANGELOG | Medium | Standard semver tagging | +| QA Workflows | Markdown lint, link check, accessibility scan | Medium | GitHub Actions | + +## 4. Phased Roadmap + +| Phase | Title | Scope | Exit Criteria | +|-------|-------|-------|---------------| +| 0 | Baseline & Inventory | Capture current content & metrics | Snapshot documented | +| 1 | Pagination | Implement for all three listing types | `/blog/page/2` works & tests pass | +| 2 | Taxonomy Core | Unified tag model + migration notes | Tags render across sections | +| 3 | Relationship Graph | Auto reverse links + relation blocks | Cross-link blocks visible | +| 4 | Filters & Search | Query filters + local search index | Combined filters functional | +| 5 | SEO & Structured | JSON-LD, enhanced meta, RSS, sitemap weights | Validation via Lighthouse & Rich Results | +| 6 | Theming & Tokens | Token source + CSS generation pipeline | Tokens compiled & docs updated | +| 7 | Docs & DX | New docs suite + CLI scaffolder | Dev can onboard <15 min | +| 8 | Packaging & Release | Versioning, changelog, distribution strategy | v1.0.0 tag & release notes | +| 9 | Quality Gates | CI checks (lint, accessibility, perf) | All enforced in PRs | +| 10 | Hardening & Polish | Edge case tests, refactors, cleanup | Zero known P1 defects | + +## 5. Detailed Specs + +### 5.1 Pagination +- Pattern: `/blog/page/2`, `/solutions/page/3`, `/industries/page/2`. +- Page size configurable: `theme.config.js` (default 10). +- Implementation: Build-time chunking -> dynamic collection arrays. + +### 5.2 Unified Taxonomy Model +Data shape (TypeScript style): +```ts +type TaxonomyEntry = { + slug: string; + label: string; + type: 'tag'; // future: category, segment + contentRefs: string[]; // URLs referencing +}; +``` +Stored as static JSON emitted to `dist/_data/taxonomy.json` for reuse. + +### 5.3 Relationship Graph +Graph build step: +```mermaid +graph LR + Solution --> Industry + Industry --> Solution + BlogPost --> Solution + BlogPost --> Industry +``` +Algorithm: parse frontmatter arrays; derive reverse edges; output adjacency map. + +### 5.4 Filters +Approach: No heavy client framework; hydrate minimal filter component via Astro islands or pure progressive enhancement. +URL query parsing → filter config object → in-memory filter on preloaded JSON index. + +### 5.5 Search +Option A: Prebuilt JSON index (title, excerpt, tags). +Option B (deferred): Lunr or FlexSearch for scoring. + +### 5.6 SEO & Structured Data +Layouts inject JSON-LD: +```json +{ + "@context": "https://schema.org", + "@type": "Article", + "headline": "...", + "datePublished": "...", + "keywords": "tag1, tag2" +} +``` + +### 5.7 Design Tokens +Source: `tokens.json` → build script → `:root { --color-primary: ... }`. +Potential future: Style dictionary integration (optional). + +### 5.8 CLI Scaffolder +Commands: +``` +theme-cli new solution "Data Orchestration" +theme-cli new industry "Logistics" +theme-cli new blog-post "Title Here" +``` +Outputs MDX template with frontmatter stub. + +### 5.9 Config Centralization +`theme.config.js` export: +```js +export default { + pagination: { pageSize: 10 }, + features: { search: true, rss: true, taxonomy: true }, + seo: { siteName: 'Dark Business Theme' } +}; +``` + +### 5.10 CI & Quality +- Lint: markdownlint + prettier check. +- Links: Dead link checker script. +- Perf: Lighthouse CI (budget JSON). +- A11y: Pa11y (key templates) or axe script. + +## 6. Risks & Mitigations +| Risk | Impact | Mitigation | +|------|--------|------------| +| Taxonomy explosion | Complexity in UI | Flat tag model initially | +| Build time growth | Longer CI cycles | Cache normalized JSON, incremental rebuild later | +| Over-optimization early | Delays shipping | Phase gating; strict acceptance per phase | +| SEO regressions | Traffic loss | Add comparison Lighthouse/structured test in CI | + +## 7. Acceptance Criteria (Global) +1. All features toggle-able via config. +2. No hydration added unless feature enabled. +3. Lighthouse Performance ≥ 95 after additions. +4. Documentation onboarding time target: < 15 minutes. +5. Release process documented & repeatable. + +## 8. Deliverables Inventory +- New config module. +- Taxonomy + relationships JSON artifacts. +- Search index builder script. +- CLI scaffolder. +- Extended docs set (Architecture, Authoring, Theming, Deployment, Contribution, DX Guide). +- CI workflows. + +## 9. Post-1.0 Backlog (Not in Current Scope) +- Multi-language (i18n) support. +- Image CDN integration. +- Analytics abstraction. +- Theme marketplace packaging. + +## 10. Approval +Sign-off needed before implementation begins. + +--- +> Provide feedback or APPROVE to proceed with task execution phase. diff --git a/astro-odyssey-backpack/astro-poster-boards/pb-v2-seo/TASKS_PREMIER_UPGRADE.md b/astro-odyssey-backpack/astro-poster-boards/pb-v2-seo/TASKS_PREMIER_UPGRADE.md new file mode 100644 index 000000000..a83d052aa --- /dev/null +++ b/astro-odyssey-backpack/astro-poster-boards/pb-v2-seo/TASKS_PREMIER_UPGRADE.md @@ -0,0 +1,109 @@ +``` + _____ _ _ _____ _ _ +|_ _| |__ ___ | |_ ___ |_ _|__ ___ | |__ ___ | |_ ___ _ __ + | | | '_ \ / _ \ | __/ _ \ ____ | |/ _ \ / _ \ | '_ \ / _ \| __/ _ \ '__| + | | | | | | __/ | || (_) |____|| | (_) | __/ | | | | (_) | || __/ | + |_| |_| |_|\___| \__\___/ |_|\___/ \___| |_| |_|\___/ \__\___|_| +``` + +# Task Breakdown – Premier Upgrade (Pending Approval) + +## Phase 0 – Baseline & Inventory +- [ ] Capture current counts (blog posts, solutions, industries) +- [ ] Record current Lighthouse scores +- [ ] Document current nav + config points + +## Phase 1 – Pagination +- [ ] Add `theme.config.js` with pagination.pageSize +- [ ] Implement generic paginate util +- [ ] Refactor blog listing → paginated +- [ ] Refactor solutions listing → paginated +- [ ] Refactor industries listing → paginated +- [ ] Add page navigation component +- [ ] Edge test: empty final page redirect + +## Phase 2 – Unified Taxonomy +- [ ] Introduce taxonomy collector script +- [ ] Parse all MDX frontmatter tags +- [ ] Normalize + slugify tags (reuse slugify) +- [ ] Emit `taxonomy.json` +- [ ] Update layouts to link tags to `/tags/` (global tag hub?) +- [ ] Create `/tags/index.astro` + dynamic tag pages +- [ ] Backfill blog tag logic → new system + +## Phase 3 – Relationship Graph +- [ ] Build `relationships.json` (solutions ↔ industries ↔ posts) +- [ ] Inject related blocks in Solution layout +- [ ] Inject related blocks in Industry layout +- [ ] Optional: show related solutions in blog posts if tags match + +## Phase 4 – Filters & Search +- [ ] Add lightweight JSON listing export per collection +- [ ] Implement client module for filtering (no framework) +- [ ] Add filter UI (checkbox/tag chips) +- [ ] Build search index (title/excerpt/tags) +- [ ] Implement fuzzy search (simple scoring) +- [ ] Progressive enhancement fallback (server full list) + +## Phase 5 – SEO & Structured Data +- [ ] Add JSON-LD generator helper +- [ ] Inject Article schema (blog) +- [ ] Inject Product/Service schema (solutions) +- [ ] Inject Thing/Organization schema (industries) +- [ ] Add RSS feed generation scripts +- [ ] Enhance sitemap with priorities + +## Phase 6 – Theming Tokens 2.0 +- [ ] Create `tokens.json` +- [ ] Build script → `generated/tokens.css` +- [ ] Replace hard-coded CSS vars where appropriate +- [ ] Document token usage + +## Phase 7 – Docs & Developer Experience +- [ ] Create `/docs/` directory structure +- [ ] Architecture Overview (mermaid + diagrams) +- [ ] Authoring Guide (MDX conventions, taxonomy) +- [ ] Theming Guide 2.0 (tokens, overrides) +- [ ] SEO & Performance Playbook +- [ ] Contribution & Release Workflow guide +- [ ] Add ASCII art headers aesthetic consistency +- [ ] Add script to validate docs links + +## Phase 8 – Packaging & Release +- [ ] Add Conventional Commits lint (optional commitlint config) +- [ ] Add CHANGELOG generator script +- [ ] Define version bump procedure +- [ ] Optional: prepare `create-astro-business` template metadata + +## Phase 9 – Quality Gates / CI +- [ ] Add GitHub Action: build + lint + test +- [ ] Add markdownlint & link checker action +- [ ] Add Lighthouse CI (budget file) +- [ ] Add accessibility scan (axe or pa11y) +- [ ] Add size-limit / bundle analyzer report + +## Phase 10 – Hardening & Polish +- [ ] Audit slugs for collisions +- [ ] Add 404 coverage for tag/filters/pagination edge cases +- [ ] Add basic unit tests for utils (slugify, paginate) +- [ ] Refactor any duplication in list rendering +- [ ] Final performance re-measure + +## Global Tasks (Cross-Phase) +- [ ] Update README to reflect new capabilities post-launch +- [ ] Add migration notes for earlier adopters +- [ ] Add issue templates (feature, bug, docs) + +## Stretch / Deferred +- [ ] i18n skeleton +- [ ] Image optimization pipeline integration +- [ ] CLI plugin distribution + +## Acceptance Gate Checklist +- [ ] Config toggles disable each major feature cleanly +- [ ] No runtime JS added when search & filters off +- [ ] Production build passes budgets +- [ ] Documentation index complete + +--- +> APPROVE to proceed or annotate with changes. diff --git a/astro-odyssey-backpack/astro-sc-odyssey-docs/ASTRO_ODYSSEY_API_DOCUMENTATION.md b/astro-odyssey-backpack/astro-sc-odyssey-docs/ASTRO_ODYSSEY_API_DOCUMENTATION.md new file mode 100644 index 000000000..d7fc936fd --- /dev/null +++ b/astro-odyssey-backpack/astro-sc-odyssey-docs/ASTRO_ODYSSEY_API_DOCUMENTATION.md @@ -0,0 +1,831 @@ +# Astro Odyssey Theme - Complete API Documentation + +## Table of Contents + +1. [Configuration System](#configuration-system) +2. [Core Components](#core-components) +3. [Section Components](#section-components) +4. [Form Components](#form-components) +5. [Blog Components](#blog-components) +6. [UI Elements](#ui-elements) +7. [Integration Patterns](#integration-patterns) +8. [Custom CSS Variables](#custom-css-variables) + +--- + +## Configuration System + +The theme uses three main configuration files that control site behavior: + +### `/src/config/settings.js` + +**Purpose**: Global site settings and theme configuration + +```javascript +export default { + title: string, // Page title for SEO + description: string, // Meta description + url: string, // Base URL (no trailing slash) + name: string, // Brand/business name + enableThemeSwitcher: boolean, // Enable/disable theme switching + showPlug: boolean // Show/hide footer plug +} +``` + +**Example Configuration**: +```javascript +export default { + title: "My Business | Professional Services", + description: "Expert solutions for modern businesses", + url: "https://mybusiness.com", + name: "My Business", + enableThemeSwitcher: true, + showPlug: false +} +``` + +### `/src/config/nav.js` + +**Purpose**: Navigation menu configuration + +```javascript +export const nav = [ + { + title: string, // Display text + slug: string // URL path + } +] +``` + +### `/src/config/footer.js` + +**Purpose**: Footer links and social media configuration + +```javascript +export const footerSocials = [ + { + name: string, // Platform name + url: string, // Profile URL + icon: string // Icon name (from Iconify) + } +] + +export const footerLists = [ + { + title: string, // Section title + items: [ + { + title: string, // Link text + slug: string // URL path + } + ] + } +] +``` + +--- + +## Core Components + +### Container + +**File**: `/src/components/core/Container.astro` + +**Purpose**: Provides consistent content width and padding throughout the site + +**Props**: +- `narrow?: boolean` - Use narrow container width + +**Slots**: +- Default slot - Content to be contained + +**Usage**: +```astro + +

Full width container content

+ + + +

Narrow container content

+ +``` + +### Header + +**File**: `/src/components/core/Header.astro` + +**Purpose**: Site header with responsive navigation + +**Props**: +- `navData?: Array` - Navigation items array +- `rightMenu?: boolean` - Position menu on the right + +**Slots**: +- `logo` - Logo/brand element +- `nav` - Custom navigation (overrides navData) +- `action-item` - Action button or element + +**Usage**: +```astro +--- +import { nav } from '../config/nav.js'; +--- + +
+ + +
+``` + +### Footer + +**File**: `/src/components/core/Footer.astro` + +**Purpose**: Site footer with links and social media + +**Props**: +- `footerSocials: Array` - Social media links +- `footerLists: Array` - Footer link sections +- `copyrightName: string` - Copyright holder name +- `background?: string` - Custom background color +- `color?: string` - Custom text color +- `showPlug?: boolean` - Show/hide theme plug (default: true) + +**Slots**: +- `logo` - Footer logo + +**Usage**: +```astro +--- +import { footerSocials, footerLists } from '../config/footer.js'; +--- + +
+ +
+``` + +--- + +## Section Components + +### Hero Sections + +#### HeroSection + +**File**: `/src/components/sections/heros/HeroSection.astro` + +**Purpose**: Generic two-column hero layout + +**Props**: None + +**Slots**: +- `text-container` - Hero text content +- `image-container` - Hero image content + +**Usage**: +```astro + +
+

Welcome to Our Platform

+

Revolutionary solutions for modern businesses

+ +
+
+ Hero +
+ +``` + +#### TextAndImageHero + +**File**: `/src/components/sections/heros/TextAndImageHero.astro` + +**Purpose**: Two-column hero with optional reverse layout + +**Props**: +- `reversed?: boolean` - Reverse text/image order + +**Slots**: +- `text-container` - Text content +- `btns-container` - Button group +- `image-container` - Image content + +**Usage**: +```astro + +
+

Innovation Starts Here

+

Cutting-edge technology meets user-friendly design

+
+
+ + +
+
+ Product +
+ +``` + +### Content Sections + +#### TextSection + +**File**: `/src/components/sections/TextSection.astro` + +**Purpose**: Simple text content section with optional narrow width + +**Props**: +- `narrow?: boolean` - Use narrow container + +**Slots**: +- Default slot - Text content + +**Usage**: +```astro + +

About Our Mission

+

We believe in creating solutions that make a difference...

+ +``` + +#### TextCardSection + +**File**: `/src/components/sections/TextCardSection.astro` + +**Purpose**: Elevated text section with card styling + +**Props**: +- `surfaceNumber?: number` - Surface theme number (default: 1) + +**Slots**: +- Default slot - Card content + +**Usage**: +```astro + +

Featured Content

+

This content appears in an elevated card style

+ +``` + +#### ThreeColumnTextSection + +**File**: `/src/components/sections/ThreeColumnTextSection.astro` + +**Purpose**: Three-column responsive layout for features or services + +**Props**: None + +**Slots**: +- `column-1-body` - First column content +- `column-1-cta` - First column CTA +- `column-2-body` - Second column content +- `column-2-cta` - Second column CTA +- `column-3-body` - Third column content +- `column-3-cta` - Third column CTA + +**Usage**: +```astro + +
+

Feature 1

+

Description of first feature

+
+ + +
+

Feature 2

+

Description of second feature

+
+ + +
+

Feature 3

+

Description of third feature

+
+ + +``` + +#### StickyTextImageSection + +**File**: `/src/components/sections/StickyTextImageSection.astro` + +**Purpose**: Text and image layout with sticky image behavior + +**Props**: +- `reversed?: boolean` - Reverse text/image positions + +**Slots**: +- `text-container` - Text content (can be long) +- `image-container` - Image that becomes sticky + +**Usage**: +```astro + +
+

Detailed Feature Overview

+

Long form content that scrolls while image stays in view...

+ +
+
+ Feature +
+ +``` + +#### CtaCardSection + +**File**: `/src/components/sections/CtaCardSection.astro` + +**Purpose**: Call-to-action section with card styling + +**Props**: +- `background?: string` - Custom background color +- `color?: string` - Custom text color + +**Slots**: +- Default slot - CTA content + +**Usage**: +```astro + +

Ready to Get Started?

+

Join thousands of satisfied customers today

+ + +``` + +#### CustomerQuoteSection + +**File**: `/src/components/sections/CustomerQuoteSection.astro` + +**Purpose**: Customer testimonial with quote styling + +**Props**: +- `quoteText: string` - The testimonial quote +- `customerName: string` - Customer name for attribution + +**Usage**: +```astro + +``` + +#### YouTubeEmbedSection + +**File**: `/src/components/sections/YouTubeEmbedSection.astro` + +**Purpose**: YouTube video embed with responsive container + +**Props**: +- `url: string` - YouTube video URL +- `rounded?: boolean` - Apply rounded corners + +**Usage**: +```astro + +``` + +--- + +## Form Components + +### Form Fields + +#### FormInput + +**File**: `/src/components/form-fields/FormInput.astro` + +**Purpose**: Input field with consistent styling + +**Props**: +- `type?: string` - Input type (default: "text") +- `label?: string` - Field label +- `name: string` - Input name attribute +- `placeholder?: string` - Placeholder text +- `required?: boolean` - Required field validation + +**Usage**: +```astro + +``` + +#### FormSelect + +**File**: `/src/components/form-fields/FormSelect.astro` + +**Purpose**: Select dropdown with consistent styling + +**Props**: +- `label?: string` - Field label +- `name: string` - Select name attribute +- `options: Array` - Option values and labels +- `required?: boolean` - Required field validation + +**Usage**: +```astro + +``` + +#### FormTextarea + +**File**: `/src/components/form-fields/FormTextarea.astro` + +**Purpose**: Textarea field with consistent styling + +**Props**: +- `label?: string` - Field label +- `name: string` - Textarea name attribute +- `placeholder?: string` - Placeholder text +- `rows?: number` - Number of visible rows (default: 4) +- `required?: boolean` - Required field validation + +**Usage**: +```astro + +``` + +### Complete Forms + +#### ContactForm + +**File**: `/src/components/forms/ContactForm.astro` + +**Purpose**: Ready-to-use contact form with all standard fields + +**Props**: None (uses internal configuration) + +**Usage**: +```astro + +``` + +**Form Fields**: +- Name (text input) +- Email (email input) +- Source (select dropdown) +- Message (textarea) +- Submit button + +#### NewsletterForm + +**File**: `/src/components/forms/NewsletterForm.astro` + +**Purpose**: Simple email collection form + +**Props**: None + +**Usage**: +```astro + +``` + +--- + +## Blog Components + +#### BlogPostsList + +**File**: `/src/components/blog/BlogPostsList.astro` + +**Purpose**: Grid layout for blog post previews + +**Props**: +- `posts: Array` - Array of post objects + +**Post Object Structure**: +```typescript +{ + href: string, // Post URL + title: string, // Post title + featuredImage: string, // Image URL + excerpt?: string // Optional excerpt +} +``` + +**Usage**: +```astro +--- +const posts = [ + { + href: "/blog/post-1", + title: "First Blog Post", + featuredImage: "/images/post1.jpg", + excerpt: "Brief description..." + } +]; +--- + + +``` + +#### BlogPostPreview + +**File**: `/src/components/blog/BlogPostPreview.astro` + +**Purpose**: Individual blog post preview card (used internally by BlogPostsList) + +**Props**: +- `post: Object` - Post data object + +--- + +## UI Elements + +### Button + +**File**: `/src/components/buttons/Button.astro` + +**Purpose**: Versatile button component with multiple variants + +**Props**: +- `href?: string` - Link URL (renders as `` instead of ` + + + + + + + + + + + + + + + +``` + +### FeatureCard + +**File**: `/src/components/cards/FeatureCard.astro` + +**Purpose**: Card component for showcasing features or products + +**Props**: +- `href: string` - Link destination +- `imgSrc: string` - Image path (without extension) +- `title: string` - Card title + +**Usage**: +```astro + +``` + +**Note**: Component automatically handles WebP/PNG fallbacks by appending `.webp` and `.png` extensions. + +### YouTubeEmbed + +**File**: `/src/components/core/YouTubeEmbed.astro` + +**Purpose**: Responsive YouTube video embed + +**Props**: +- `url: string` - YouTube video URL +- `rounded?: boolean` - Apply rounded corners +- `loading?: string` - Loading strategy (default: "lazy") + +**Usage**: +```astro + +``` + +### Logo + +**File**: `/src/components/Logo.astro` + +**Purpose**: Simple text-based logo component + +**Props**: None + +**Usage**: +```astro + +``` + +**Customization**: Edit the component file to replace with your own logo design. + +--- + +## Integration Patterns + +### Common Layout Patterns + +#### Basic Page Layout +```astro +--- +import { Container, Header, Footer } from '@components/odyssey-theme'; +import { nav } from '../config/nav.js'; +import { footerSocials, footerLists } from '../config/footer.js'; +--- + +
+ +
+ +
+ + + +
+ +
+ +
+``` + +#### Landing Page Pattern +```astro + + +

Why Choose Us

+

Compelling value proposition...

+ + + + + + +

Ready to Start?

+ + +``` + +### Form Integration +```astro + +

Contact Us

+ + + + +
+ + + + + +``` + +### Theme Switching Integration +```astro +--- +import { ThemeSwitcher } from '../components/theme-switcher/theme-switcher'; +import settings from '../config/settings.js'; +--- + +{settings.enableThemeSwitcher && ( + +)} +``` + +--- + +## Custom CSS Variables + +The theme uses CSS custom properties for consistent theming: + +### Layout Variables +```css +--container-max-width +--container-max-width-narrow +--container-padding +--section-margin +--navbar-height +``` + +### Theme Colors +```css +--theme-primary +--theme-primary-hover +--theme-on-primary +--theme-bg +--theme-on-bg +--theme-surface-1 +--theme-on-surface-1 +``` + +### Typography +```css +--theme-font-family-sans +--theme-font-family-serif +--font-size-sm +--font-size-md +--font-size-lg +``` + +### Form Styling +```css +--form-field-border-color +--form-field-border-focus-color +--form-field-input-color +--form-field-border-radius +``` + +### Component Styling +```css +--theme-shape-radius +--theme-button-border-radius +--theme-transition +``` + +### Using Custom Variables +```astro + +``` + +--- + +## Dependencies + +The theme requires these packages: + +- **Astro**: `^4.15.9` - Core framework +- **astro-icon**: `^1.1.0` - Icon system using Iconify +- **@iconify-json/ic**: `^1.1.17` - Material Design icons +- **@iconify-json/mdi**: `^1.1.64` - Material Design icons +- **@astrojs/lit**: `^4.0.1` - Lit components support +- **@astrojs/mdx**: `^2.1.1` - MDX support +- **lit**: `^3.1.2` - Web components + +### Icon Usage +Icons use the Iconify system. Common icon patterns: +```astro +--- +import { Icon } from 'astro-icon/components'; +--- + + + + +``` + +--- + +This documentation covers all components in the Astro Odyssey Theme. Each component is designed to be composable and customizable through props and slots, following Astro's component patterns for maximum flexibility and reusability. \ No newline at end of file diff --git a/astro-odyssey-backpack/astro-sc-odyssey-docs/CLAUDE.md b/astro-odyssey-backpack/astro-sc-odyssey-docs/CLAUDE.md new file mode 100644 index 000000000..ea5b2582a --- /dev/null +++ b/astro-odyssey-backpack/astro-sc-odyssey-docs/CLAUDE.md @@ -0,0 +1,90 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +This is the Odyssey Theme, a modern Astro-based marketing website theme designed for startups and businesses. It's a fully-featured theme with landing pages, blog functionality, contact forms, and comprehensive theming system. + +## Development Commands + +```bash +npm install # Install dependencies +npm start # Start development server (alias for npm run dev) +npm run dev # Start development server at localhost:4321 +npm run build # Build production site to ./dist/ +npm run preview # Preview production build locally +npm run format # Format code with Prettier +``` + +## Technology Stack + +- **Framework**: Astro v4.15.9 with TypeScript +- **Integrations**: MDX, Lit components, Sitemap, Icon system +- **Styling**: CSS custom properties with comprehensive theming system +- **Icons**: Astro Icon with Iconify JSON packages (@iconify-json/ic, @iconify-json/mdi) + +## Architecture & Structure + +### Configuration System +The theme uses a centralized configuration approach: +- `src/config/settings.js` - Global site settings, theme switcher control +- `src/config/nav.js` - Main navigation structure +- `src/config/footer.js` - Footer configuration +- `astro.config.mjs` - Astro integrations and site URL configuration + +### Component Architecture +Components are organized by functional category: +- `src/components/core/` - Essential layout components (Header, Footer, Navigation) +- `src/components/sections/` - Page section components +- `src/components/blog/` - Blog-specific components +- `src/components/forms/` - Contact forms and form fields +- `src/components/buttons/` - Button variations +- `src/components/cards/` - Card component variants +- `src/components/theme-switcher/` - Theme switching functionality + +### Layout System +Three primary layouts in `src/layouts/`: +- `Base.astro` - Core HTML structure and meta tags +- `Page.astro` - Standard page layout with navigation/footer +- `Post.astro` - Blog post layout with enhanced meta and structure + +### TypeScript Configuration +Uses path mapping for clean imports: +- `@config` → `src/config/*` +- `@components` → `src/components/*` +- `@layouts` → `src/layouts/*` +- `@styles` → `src/styles/*` +- `@utils` → `src/utils/*` +- `@icons` → `src/icons/*` + +### Theming System +The theme includes a comprehensive CSS custom property system: +- `src/styles/theme.css` - CSS custom properties for colors, spacing, typography +- `src/styles/global.css` - Global styles and component base styles +- Theme switcher component allows runtime theme changes +- Fully customizable design tokens + +### Page Structure +- File-based routing through `src/pages/` +- Blog functionality with MDX support +- Landing page examples +- Company pages (about, contact) +- Theme demonstration pages + +## Key Features + +- **Blog System**: Full-featured blog with MDX support and tagging +- **Contact Forms**: Pre-configured for Netlify, Formspree, Formspark +- **Theme Switching**: Runtime theme switching with CSS custom properties +- **SEO Optimized**: Open Graph, canonical URLs, sitemap generation +- **Performance**: Optimized for Lighthouse perfect scores +- **Responsive Design**: Mobile-first responsive layouts + +## Development Notes + +- The theme is designed to be easily customizable through the configuration files +- Icon system uses Astro Icon with Iconify for scalable icon management +- CSS architecture supports easy theme customization without touching component files +- MDX integration allows for rich content in blog posts +- Lit components provide enhanced interactivity where needed \ No newline at end of file diff --git a/astro-odyssey-backpack/astro-sc-odyssey-docs/DEPLOYMENT_GUIDE.md b/astro-odyssey-backpack/astro-sc-odyssey-docs/DEPLOYMENT_GUIDE.md new file mode 100644 index 000000000..5de802f47 --- /dev/null +++ b/astro-odyssey-backpack/astro-sc-odyssey-docs/DEPLOYMENT_GUIDE.md @@ -0,0 +1,795 @@ +# Astro Odyssey Theme - Deployment Guide + +## 🚀 Production Deployment Guide + +This guide covers deploying the Astro Odyssey Theme to various hosting platforms, with CI/CD setup, performance optimization, and production configuration. + +## 📋 Pre-Deployment Checklist + +### Essential Configuration +- [ ] Update `astro.config.mjs` with production site URL +- [ ] Configure environment variables for production +- [ ] Test all forms with production endpoints +- [ ] Verify all theme images are optimized +- [ ] Run production build locally and test +- [ ] Check all internal links and navigation +- [ ] Validate SEO meta tags and Open Graph data + +### Performance Verification +- [ ] Run Lighthouse audit (target: 90+ on all metrics) +- [ ] Test theme switching performance +- [ ] Verify image optimization and lazy loading +- [ ] Check CSS and JavaScript bundle sizes +- [ ] Test mobile responsiveness across devices + +## 🌐 Platform-Specific Deployment + +### Netlify Deployment + +#### Quick Deploy +```bash +# Install Netlify CLI +npm install -g netlify-cli + +# Build and deploy +npm run build +netlify deploy --prod --dir=dist +``` + +#### Netlify Configuration +Create `netlify.toml` in project root: + +```toml +[build] + publish = "dist" + command = "npm run build" + +[build.environment] + NODE_VERSION = "18" + +[[redirects]] + from = "/*" + to = "/404" + status = 404 + +[[headers]] + for = "/assets/*" + [headers.values] + Cache-Control = "public, max-age=31536000, immutable" + +[[headers]] + for = "*.css" + [headers.values] + Cache-Control = "public, max-age=31536000, immutable" + +[[headers]] + for = "*.js" + [headers.values] + Cache-Control = "public, max-age=31536000, immutable" + +# Form handling +[context.production] + environment = { NODE_ENV = "production" } +``` + +#### Netlify Forms Integration +Update contact forms: + +```astro + +
+ + + + + + +