Skip to content

Commit 376b00e

Browse files
KebooKeboo
committed
Adds AI agent guidelines and vpk tooling options
Introduces a comprehensive `AGENTS.md` file, providing detailed guidance for AI coding agents on repository structure, development workflow, documentation conventions, and best practices. Updates several documentation pages to suggest using `dnx` for `vpk`, offering a flexible alternative to global installation and emphasizing version compatibility. Includes VS Code tasks to simplify local development setup, covering dependency installation and starting the Docusaurus development server. Refines `package-lock.json` with updated peer dependency declarations.
1 parent 83b4fbf commit 376b00e

File tree

9 files changed

+427
-1
lines changed

9 files changed

+427
-1
lines changed

‎.vscode/tasks.json‎

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,29 @@
1+
{
2+
"version": "2.0.0",
3+
"tasks": [
4+
{
5+
"label": "Start Docusaurus Dev Server",
6+
"type": "shell",
7+
"command": "npm install && npm run start",
8+
"isBackground": true,
9+
"problemMatcher": [
10+
"$tsc"
11+
],
12+
"group": "build"
13+
},
14+
{
15+
"label": "Install dependencies",
16+
"type": "shell",
17+
"command": "npm install",
18+
"isBackground": false,
19+
"group": "build"
20+
},
21+
{
22+
"label": "Start Docusaurus Dev Server",
23+
"type": "shell",
24+
"command": "npm run start",
25+
"isBackground": true,
26+
"group": "build"
27+
}
28+
]
29+
}

‎AGENTS.md‎

