# Help Extras Website Plan

## Goal

Bring the remaining Help Extras content into The HyperCard Center:

- Glossary of Terms
- Troubleshooting
- Helpful Tips

The source Markdown already lives in the nested `store/` repository under `store/HelpExtras/`. Placeholders have already been integrated into HyperTalk Reference card rendering, so this plan reuses that work where possible and adds first-class pages for the other Help Extras sections.

## Current State

- `pages/HyperTalkReference-read.php` already parses front-matter Markdown and expands `[ph:name]` references by appending matching Placeholder entries from `store/HelpExtras/Placeholders/`.
- `store/HelpExtras/Placeholders/` is used as supporting content, not as a public browseable stack.
- `store/HelpExtras/Glossary/`, `store/HelpExtras/Tips/`, and `store/HelpExtras/Troubleshooting/` contain the new public content.
- Each section has an `-Index.md` file plus one Markdown file per card.
- The current Markdown format is consistent with the HyperTalk Reference reader: YAML-ish front matter with `title` and `card_id`, followed by simple Markdown.
- Routing currently only knows about `/`, `/sitemap`, `/editor`, `/goto`, and `/HyperTalkReference...`.

## Proposed URL Structure

Use a single Help Extras stack with stable section routes:

- `/HelpExtras`
- `/HelpExtras/Glossary`
- `/HelpExtras/Glossary/{card}`
- `/HelpExtras/Tips`
- `/HelpExtras/Tips/{card}`
- `/HelpExtras/Troubleshooting`
- `/HelpExtras/Troubleshooting/{card}`

Keep filenames as URL slugs without the `.md` extension. Examples:

- `/HelpExtras/Glossary/active-text`
- `/HelpExtras/Tips/Properties-of-the-Variable-Watcher`
- `/HelpExtras/Troubleshooting/Wheres-the-field`

Add legacy numeric redirects later if useful:

- `/HelpExtras/{card_id}` can scan the section indexes and redirect to the matching canonical route.

## Implementation Steps

### 1. Extract Shared Markdown Rendering

Move the useful parts of `md_format_content()` and `format_link_ph_callback()` out of `pages/HyperTalkReference-read.php` into a shared include, likely `code/markdown.inc.php` or `code/content.inc.php`.

The shared parser should:

- Parse front matter into a `$header` array.
- Render headings, paragraphs, lists, inline code, fenced code blocks, links, and `[[image:%stack%/...]]`.
- Keep placeholder collection behavior for `[ph:name]`, but make it optional through an options array.
- Return both the parsed header and rendered body.

Reason: Help Extras pages and HyperTalk pages use the same Markdown shape. Keeping one parser prevents formatting drift.

### 2. Add Help Extras Section Metadata

Create a small helper that describes the public Help Extras sections:

```php
function help_extras_sections() {
  return [
    'Glossary' => [
      'title' => 'Glossary of Terms',
      'folder' => 'Glossary',
      'singular' => 'definition',
    ],
    'Tips' => [
      'title' => 'Helpful Tips',
      'folder' => 'Tips',
      'singular' => 'tip',
    ],
    'Troubleshooting' => [
      'title' => 'Troubleshooting',
      'folder' => 'Troubleshooting',
      'singular' => 'problem',
    ],
  ];
}
```

Also add helper functions to:

- Build a section path under `store/HelpExtras/{folder}`.
- Read a card by slug.
- List section cards by scanning `*.md` and excluding `-Index.md`.
- Sort cards by rendered title, with an override if the source index later grows explicit ordering.
- Find a card by `card_id` if numeric redirects are added.

### 3. Add Routes

Extend `code/route.inc.php`:

- `/HelpExtras` includes a new overview page.
- `/HelpExtras/{section}` includes a section index page.
- `/HelpExtras/{section}/{card}` includes a card reader page.

Validate route pieces with `basename()` and a whitelist from `help_extras_sections()` so arbitrary directories cannot be read.

Add `/goto` support for `stack=HelpExtras` if the new pages include a destination menu.

### 4. Add Page Templates

Add these pages:

- `pages/HelpExtras-index.php`
- `pages/HelpExtras-section.php`
- `pages/HelpExtras-read.php`

`HelpExtras-index.php` should introduce the stack using the same voice as the original Help Extras overview:

- Tips
- Troubleshooting
- Glossary of Terms
- HyperTalk Placeholders

Placeholders can be linked as a supporting/reference section or deferred if we do not want a public Placeholder index yet.

