Skip to content

Commit 563b153

Browse files
ngnijlandngnijland
committed
chore: add docs, blog and features description to AGENTS file
1 parent b4e27fb commit 563b153

File tree

2 files changed

+126
-77
lines changed

2 files changed

+126
-77
lines changed

‎docs/AGENTS.md‎

Lines changed: 123 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -16,3 +16,126 @@ npm run knip # Unused files and dependencies
1616
If `format:check` fails, run `npx prettier --write .` and commit the result.
1717

1818
All five commands must exit with code 0 before you push.
19+
20+
## Content Authoring Guide
21+
22+
### Features
23+
24+
Every `.md` file inside `src/collections/feature` will be handled as a feature. Features with `showOnHomepage: true` are displayed on the landing page. Features can also be linked to a feature page via the `featurePage` field, grouping them into category pages at `/features/[slug]`.
25+
26+
The Markdown files are separated into two sections:
27+
28+
- Frontmatter YAML containing all data other than the content following a set data structure.
29+
- Content; allows writing markdown that gets converted into HTML when the project is built.
30+
31+
The frontmatter schema is as follows:
32+
33+
```typescript
34+
const alignment = z.enum(["left", "right", "full-width"]);
35+
const columnSpan = z.union([z.literal(6), z.literal(8), z.literal(12)]);
36+
37+
type Alignment = "left" | "right" | "full-width";
38+
type ColumnSpan = 6 | 8 | 12;
39+
40+
type Image = {
41+
type: "image";
42+
/** Path to asset INSIDE src folder */
43+
path: string;
44+
alt: string;
45+
/** Optional caption to be shown underneath the asset (supports inline markdown) */
46+
caption?: string;
47+
/** Placement of the asset related to the content */
48+
alignment: Alignment;
49+
/** Width of the asset. Choose between 6 (50%), 8 (66.67%), or 12 (100%) */
50+
columnSpan: ColumnSpan;
51+
};
52+
53+
type Video = {
54+
type: "video";
55+
/** Path to asset in public folder */
56+
path: string;
57+
alt: string;
58+
caption?: string;
59+
alignment: Alignment;
60+
columnSpan: ColumnSpan;
61+
};
62+
63+
type Feature = {
64+
name: string;
65+
/** Whether this feature is shown on the homepage */
66+
showOnHomepage: boolean; // defaults to false
67+
tagLine?: string;
68+
/** Path to related documentation */
69+
docPath?: string;
70+
/** WordPress blog post ID for linking to the related blog post */
71+
blogId?: number;
72+
/** Fragment identifier appended to the blog post URL */
73+
blogFragment?: string;
74+
/** YouTube video URL */
75+
youtubeLink?: string; // must be a valid URL
76+
/** Links this feature to a feature page category */
77+
featurePage?:
78+
| "accessibility"
79+
| "app-actions"
80+
| "build-insights"
81+
| "design-comparison"
82+
| "networking"
83+
| "screenshots-recordings"
84+
| "simulator-camera"
85+
| "status-bar"
86+
| "user-defaults-editor";
87+
/** Asset can be an image or a video */
88+
asset: Image | Video;
89+
};
90+
```
91+
92+
**NOTE:** Video assets need to be placed in the `public/` folder, while image assets need to be placed inside the `src/` folder. Assets in the `public/` folder won't be processed during the building of the project. Astro does not support video processing. We should take care of that ourselves (filesize, quality and resolution). For images this is done automatically. Feel free to use big image assets.
93+
94+
An example feature:
95+
96+
```md
97+
---
98+
showOnHomepage: true
99+
name: "Quick Actions"
100+
featurePage: "app-actions"
101+
asset:
102+
type: "video"
103+
path: "/features/quick-actions.mp4"
104+
alt: "RocketSim panel that shows configurable actions for locations, push notifications and deeplinks."
105+
alignment: "right"
106+
columnSpan: 6
107+
---
108+
109+
**Configurable actions** for Deeplinks (Universal Links), Push Notifications, locations, permissions, and quick state resets.
110+
111+
- **Bundle Identifier based:** actions automatically show up for recent builds
112+
- Quickly test **Locations, Push Notifications, and Deeplinks**
113+
- Use **Reset Keychain** to clear stubborn authentication state faster
114+
```
115+
116+
### Feature Pages
117+
118+
Feature pages are category pages that group related features together. They live in `src/collections/feature-page/` and are rendered at `/features/[slug]`. Each feature page has a hero section and an optional bento grid layout.
119+
120+
The available feature page slugs are: `accessibility`, `app-actions`, `build-insights`, `design-comparison`, `networking`, `screenshots-recordings`, `simulator-camera`, `status-bar`, `user-defaults-editor`.
121+
122+
### Documentation
123+
124+
Product documentation is powered by [Starlight](https://starlight.astro.build/) (an Astro integration) and lives in `src/content/docs/docs/`. Pages use `.md` or `.mdx` format with standard Starlight frontmatter (`title`, `description`).
125+
126+
The sidebar structure is defined in `astro.config.ts` under `starlight.sidebar`. Some sections use `autogenerate` (auto-discovers pages in a directory), others list pages explicitly by `slug` or `link`.
127+
128+
Current sidebar sections: Getting Started, Screenshots & Recordings, Simulator Camera, Status Bar, Design Comparison, App Actions, Networking, Build Insights, Accessibility, Agentic Development, User Defaults Editor, Settings, Support.
129+
130+
Images for a doc page should be placed in a subfolder next to the `.md`/`.mdx` file and referenced with relative paths (e.g., `![Alt](./subfolder/image.png)`).
131+
132+
Available shortcodes (auto-imported, no import statement needed):
133+
- `<Youtube id="..." title="..." />` — embeds a YouTube video
134+
- `<Accordion>` — collapsible content
135+
- `<Tweet />` — embedded tweet
136+
137+
The documentation also generates `llms.txt` and `llms-full.txt` files via the `starlight-llms-txt` plugin for LLM consumption.
138+
139+
### Blog
140+
141+
The blog is powered by a headless WordPress instance. Blog posts are fetched at build time and statically rendered.

‎docs/README.md‎

Lines changed: 3 additions & 77 deletions
Original file line numberDiff line numberDiff line change
@@ -26,85 +26,11 @@ npm run dev
2626

2727
This starts your app in development mode, rebuilding assets on file changes.
2828

29-
## Features
30-
31-
Every `.md` file inside `src/collections/feature` will be handled as a feature. For now the only place they are used in on our landing page. Every file is converted into a section showcasing the particular feature.
32-
33-
The Markdown files are separated into two sections:
34-
35-
- Frontmatter YAML containing all data other than the content following a set data structure.
36-
- Content; allows writing markdown that gets converted into HTML when the project is build
37-
38-
The frontmatter schema is as follows:
39-
40-
```typescript
41-
const alignment = z.enum(["left", "right", "full-width"]);
42-
const columnSpan = z.union([z.literal(6), z.literal(8)]);
43-
44-
type Alignment = "left" | "right" | "full-width";
45-
type columnSpan = 6 | 8;
46-
47-
type Photo = {
48-
type: "photo";
49-
/** Path to asset INSIDE src folder */
50-
path: string;
51-
alt: string;
52-
/** Optional caption to be shown underneath the asset (supports inline markdown) */
53-
caption?: string;
54-
/** Placement of the asset related to the content */
55-
alignment: Alignment;
56-
/** Width of the asset. Choose between 6 (50%) or 8 (66.67%) */
57-
columnSpan: ColumnSpan;
58-
};
59-
60-
type Video = {
61-
type: "video";
62-
/** Path to asset public folder */
63-
path: string;
64-
alt: string;
65-
caption?: string;
66-
alignment: Alignment;
67-
columnSpan: ColumnSpan;
68-
};
69-
70-
type Feature = {
71-
name: string;
72-
tagLine?: string;
73-
/** Asset can be a photo or a video */
74-
asset: Photo | Video;
75-
/** Order the features will be shown on the landing page */
76-
sortOrder: number;
77-
};
78-
```
79-
80-
**NOTE:** Video assets need to be placed in the `public/` folder, while image assets need to be placed inside the `src/` folder. Assets in the `public/` folder won't be processed during the building of the project. Astro does not support video processing. We should take care of that ourselves (filesize, quality and resolution). For images this is done automatically. Feel free to use big image assets.
81-
82-
An example feature:
83-
84-
```md
85-
---
86-
name: "Quick Actions"
87-
asset:
88-
type: "image"
89-
path: "../../assets/features/quick-actions.jpg"
90-
alt: "RocketSim panel that shows configurable actions for locations, push notifications and deeplinks."
91-
alignment: "right"
92-
columnSpan: 6
93-
sortOrder: 3
94-
---
95-
96-
**Configurable actions** for Deeplinks (Universal Links) and Push Notifications. Control permissions.
97-
98-
- **Bundle Identifier based:** actions automatically show up for recent builds
99-
- Quickly test **Locations, Push Notifications, and Deeplinks**
100-
- **Grant, revoke, or reset permissions** like photo and location access, allowing you to quicker test related implementations
101-
```
102-
103-
## Blog
29+
## Content
10430

105-
The blog is powered by a headless WordPress instance. The blog posts are fetched at build time and statically rendered.
31+
Features live in `src/collections/feature/`, feature pages in `src/collections/feature-page/`, and the blog is powered by a headless WordPress instance. See [AGENTS.md](./AGENTS.md) for the full content authoring guide (schemas, examples, and conventions).
10632

107-
### Local development
33+
## Blog — Local Development
10834

10935
Make sure Docker is running.
11036

0 commit comments

Comments
 (0)