Lines changed: 311 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,311 @@
1+
# AGENTS.md
2+
3+
This file provides guidance for AI coding agents working with the Velopack documentation repository.
4+
5+
## Repository Overview
6+
7+
This repository contains the official documentation website for [Velopack](https://github.com/velopack/velopack), an installer and auto-update framework for cross-platform desktop applications. The site is built using [Docusaurus 3](https://docusaurus.io/), a modern static site generator.
8+
9+
**Live Site:** https://docs.velopack.io/
10+
11+
## Project Structure
12+
13+
```
14+
velopack.docs/
15+
├── docs/ # Main documentation content (MDX files)
16+
│ ├── index.mdx # Landing page
17+
│ ├── getting-started/ # Quick-start guides for different languages
18+
│ ├── integrating/ # SDK integration guides
19+
│ ├── packaging/ # Building releases with vpk
20+
│ ├── distributing/ # Deployment guides
21+
│ ├── migrating/ # Migration guides from other frameworks
22+
│ ├── reference/ # API reference (auto-generated)
23+
│ └── troubleshooting/ # FAQ and debugging guides
24+
├── blog/ # Blog posts
25+
├── src/ # Custom React components and CSS
26+
│ ├── components/ # Reusable React components
27+
│ ├── css/ # Custom stylesheets
28+
│ └── theme/ # Docusaurus theme customizations
29+
├── static/ # Static assets (images, logos, favicons)
30+
├── generator/ # C# project for generating API reference docs
31+
├── scripts/ # Build and deployment scripts
32+
├── docusaurus.config.ts # Main Docusaurus configuration
33+
├── sidebars.ts # Sidebar navigation structure
34+
└── package.json # Node.js dependencies and scripts
35+
```
36+
37+
## Key Technologies
38+
39+
- **Framework:** Docusaurus 3.8.1
40+
- **Runtime:** Node.js 18+
41+
- **Language:** TypeScript/JavaScript (site), MDX (documentation)
42+
- **Package Manager:** npm or yarn
43+
- **Reference Generator:** C# (.NET) for auto-generating API documentation
44+
45+
## Development Workflow
46+
47+
### Setup and Local Development
48+
49+
```bash
50+
# Install dependencies
51+
npm install
52+
53+
# Start development server (http://localhost:3000)
54+
npm run start
55+
56+
# Build for production
57+
npm run build
58+
59+
# Serve production build locally
60+
npm run serve
61+
```
62+
63+
### Available npm Scripts
64+
65+
- `npm run start` - Start Docusaurus dev server with hot reload
66+
- `npm run build` - Build static site to `build/` directory
67+
- `npm run serve` - Serve production build locally
68+
- `npm run clear` - Clear Docusaurus cache
69+
- `npm run typecheck` - Run TypeScript type checking
70+
71+
### VS Code Tasks
72+
73+
The repository includes preconfigured VS Code tasks:
74+
- **Start Docusaurus Dev Server** - Install dependencies and start dev server
75+
- **Install dependencies** - Run npm install
76+
77+
## Writing Documentation
78+
79+
### Content Format
80+
81+
Documentation is written in **MDX** (Markdown with JSX support), allowing you to:
82+
- Use standard Markdown syntax
83+
- Import and use React components
84+
- Add interactive examples and demos
85+
86+
### File Locations
87+
88+
- **Tutorials/Guides:** Place in appropriate subdirectory under `docs/`
89+
- **Blog Posts:** Add to `blog/` with YYYY-MM-DD format or subdirectories
90+
- **API Reference:** Auto-generated; don't edit directly (see Reference Generation below)
91+
92+
### MDX Frontmatter
93+
94+
Add metadata to docs using frontmatter:
95+
96+
```mdx
97+
---
98+
title: Page Title
99+
sidebar_label: Short Label
100+
sidebar_position: 1
101+
disable_comments: true
102+
---
103+
```
104+
105+
### Custom Components
106+
107+
The site includes custom React components in `src/components/`. Notable examples:
108+
- `<FancyStep>` - Styled step-by-step instructions
109+
- Standard Docusaurus components like `<DocCardList>`
110+
111+
## Reference Documentation Generation
112+
113+
API reference documentation is **auto-generated** from source code in the main Velopack repository.
114+
115+
### Generator Project
116+
117+
- **Location:** `generator/` directory
118+
- **Language:** C# (.NET)
119+
- **Purpose:** Extracts API documentation and generates MDX files
120+
121+
### Generated References
122+
123+
The following reference docs are auto-generated:
124+
- **C# API Reference:** `docs/reference/cs/`
125+
- **CLI Reference:** `docs/reference/cli/`
126+
- **C++ Reference:** `docs/reference/cpp/`
127+
- **JavaScript Reference:** `docs/reference/js/`
128+
129+
**⚠️ Important:** Do not manually edit files in these directories. They will be overwritten on the next generation run.
130+
131+
### Running the Generator
132+
133+
```bash
134+
cd generator
135+
dotnet run
136+
```
137+
138+
This updates all auto-generated reference documentation.
139+
140+
## Configuration Files
141+
142+
### docusaurus.config.ts
143+
144+
Main configuration including:
145+
- Site metadata (title, tagline, URL)
146+
- Theme configuration (navbar, footer, color modes)
147+
- Plugins (search, redirects, analytics)
148+
- Deployment settings
149+
150+
### sidebars.ts
151+
152+
Defines the documentation sidebar navigation structure. Docusaurus supports:
153+
- Auto-generated sidebars from directory structure
154+
- Manual sidebar configuration
155+
- Category grouping and custom ordering
156+
157+
## Common Tasks for AI Agents
158+
159+
### Adding New Documentation
160+
161+
1. Create MDX file in appropriate `docs/` subdirectory
162+
2. Add frontmatter with title and metadata
163+
3. Update `sidebars.ts` if manual ordering is needed
164+
4. Test locally with `npm run start`
165+
166+
### Updating Existing Documentation
167+
168+
1. Locate the MDX file in `docs/` directory
169+
2. Edit content (preserve frontmatter)
170+
3. Verify links and references are valid
171+
4. Check for broken Markdown links (enforced by `onBrokenMarkdownLinks: 'throw'`)
172+
173+
### Adding Blog Posts
174+
175+
1. Create directory in `blog/` with format: `YYYY-MM-DD-slug/`
176+
2. Add `index.md` or `index.mdx` with frontmatter
177+
3. Include author information in `blog/authors.yml`
178+
179+
### Modifying Site Configuration
180+
181+
1. Edit `docusaurus.config.ts` for site-wide settings
182+
2. Edit `sidebars.ts` for navigation structure
183+
3. Rebuild site to see changes
184+
185+
### Working with Components
186+
187+
1. Custom components go in `src/components/`
188+
2. Import in MDX files: `import Component from '@site/src/components/Component'`
189+
3. Theme overrides go in `src/theme/`
190+
191+
## Language Support
192+
193+
Velopack supports multiple programming languages. When adding documentation:
194+
195+
| Language | Status | Quick-Start Path | Reference Path |
196+
|-----------|--------|------------------|---------------|
197+
| C# | ✅ Ready | `docs/getting-started/csharp.mdx` | `docs/reference/cs/` |
198+
| Rust | ✅ Ready | `docs/getting-started/rust.mdx` | - |
199+
| JavaScript| ✅ Ready | `docs/getting-started/javascript.mdx` | `docs/reference/js/` |
200+
| C++ | ✅ Ready | `docs/getting-started/cpp.mdx` | `docs/reference/cpp/` |
201+
| Python | ✅ Ready | `docs/getting-started/python.mdx` | - |
202+
203+
## Important Conventions
204+
205+
### Linking
206+
207+
- **Internal docs:** Use relative paths: `[text](./page.mdx)` or `[text](../category/page.mdx)`
208+
- **External:** Use full URLs: `[text](https://example.com)`
209+
- **Broken links:** Will cause build to fail (enforced by config)
210+
211+
### Code Blocks
212+
213+
Use language-specific syntax highlighting:
214+
215+
````mdx
216+
```csharp
217+
// C# code example
218+
```
219+
220+
```bash
221+
# Shell commands
222+
```
223+
````
224+
225+
### Redirects
226+
227+
Old URLs are redirected in `docusaurus.config.ts`:
228+
229+
```typescript
230+
redirects: [
231+
{ from: '/old-path', to: '/new-path' },
232+
]
233+
```
234+
235+
Add new redirects when moving/renaming pages.
236+
237+
## Testing and Validation
238+
239+
### Before Committing
240+
241+
1. **Build succeeds:** `npm run build` (catches broken links, invalid config)
242+
2. **TypeScript checks:** `npm run typecheck`
243+
3. **Visual review:** Test on dev server (`npm run start`)
244+
4. **Search works:** Verify search index includes new content
245+
246+
### Build Enforcement
247+
248+
The configuration includes strict checks:
249+
- `onBrokenLinks: 'throw'` - Broken internal links fail the build
250+
- `onBrokenMarkdownLinks: 'throw'` - Invalid Markdown links fail the build
251+
252+
## Deployment
253+
254+
The site is deployed automatically via CI/CD. Deployment configuration is in `docusaurus.config.ts`:
255+
256+
```typescript
257+
url: 'https://docs.velopack.io/',
258+
baseUrl: '/',
259+
organizationName: 'velopack',
260+
projectName: 'velopack.docs',
261+
```
262+
263+
## Search
264+
265+
Search is powered by `@easyops-cn/docusaurus-search-local`:
266+
- Automatically indexes all documentation
267+
- Blog posts are excluded from indexing
268+
- Reference documentation is excluded via regex pattern
269+
- Search index is built during `npm run build`
270+
271+
## Contributing Guidelines
272+
273+
1. **Documentation edits** have "Edit this page" links pointing to GitHub
274+
2. **Reference pages** cannot be edited (auto-generated)
275+
3. Follow existing structure and conventions
276+
4. Test locally before committing
277+
5. Ensure builds pass without errors
278+
279+
## Resources
280+
281+
- **Docusaurus Docs:** https://docusaurus.io/docs
282+
- **Velopack Main Repo:** https://github.com/velopack/velopack
283+
- **Discord Community:** https://discord.gg/CjrCrNzd3F
284+
- **Live Documentation:** https://docs.velopack.io/
285+
286+
## Notes for AI Agents
287+
288+
1. **Do not edit auto-generated reference docs** - They're regenerated from source code
289+
2. **Respect the MDX format** - Maintain frontmatter and JSX syntax
290+
3. **Test builds locally** - Strict link checking will fail CI if broken
291+
4. **Follow existing patterns** - Match the style and structure of existing docs
292+
5. **Update sidebars.ts** - If adding new sections or changing navigation
293+
6. **Use TypeScript** - Configuration files use TypeScript for type safety
294+
7. **Check package.json** - For correct commands and dependencies
295+
8. **Preserve React components** - Don't convert JSX to plain Markdown if components are used
296+
297+
## Troubleshooting
298+
299+
### Common Issues
300+
301+
- **Build fails on broken links:** Check `npm run build` output for specific broken links
302+
- **Search not working:** Rebuild with `npm run build` to regenerate search index
303+
- **Dev server issues:** Clear cache with `npm run clear` and restart
304+
- **Missing dependencies:** Run `npm install` to ensure all packages are installed
305+
- **TypeScript errors:** Run `npm run typecheck` to see type issues
306+
307+
### Getting Help
308+
309+
- Check existing documentation structure for examples
310+
- Review Docusaurus documentation for framework-specific questions
311+
- Join Velopack Discord for project-specific questions

‎docs/distributing/github-actions.mdx‎

Lines changed: 12 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -112,3 +112,15 @@ permissions:
112112
vpk pack -u MyUniqueIdentifier -v ${{ steps.get-version.outputs.version }} -p publish
113113
vpk upload github --repoUrl https://github.com/${{ github.repository }} --publish --releaseName "MyProject ${{ steps.get-version.outputs.version }}" --tag v${{ steps.get-version.outputs.version }}
114114
```
115+
116+
Alternatively, you can run `vpk` without installing it globally using the [`dnx`](https://learn.microsoft.com/dotnet/core/tools/dotnet-tool-exec?WT.mc_id=DT-MVP-5003472) command. Make sure to specify the same version as the Velopack package referenced in your application:
117+
118+
```yml
119+
- name: Create Velopack Release
120+
run: |
121+
dnx vpk --version 1.0.0 download github --repoUrl https://github.com/${{ github.repository }}
122+
dnx vpk --version 1.0.0 pack -u MyUniqueIdentifier -v ${{ steps.get-version.outputs.version }} -p publish
123+
dnx vpk --version 1.0.0 upload github --repoUrl https://github.com/${{ github.repository }} --publish --releaseName "MyProject ${{ steps.get-version.outputs.version }}" --tag v${{ steps.get-version.outputs.version }}
124+
```
125+
126+
Replace `1.0.0` with the version of the Velopack package you're using in your application.

‎docs/getting-started/content/_install-vpk.mdx‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,4 +5,15 @@ You can install the .NET SDK from the [.NET download page](https://dotnet.micros
55
Once .NET is installed, you can install `vpk` by running:
66
```cmd
77
dotnet tool install -g vpk
8-
```
8+
```
9+
10+
:::tip
11+
It's recommended to use the same version of `vpk` as the Velopack package referenced in your application to ensure compatibility.
12+
:::
13+
14+
Alternatively, you can run `vpk` without installing it globally using the [`dnx`](https://learn.microsoft.com/en-us/dotnet/core/tools/dotnet-tool-exec?WT.mc_id=DT-MVP-5003472) command:
15+
```cmd
16+
dnx vpk --version 1.0.0
17+
```
18+
19+
Replace `1.0.0` with the version of the Velopack package you're using in your application.

‎docs/getting-started/rust.mdx‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,6 +52,17 @@ dotnet tool update -g vpk
5252
```
5353
***Note: you must have the .NET Core SDK 8 installed to use and update `vpk`***
5454

55+
:::tip
56+
It's recommended to use the same version of `vpk` as the Velopack package referenced in your application to ensure compatibility.
57+
:::
58+
59+
Alternatively, you can run `vpk` without installing it globally using the [`dnx`](https://learn.microsoft.com/dotnet/core/tools/dotnet-tool-exec?WT.mc_id=DT-MVP-5003472) command:
60+
```sh
61+
dnx vpk --version 1.0.0
62+
```
63+
64+
Replace `1.0.0` with the version of the Velopack package you're using in your application.
65+
5566
6. Package your Velopack release / installers:
5667
```sh
5768
vpk pack -u MyAppUniqueId -v 1.0.0 -p /target/release -e myexename.exe

0 commit comments

Comments
 (0)