135 lines
2.8 KiB
Markdown
135 lines
2.8 KiB
Markdown
# radie-help
|
|
|
|
Content-driven help site built with Astro and MDX.
|
|
|
|
## Requirements
|
|
|
|
- `node >= 22.12.0`
|
|
- `npm`
|
|
|
|
## Basic Setup
|
|
|
|
1. Install dependencies:
|
|
|
|
```sh
|
|
npm install
|
|
```
|
|
|
|
2. Start the local dev server:
|
|
|
|
```sh
|
|
npm run dev
|
|
```
|
|
|
|
3. Open `http://localhost:4321`.
|
|
|
|
## Available Commands
|
|
|
|
| Command | What it does |
|
|
| --- | --- |
|
|
| `npm run dev` | Start the local Astro dev server |
|
|
| `npm run build` | Build the site for production |
|
|
| `npm run preview` | Preview the production build locally |
|
|
|
|
## How Content Works
|
|
|
|
- Each top-level folder inside `src/content/` is a content section.
|
|
- The current site includes sections for `src/content/website/` and `src/content/avatar-items/`.
|
|
- Files in a section can be `.md` or `.mdx`.
|
|
- Each content file must include frontmatter with:
|
|
|
|
```md
|
|
---
|
|
title: Page Title
|
|
description: Short summary
|
|
---
|
|
```
|
|
|
|
- `index.mdx` becomes the landing page for that section.
|
|
Example: `src/content/website/index.mdx` maps to `/website`
|
|
- Any other file becomes a subpage under that section.
|
|
Example: `src/content/website/registration.mdx` maps to `/website/registration`
|
|
|
|
## Adding A New Content Subpage
|
|
|
|
To add a new page inside an existing section:
|
|
|
|
1. Create a new `.md` or `.mdx` file in the relevant folder under `src/content/`.
|
|
2. Add the required frontmatter:
|
|
|
|
```md
|
|
---
|
|
title: New Page
|
|
description: What this page covers
|
|
---
|
|
```
|
|
|
|
3. Add the page body content.
|
|
|
|
Example:
|
|
|
|
```text
|
|
src/content/website/account-recovery.mdx
|
|
```
|
|
|
|
This page will be available at:
|
|
|
|
```text
|
|
/website/account-recovery
|
|
```
|
|
|
|
## Adding A New Content Section
|
|
|
|
If you want a new group of subpages, create a new folder in `src/content/` and then register it once in `src/config/content.ts`.
|
|
|
|
### 1. Create the folder and files
|
|
|
|
Example:
|
|
|
|
```text
|
|
src/content/mobile-app/
|
|
├── index.mdx
|
|
└── notifications.mdx
|
|
```
|
|
|
|
`index.mdx` should describe the section landing page. Any additional files become subpages for that section.
|
|
|
|
### 2. Update `src/config/content.ts`
|
|
|
|
Add a new entry to `contentSections`:
|
|
|
|
```ts
|
|
export const contentSections = {
|
|
website: {
|
|
dir: "website",
|
|
},
|
|
avatarItems: {
|
|
dir: "avatar-items",
|
|
},
|
|
mobileApp: {
|
|
dir: "mobile-app",
|
|
},
|
|
};
|
|
```
|
|
|
|
The object key is the section route and Astro collection name. The `dir` value is the folder under `src/content/`.
|
|
|
|
### 3. Run the site locally
|
|
|
|
```sh
|
|
npm run dev
|
|
```
|
|
|
|
Verify that:
|
|
|
|
- the new section appears on the home page
|
|
- the section index page loads
|
|
- the new subpages resolve under the expected URL path
|
|
|
|
## Contributor Notes
|
|
|
|
- Keep one topic per file.
|
|
- Use `index.mdx` only for a section landing page.
|
|
- Prefer lowercase, hyphenated filenames for clean URLs.
|
|
- If you create a new top-level content folder, register it in `src/config/content.ts`. `src/content.config.ts`, navigation, and routing derive from that registry.
|