本指南说明如何在真实 WordPress 网站上使用 FreeAstroAPI WordPress starter kit。
Starter kit 是 Astrology Suite for FreeAstroAPI WordPress plugin。它提供 Gutenberg blocks 和 shortcodes，可用于 natal charts、reports、simple sign tools 和 ephemeris tables。
官方插件页面：
Astrology Suite for FreeAstroAPI on WordPress.org
1. 安装并启用插件
在 WordPress 中打开 Plugins > Add New Plugin，搜索：
Astrology Suite for FreeAstroAPI安装后点击 Activate。
也可以从 WordPress.org 下载 ZIP 后手动上传：
Download the plugin from WordPress.org
启用后，WordPress 会添加设置页：
Settings > Astrology Suite插件也会在 WordPress block editor 中注册 Astrology Suite blocks。
2. 创建 FreeAstroAPI key
插件需要 FreeAstroAPI key 才能计算 chart 或 report。
创建免费账户：
然后打开 dashboard：
进入 API Keys，创建 key 并立即复制。完整 key 只显示一次。
保持 key 私密，不要放到公开页面、截图、GitHub issue 或 frontend JavaScript。
3. 在 WordPress 中保存 API key
打开：
Settings > Astrology Suite > API把 FreeAstroAPI key 粘贴到 API key 字段，点击 Save Changes。
注意：保存后 API key 字段可能看起来为空。这是正常的。留空表示继续使用已保存 key；如果要替换，则粘贴新 key。
插件从 WordPress 发送 API 请求。访客不会在浏览器中收到原始 API key。
4. 允许访客使用工具
仍在 Settings > Astrology Suite > API 中，检查 public access 设置。
如果希望访客无需登录即可使用 chart、report、simple sign 和 ephemeris forms，启用 Allow public calculations。
如果关闭，公开访客会看到访问提示而不是表单。私密会员站可以关闭，大多数公开占星工具应开启。
5. 选择 frontend language
Frontend language 控制插件界面文本，例如表单标签、按钮、loading message 和 status message。
选择访客要看到的语言，然后点击 Save Changes。
这个设置控制插件界面。解释文本取决于 FreeAstroAPI 对所选 endpoint 和 options 返回的内容。
6. 从 chart + report block 开始
打开你要放置占星工具的 WordPress 页面。
在 block editor 中点击 +，搜索：
Astrology Suite第一张公开页面建议使用：
Astrology Suite Chart + Report它会给访客一个表单，并显示 natal chart 和 interpretation report。
其他可用 blocks：
- Astrology Suite Chart Only
- Astrology Suite Report Only
- Astrology Suite Ephemeris
- Simple Sign: Sun
- Simple Sign: Moon
- Simple Sign: Rising
- Simple Sign: Midheaven
添加后发布或更新页面。
7. 测试公开页面
打开 frontend 页面，不要只看 editor preview。
对 natal chart 和 report blocks，用真实测试资料提交：
- Name
- Birth date
- Birth hour and minute
- Birth city
City 字段在输入至少两个字符后搜索。请选择下拉建议，这样插件能使用正确 timezone、latitude 和 longitude。
如果访客不知道出生时间，可以选择 I do not know my birth time。插件会按 unknown birth time 处理，无法安全计算的 time-dependent details 会被省略。
8. 选择 chart style
打开：
Settings > Astrology Suite > Custom Chart选择 preset chart theme 并保存。然后刷新公开页面，再提交一次测试。
推荐流程：
- 选择 preset chart theme。
- 保存设置。
- 测试公开页面。
- 基础流程工作后，再使用 advanced custom chart JSON。
之后如果要设计自定义样式，可以使用 FreeAstroAPI Chart Designer：
9. 配置报告长度和 sections
打开：
Settings > Astrology Suite > Report这个 tab 控制访客看到多少 report content。
新手常用设置：
- Report detail level
- Maximum planets shown
- Maximum aspects shown per section
- Whether ASC and MC sections are included
- Whether birth context is shown
- Whether tables are shown
- Whether chart print controls are visible
- Whether planet aspect links are shown
- Whether the thematic interpretation section is shown
先用默认值。页面太长时再降低限制。
如果启用 Show planet aspect links，planet sections 可以显示相关 aspect links。访客点击后，当 FreeAstroAPI 返回对应解释时，会打开 modal。
10. 使用 shortcodes
如果主题、classic editor、widget area 或 page builder 更适合 shortcodes，可以使用插件 shortcodes：
[astrology_suite mode="chart-report"]
[astrology_suite mode="chart-only"]
[astrology_suite mode="report-only"]
[astrology_suite_chart_only]
[astrology_suite_report_only]
[astrology_suite_chart_report]
[astrology_suite_simple_sign_sun include_interpretation="true"]
[astrology_suite_simple_sign_moon]
[astrology_suite_simple_sign_rising]
[astrology_suite_simple_sign_midheaven]
[astrology_suite_ephemeris]适合使用 shortcodes 的情况：
- 使用 classic editor。
- page builder 对 shortcode 支持好过 Gutenberg block。
- 想把工具放在 shortcode-ready widget 或 template area 中。
11. 调整 widget 样式
打开：
Settings > Astrology Suite > Style这个 tab 控制主要 widget 外观：
- Wrapper background
- Border visibility
- Form inputs
- Labels
- Buttons
- Focus states
- Result cards
- Past input controls
- Aspect interpretation modal colors
Ephemeris table 使用单独 tab：
Settings > Astrology Suite > Ephemeris Style它控制 table background、text、grid lines、header colors、current day styling、retrograde values、ingress values 和 station values。
在 frontend，ephemeris block 允许访客切换 month、year、zodiac mode、selected bodies 和 CSV export options。
12. 添加隐私说明
访客提交表单时，Astrology Suite 会通过 HTTPS 把计算请求发送到 FreeAstroAPI。
根据 block，request data 可能包括：
- Birth date and time
- Unknown birth time preference
- City, timezone, latitude, and longitude
- Selected chart and report options
- Selected astrology points
- Selected ephemeris month, year, zodiac mode, and bodies
默认情况下，插件不会把访客出生数据存到 WordPress。可选的 past inputs list 存在访客浏览器 local storage。
请在工具附近或隐私政策里添加简短说明。
13. 常见问题
表单提示访客没有访问权限
打开 Settings > Astrology Suite > API 并启用 public calculations。如果工具是私密的，请以有编辑权限的 WordPress 用户登录。
API key 字段保存后为空
这是正常的。留空表示继续使用已保存 key；粘贴新 key 会替换。
城市建议不出现
检查访客是否输入至少两个字符、API key 是否已保存、站点是否能访问 FreeAstroAPI。
可以试更具体的查询：
Paris, FRchart 不渲染
检查：
- API key 有效。
- birth form 使用了下拉中的城市建议。
- Custom Chart tab 没有无效 custom JSON。
- browser console 或 WordPress error log 没有 API error。
report 缺少 houses、ASC 或 MC
这些字段依赖出生时间。如果访客选择未知出生时间，插件会省略 time-dependent details，而不是显示不可靠占位。
样式修改没有显示
检查：
- 保存了正确 settings tab。
- page cache 已清理。
- theme CSS 没有覆盖插件样式。
- normal widgets 使用 Style，ephemeris tables 使用 Ephemeris Style。
14. 发布清单
- Install and activate the plugin.
- Save a valid FreeAstroAPI key.
- Enable public calculations if the page is public.
- Choose the frontend language.
- Add a chart, report, simple sign, or ephemeris block.
- Submit one real test request.
- Confirm city autocomplete works.
- Test the unknown birth time option.
- Confirm the chart or report output looks correct on desktop.
- Test the page on mobile.
- Add a privacy note.
- Clear your WordPress cache.
完成这些检查后，WordPress astrology starter kit 就可以给访客使用了。