`HelpExtras-section.php` should:

- Render the section title.
- Render the section `-Index.md` intro text.
- List every card in that section.
- Use compact icon/table layout in retro mode and Bootstrap-friendly layout in modern mode.

`HelpExtras-read.php` should:

- Render breadcrumbs: Home -> Help Extras -> Section -> Card.
- Render the selected Markdown card.
- Include a right-side section list in modern mode, matching the HyperTalk Reference pattern.
- Include a simple destination selector or previous/index/next links in retro mode.

### 5. Navigation Integration

Update existing navigation surfaces:

- Add Help Extras to the Home Stack (`pages/home.php`) next to HyperTalk Reference.
- Add Help Extras sections to `pages/sitemap.php`.
- Consider adding a footer or header link to Help Extras only if it fits both retro and modern layouts.

Preserve the old HyperCard help-stack feeling. This should feel like another stack, not a redesigned documentation portal.

### 6. Contextual Links From HyperTalk Reference

After the base Help Extras pages work, wire contextual references from HyperTalk cards:

- Replace plain "Click Tips..." text with links when there is an obvious target.
- Start with exact known mappings found in current content:
  - `variableWatcher` -> `/HelpExtras/Tips/Properties-of-the-Variable-Watcher`
  - `messageWatcher` -> `/HelpExtras/Tips/Properties-of-the-Message-Watcher`
  - `hilite` -> `/HelpExtras/Tips/List-of-synonyms`
  - `Referring-to-objects` -> `/HelpExtras/Tips/List-of-synonyms`
  - operator precedence pages -> `/HelpExtras/Tips/Operator-precedence`
- Use an explicit map rather than fuzzy string matching for the first pass.

Do not block the initial launch on contextual linking. The first milestone is browseable Help Extras content.

### 7. Glossary Active Text

The original Help Extras stack allowed active text in Glossary and Placeholder entries. For the website:

- Support explicit Markdown links if the source has them.
- Add a second pass that recognizes glossary terms only when the source marks them or when we have a safe explicit map.
- Avoid auto-linking every matching word globally; that can create noisy and incorrect links.

### 8. Placeholder Handling

Keep the current HyperTalk behavior:

- `[ph:name]` renders inline as italic text.
- Referenced placeholder definitions append below the HyperTalk card.

For Help Extras pages:

- Render `[ph:name]` inline the same way.
- Decide per page whether to append placeholder definitions. Tips pages such as Properties of the Variable Watcher use `[ph:posInteger]`; appending definitions there is probably helpful and consistent.

### 9. Error Handling

For missing or invalid section/card routes:

- Include `pages/notfound.php`.
- Do not expose filesystem paths.
- Log missing content with enough context to repair bad links.

When a Markdown file has no `title`, fall back to a title derived from the filename.

### 10. Testing Checklist

Manual routes to verify:

- `/HelpExtras`
- `/HelpExtras/Glossary`
- `/HelpExtras/Glossary/active-text`
- `/HelpExtras/Tips`
- `/HelpExtras/Tips/Properties-of-the-Variable-Watcher`
- `/HelpExtras/Troubleshooting`
- `/HelpExtras/Troubleshooting/Wheres-the-field`
- The same pages after switching `?view=modern` and `?view=retro`
- Existing `/HyperTalkReference` pages, especially pages that append Placeholders

Implementation checks:

- No warnings for missing `$_REQUEST`, `$_COOKIE`, or undefined route variables.
- No raw Markdown front matter appears in rendered pages.
- Lists and code blocks render correctly.
- Section sidebars do not break modern mobile layout.
- Retro pages remain usable in narrow fixed-width layout.
- `store/` remains clean unless content edits are intentionally made there.

### 11. Suggested Order Of Work

1. Extract shared Markdown/parser helpers.
2. Add Help Extras metadata and file-reading helpers.
3. Add Help Extras routes.
4. Build the overview, section index, and reader pages.
5. Add Home Stack and sitemap links.
6. Test modern and retro rendering.
7. Add explicit contextual links from HyperTalk Reference to Tips.
8. Decide whether Placeholder index pages should become public browseable pages.

## Open Decisions

- Should `/HelpExtras/Placeholders` become a public browseable section, or remain supporting content appended to related cards?
- Should section ordering follow filename/title sorting, or should we generate/use explicit topic indexes from the original stack?
- Should old Help Extras `card_id` links be supported immediately?
- Should contextual "Click Tips" links appear inline, as a related-help box, or both?