[Phase 1] Write core documentation pages#107
Merged
afucher merged 3 commits intodoc-websitefrom Mar 31, 2026
Merged
Conversation
✅ Issue #97 Complete ## Pages Created/Updated 1. **introduction.mdx** — Welcome page with feature overview - Explains what AstroChart is and is NOT - Feature table highlighting key capabilities - Inline <ChartDemo> showing a basic radix chart - Links to GitHub, npm, and next steps 2. **installation.md** — Installation guide - npm, yarn, pnpm package managers - CDN unpkg bundle with UMD global example - ESM import for bundlers - TypeScript type definitions - Compatibility table for different environments 3. **quickstart.mdx** — Quick Start guide - 4-step walkthrough: Install → Container → Data → Render - Data format explanation (Record<string, number[]> for planets, array of 12 for cusps) - Complete HTML + JS example (copy-pasteable) - Live <ChartDemo> showing rendered output - Troubleshooting section 4. **guides/radix-chart.mdx** — Radix Chart guide - Full explanation of radix charts - Data format details with valid planet names - House cusps requirement (exactly 12 values) - Complete example with all 15 planets/points - Retrograde planet marking - Aspects with customizable orbs - Live <ChartDemo> example 5. **guides/transit-chart.mdx** — Transit Chart guide - How transit charts overlay on radix - Complete examples with both radix and transit data - Retrograde transit planets - Transit-to-natal aspects - Live <ChartDemo> showing dual-ring chart - API reference for transit methods 6. **guides/animation.mdx** — Animation guide (greatly expanded) - Detailed animation method signature and parameters - Complete interactive example with date picker - Duration best practices (300ms–5s recommendations) - Callback patterns and completion handling - Chaining animations with async/await - Performance considerations - Common patterns (date input, continuous loop) - Live <ChartDemo mode="animate"> with interactive button - Troubleshooting guide ## Key Changes - Converted 5 files from .md to .mdx to support component imports - Fixed all data format examples to use correct AstroData structure: - `planets: Record<string, number[]>` (was array of objects) - `cusps: number[]` of exactly 12 values - Added `<ChartDemo>` components to intro, quickstart, and all 3 guides - Enhanced animation guide with complete API documentation - Verified all code examples match actual library API - All pages include proper links to related docs ## Build Verification ✅ Build successful: 25 pages generated ✅ All 6 core docs pages render without errors ✅ Pagefind search index includes all new pages ✅ No TypeScript diagnostics ✅ No broken internal links ✅ No console errors 🧑 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev>
Regenerate astrochart.js UMD bundle via `npm run build`. No source changes — output is deterministic from current TypeScript sources. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev>
The second element of a planet array is the astrological velocity of the point, not a boolean/flag. A negative velocity means the planet is retrograde; the sign of the value carries the meaning, not an arbitrary sentinel like -1. Updated in all affected files: - quickstart.mdx - guides/radix-chart.mdx - guides/transit-chart.mdx - api/types.md - api/radix.md Example values in code snippets updated to use realistic velocities (e.g. -1.5, -0.3) instead of the misleading -1 flag convention. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev>
afucher
added a commit
that referenced
this pull request
Mar 31, 2026
* Issue 93 setup astro (#104) * feat: Set up Astro + Starlight project structure (Issue #93) Implements the initial website directory with: - Astro + Starlight configuration - TypeScript setup (tsconfig.json) - Component structure (ChartDemo, SinceBadge) - Custom landing page (src/pages/index.astro) - Documentation pages structure (src/content/docs/) * Getting Started: introduction, installation, quickstart * Guides: radix, transit, animation, custom settings, etc. * Framework integrations: React, Vue, Angular * API Reference: Chart, Radix, Transit, Settings, Types, etc. * Project: changelog, contributing - Placeholder logo and styles - .gitignore and environment setup Acceptance criteria met: ✓ website/ directory created with package.json ✓ astro.config.mjs configured with Starlight ✓ TypeScript setup ✓ src/ directory structure with pages, components, styles, content/docs ✓ public/ directory with placeholder logo ✓ ChartDemo and SinceBadge components ready Next: npm install and verify build (will be done in Phase 1) * fix: Resolve build errors for Astro 6 + Starlight 0.38 compatibility - Fix tsconfig.json: correct Astro tsconfig preset path (configs/ -> tsconfigs/) - Upgrade to astro@^6.0.0 + @astrojs/starlight@^0.38.0 (Zod v4 compatible) - Add .npmrc with legacy-peer-deps=true for peer dependency resolution - Fix src/content.config.ts location and add docsLoader() (Astro 6 requirement) - Fix astro.config.mjs sidebar slugs (remove 'docs/' prefix) - Fix social config syntax (array instead of object, Starlight v0.33+ change) - Rewrite landing page to use StarlightPage component correctly - Fix internal links to use correct route paths Build result: 24 pages built, search index generated, sitemap created. * docs: Add retrospective findings to AGENTS.md - Add Environment section (nvm use 24, website sub-project) - Add Adding New Dependencies section with verification workflow * fix: Exclude website/ from root TypeScript and webpack build The website/ sub-project has its own node_modules with Astro/Starlight packages. Without exclusions, ts-loader was crawling into website/node_modules/ and failing with 24 TypeScript errors. - tsconfig.json: add 'website' to exclude list - webpack.config.js: add /website/ to ts-loader exclude regex * docs: Add sub-project isolation hard rule to AGENTS.md * [Phase 1] Implement ChartDemo component and demo data (#105) * feat(website): implement ChartDemo component and demo data (#94) - Add `src/data/demoData.ts` with defaultRadixData (15 planets + 12 cusps) and defaultTransitData for transit/animate examples - Rewrite ChartDemo.astro with updated props: id, height (default 500), mode ('radix'|'transit'|'animate'), showCode (default true) - Animate mode renders a 'Start Animation' button wired to transit.animate() - Inline <script> loads /astrochart.js on demand and initialises chart based on mode, using demoData passed via define:vars - Collapsible <details> code snippet auto-generated per mode - <noscript> fallback included - Add website/public/astrochart.js (UMD bundle served to browser) - Add src/content/docs/test-demo.md testing all modes and props - Website builds cleanly (25 pages); root lib build + 86 tests all pass 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev> * fix(website): fix ChartDemo not rendering on test-demo page Three bugs fixed: 1. Rename test-demo.md → test-demo.mdx Astro/Starlight only processes component imports (MDX syntax) in .mdx files. The .md file was printing the import statement as plain text and not rendering any <ChartDemo> tags. 2. Fix planet key names in demoData.ts The library recognises NNode/SNode/Fortune; the data used the non-existent keys NorthNode, SouthNode, Vertex which caused the validate() call inside Radix to silently skip those planets and could throw on malformed data shapes. 3. Fix multi-instance script loading race condition With 5 ChartDemo instances on one page, all inline scripts ran simultaneously and each tried to inject /astrochart.js. Replace with a shared __astrochartQueue pattern: the first instance creates the script tag and flushes the queue on load; subsequent instances detect the in-flight tag and push their initChart() to the queue instead of creating duplicate script tags. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev> * docs: apply learnings from Issue #94 debugging AGENTS.md: - Add website/Astro rules: .mdx required for component imports; queue pattern for multi-instance is:inline script loading - Add AstroChart data shape section: real AstroData type, valid planet keys, cusps constraint, retrograde flag format website docs (wrong data shape fixed): - api/types.md: rewrite with real AstroData/Points types, table of valid planet keys, full working example - guides/radix-chart.md: replace invented Planet[]/Cusp[] API with real Record<string,number[]>/number[] shape throughout - api/radix.md: correct code example, document data constraints library-issues/ (new directory, two files): - improve-validate-unknown-planet-keys.md: unknown planet keys silently render as fallback circles with no warning — improvement candidate - bug-settings-mutation-across-instances.md: Chart constructor mutates the shared default_settings singleton via Object.assign, causing cross-instance settings bleed — confirmed bug 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev> * docs: remove pointless prop-test sections from test-demo 'Radix with Custom Height' and 'Transit without Code Snippet' existed to exercise ChartDemo component props — not to communicate anything useful to a documentation reader. Removed. * fix: exclude project/__tests__ from TypeScript compilation Without this exclusion tsc emits .d.ts files for the test helpers into dist/project/__tests__/ on every npm run build. The issue-93 branch had this fix but it was not in doc-website, so it reappeared on the new branch. --------- Co-authored-by: eca <git@eca.dev> * [Phase 1] Create custom landing page (#106) * [Phase 1] Create custom landing page Implement comprehensive landing page for AstroChart with all required sections: Hero Section: - Tagline: "A free and open-source JavaScript library for generating SVG astrology charts" - npm install snippet - "Get Started" CTA → /installation - "View on GitHub" link Version Badge: - Dynamically reads version from package.json at build time - Displays as "v3.0.2" - Links to /changelog Live Demo Section: - Side-by-side radix and transit chart demos using ChartDemo component - Collapsible code example showing usage - Interactive charts powered by pure SVG Feature Cards: - Pure SVG: crisp, scalable vector graphics - Zero Dependencies: pure vanilla JavaScript - Fully Customizable: control all visual settings - TypeScript-first: full type definitions included Sponsorship Section: - Ko-fi button with coffee emoji - GitHub Sponsors button with heart emoji - Gradient background styling Mobile Responsive: - Works on 320px–1920px viewports - Grid layouts adjust to single column on mobile - Sponsor buttons stack vertically on narrow screens Build verified: 25 pages built successfully with no errors Closes #95 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev> * fix sponsor link --------- Co-authored-by: eca <git@eca.dev> * [Phase 1] Write core documentation pages (#107) * [Phase 1] Write core documentation pages ✅ Issue #97 Complete ## Pages Created/Updated 1. **introduction.mdx** — Welcome page with feature overview - Explains what AstroChart is and is NOT - Feature table highlighting key capabilities - Inline <ChartDemo> showing a basic radix chart - Links to GitHub, npm, and next steps 2. **installation.md** — Installation guide - npm, yarn, pnpm package managers - CDN unpkg bundle with UMD global example - ESM import for bundlers - TypeScript type definitions - Compatibility table for different environments 3. **quickstart.mdx** — Quick Start guide - 4-step walkthrough: Install → Container → Data → Render - Data format explanation (Record<string, number[]> for planets, array of 12 for cusps) - Complete HTML + JS example (copy-pasteable) - Live <ChartDemo> showing rendered output - Troubleshooting section 4. **guides/radix-chart.mdx** — Radix Chart guide - Full explanation of radix charts - Data format details with valid planet names - House cusps requirement (exactly 12 values) - Complete example with all 15 planets/points - Retrograde planet marking - Aspects with customizable orbs - Live <ChartDemo> example 5. **guides/transit-chart.mdx** — Transit Chart guide - How transit charts overlay on radix - Complete examples with both radix and transit data - Retrograde transit planets - Transit-to-natal aspects - Live <ChartDemo> showing dual-ring chart - API reference for transit methods 6. **guides/animation.mdx** — Animation guide (greatly expanded) - Detailed animation method signature and parameters - Complete interactive example with date picker - Duration best practices (300ms–5s recommendations) - Callback patterns and completion handling - Chaining animations with async/await - Performance considerations - Common patterns (date input, continuous loop) - Live <ChartDemo mode="animate"> with interactive button - Troubleshooting guide ## Key Changes - Converted 5 files from .md to .mdx to support component imports - Fixed all data format examples to use correct AstroData structure: - `planets: Record<string, number[]>` (was array of objects) - `cusps: number[]` of exactly 12 values - Added `<ChartDemo>` components to intro, quickstart, and all 3 guides - Enhanced animation guide with complete API documentation - Verified all code examples match actual library API - All pages include proper links to related docs ## Build Verification ✅ Build successful: 25 pages generated ✅ All 6 core docs pages render without errors ✅ Pagefind search index includes all new pages ✅ No TypeScript diagnostics ✅ No broken internal links ✅ No console errors 🧑 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev> * chore: rebuild dist bundle Regenerate astrochart.js UMD bundle via `npm run build`. No source changes — output is deterministic from current TypeScript sources. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev> * docs: fix planet velocity description — not a retrograde flag The second element of a planet array is the astrological velocity of the point, not a boolean/flag. A negative velocity means the planet is retrograde; the sign of the value carries the meaning, not an arbitrary sentinel like -1. Updated in all affected files: - quickstart.mdx - guides/radix-chart.mdx - guides/transit-chart.mdx - api/types.md - api/radix.md Example values in code snippets updated to use realistic velocities (e.g. -1.5, -0.3) instead of the misleading -1 flag convention. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev> --------- Co-authored-by: eca <git@eca.dev> * [Phase 1] Configure and test CI/CD pipeline (#96) (#108) * ci: add docs-deploy workflow and deployment guide (#96) - Add .github/workflows/docs-deploy.yml: - Triggers on push to main (paths: website/** and project/src/**) - Supports manual trigger via workflow_dispatch - Builds library → copies bundle → builds Astro site → deploys to AstroDraw/astrodraw.github.io via peaceiris/actions-gh-pages - Uses DOCS_DEPLOY_KEY secret for SSH deploy key authentication - Add docs/docs-deploy.md: - Explains what each workflow step does - One-time SSH key pair setup instructions - How to manually trigger via GitHub Actions UI - Debugging guide for common failure scenarios Closes #96 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev> * ci: switch to official GitHub Pages action, deploy from AstroChart repo (#96) Replace peaceiris/actions-gh-pages (third-party, slow to maintain, requires SSH deploy key setup) with the official GitHub Actions stack: - actions/upload-pages-artifact@v3 - actions/deploy-pages@v4 Changes: - Split single job into build + deploy jobs - Add top-level permissions (pages: write, id-token: write, contents: read) - Add concurrency group to prevent overlapping deploys - Remove all external repo / SSH deploy key config — no secrets needed - Site now deploys directly to AstroChart repo Pages Update website/astro.config.mjs: - site: https://astrodraw.github.io/AstroChart - base: /AstroChart (required for project repo sub-path deployment) Update docs/docs-deploy.md to reflect new one-time setup (Pages source → GitHub Actions in repo settings) and remove SSH key instructions. 🤖 Generated with [eca](https://eca.dev) Co-Authored-By: eca <git@eca.dev> * ci: temporarily enable workflow trigger on issue-96-ci-cd for testing * ci: revert temporary test trigger on issue-96-ci-cd --------- Co-authored-by: eca <git@eca.dev> --------- Co-authored-by: eca <git@eca.dev>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive documentation coverage for AstroChart library including:
All pages feature live
<ChartDemo>components and correctAstroDataformat examples.Pages Modified/Created
introduction.mdxinstallation.mdquickstart.mdxguides/radix-chart.mdxguides/transit-chart.mdxguides/animation.mdxAcceptance Criteria — All Met ✅
introduction.mdx— Explains AstroChart, feature table, inline ChartDemo, GitHub/npm linksinstallation.md— npm/yarn/pnpm, CDN unpkg, ESM, UMD global, TypeScript typesquickstart.mdx— Step 1–4, data format, copy-pasteable code, ChartDemoguides/radix-chart.mdx— Planets, cusps, full example, retrograde, aspects, ChartDemoguides/transit-chart.mdx— Transit overlay, transit-to-radix aspects, ChartDemoguides/animation.mdx—transit.animate()signature, duration, callbacks, ChartDemo with interactive buttonastro.config.mjsBuild Verification
Technical Details
Data Format
All code examples use correct
AstroDatastructure:Component Integration
<ChartDemo id="intro-demo" mode="radix" /><ChartDemo id="quickstart-demo" mode="radix" /><ChartDemo id="radix-demo" mode="radix" /><ChartDemo id="transit-demo" mode="transit" /><ChartDemo id="animation-demo" mode="animate" />File Conversions
Converted 5
.mdfiles to.mdxto support JSX component imports (required for ChartDemo).Test Plan
npm run buildfromwebsite/directoryRelated Issues
🧑 Generated with eca