Skip to content

Commit de5f961

Browse files
IEvangelistIEvangelist
committed
🤓 initial bits
1 parent 1a0e079 commit de5f961

File tree

335 files changed

+85797
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

335 files changed

+85797
-0
lines changed

‎.aspire/settings.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"appHostPath": "../src/apphost/Aspire.Dev.AppHost/Aspire.Dev.AppHost.csproj",
3+
"features": {
4+
"deployCommandEnabled": "true",
5+
"singlefileAppHostEnabled": "true"
6+
}
7+
}

‎.dockerignore‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
# Aspire.dev Docker ignore file
2+
# Exclude unnecessary files from Docker build context
3+
4+
# Node.js
5+
frontend/node_modules/
6+
frontend/dist/
7+
frontend/.astro/
8+
9+
# .NET
10+
**/bin/
11+
**/obj/
12+
**/.vs/
13+
**/.vscode/
14+
15+
# Git (keep .git for build context but exclude gitignore)
16+
.gitignore
17+
18+
# Other
19+
**/*.log
20+
**/*.tmp
21+
**/Thumbs.db
22+
**/.DS_Store
23+
24+
# Documentation
25+
*.md
26+
docs/
27+
28+
# Test files
29+
tests/
30+
**/*.test.*

‎.gitattributes‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
# Enforce LF line endings for text files
2+
# This forces Git to normalize line endings to LF on checkout.
3+
# See https://git-scm.com/docs/gitattributes for details.
4+
5+
# Default: treat all files as text and check out with LF
6+
* text=auto eol=lf
7+
8+
# Explicitly mark binary files to avoid corruption
9+
*.png binary
10+
*.jpg binary
11+
*.jpeg binary
12+
*.gif binary
13+
*.webp binary
14+
*.ico binary
15+
*.pdf binary
16+
*.zip binary
17+
*.gz binary
18+
*.tar binary
19+
*.exe binary
20+
*.dll binary
21+
*.so binary
22+
23+
# Common source/code/docs
24+
*.md text eol=lf
25+
*.mdx text eol=lf
26+
*.html text eol=lf
27+
*.css text eol=lf
28+
*.scss text eol=lf
29+
*.js text eol=lf
30+
*.jsx text eol=lf
31+
*.ts text eol=lf
32+
*.tsx text eol=lf
33+
*.json text eol=lf
34+
*.yml text eol=lf
35+
*.yaml text eol=lf
36+
*.cs text eol=lf
37+
*.xml text eol=lf
38+
*.py text eol=lf
39+
*.sh text eol=lf
40+
*.ps1 text eol=lf
41+
42+
# Generated data files - use 'ours' merge strategy to avoid conflicts
43+
# These files are regenerated at build time, so merge conflicts don't matter
44+
src/frontend/src/data/*.json merge=ours

‎.github/copilot-instructions.md‎

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# GitHub Copilot Instructions
2+
3+
This file provides context and instructions for GitHub Copilot when working on the Aspire documentation website.
4+
5+
## Repository Overview
6+
7+
This repository contains the source code for the official [Aspire documentation website](https://aspire.dev). Aspire is a modern application orchestration framework for building cloud-native distributed applications with .NET.
8+
9+
## Project Architecture
10+
11+
### Technology Stack
12+
- **Frontend**: Astro + Starlight (TypeScript-based static site generator)
13+
- **Orchestration**: .NET 9.0 with Aspire AppHost
14+
- **Styling**: CSS with Catppuccin themes (light/dark mode support)
15+
- **Content**: Markdown-based documentation with frontmatter
16+
17+
### Project Structure
18+
```
19+
src/
20+
├── apphost/ # Aspire orchestration
21+
│ └── Aspire.Dev.AppHost/ # .NET project for development orchestration
22+
├── frontend/ # Astro documentation site
23+
│ ├── src/
24+
│ │ ├── components/ # Reusable Astro components
25+
│ │ ├── content/docs/ # Main documentation (Markdown)
26+
│ │ ├── data/ # JSON data files (integrations, testimonials)
27+
│ │ ├── styles/ # CSS styling
28+
│ │ └── assets/ # Static assets (images, videos)
29+
│ ├── scripts/ # Build and data update scripts
30+
│ └── public/ # Static public assets
31+
```
32+
33+
## Development Workflow
34+
35+
### Local Development
36+
Always use Aspire orchestration for development:
37+
```bash
38+
cd src/apphost/Aspire.Dev.AppHost
39+
dotnet run
40+
```
41+
42+
This automatically:
43+
- Installs Node.js dependencies
44+
- Starts the Vite development server
45+
- Provides hot-reload capabilities
46+
- Opens the Aspire dashboard
47+
48+
### Build Process
49+
- **Frontend**: `npm run build` (in src/frontend/)
50+
- **AppHost**: `dotnet build` (in src/apphost/Aspire.Dev.AppHost/)
51+
52+
## Content Guidelines
53+
54+
### Documentation Structure
55+
- Use **Starlight** conventions for documentation
56+
- Content lives in `src/frontend/src/content/docs/`
57+
- Follow the existing directory structure:
58+
- `get-started/` - Getting started guides
59+
- `integrations/` - Integration documentation
60+
- `reference/` - API and technical references
61+
- `architecture/` - Architectural guidance
62+
- `community/` - Community resources
63+
64+
### Markdown Conventions
65+
- Use **clear, concise language**
66+
- Include **code examples** where appropriate
67+
- Add **alt text** for images
68+
- Use **proper heading hierarchy** (H1 for page title, H2 for main sections)
69+
- Include **frontmatter** for all pages:
70+
```yaml
71+
---
72+
title: Page Title
73+
description: Brief description of the page content
74+
---
75+
```
76+
77+
### Component Development
78+
- Use **TypeScript** for new components
79+
- Follow **Astro component guidelines**
80+
- Ensure components are **accessible and responsive**
81+
- Place components in `src/frontend/src/components/`
82+
83+
## Styling Guidelines
84+
85+
### Theme System
86+
- Uses **Catppuccin themes** (light: latte, dark: mocha)
87+
- Supports **automatic theme switching**
88+
- Custom CSS in `src/frontend/src/styles/`
89+
90+
### CSS Conventions
91+
- Use **CSS custom properties** for theming
92+
- Follow **responsive design principles**
93+
- Maintain **accessibility standards**
94+
- Use **semantic HTML** elements
95+
96+
### Fonts
97+
- Primary: **Outfit** (variable font)
98+
- Secondary: **Rubik** (variable font)
99+
100+
## Code Style
101+
102+
### TypeScript/JavaScript
103+
- Use **TypeScript** for type safety
104+
- Follow **Astro conventions**
105+
- Use **meaningful variable names**
106+
- Include **JSDoc comments** for complex functions
107+
108+
### .NET/C#
109+
- Follow **standard .NET conventions**
110+
- Use **meaningful class and method names**
111+
- Include **XML documentation** for public APIs
112+
- Target **.NET 9.0**
113+
114+
### Markdown
115+
- Use **fenced code blocks** with language specification
116+
- Include **proper alt text** for images
117+
- Use **descriptive link text**
118+
- Follow **consistent heading structure**
119+
120+
## Integration Data
121+
122+
### Automated Updates
123+
- Integration data is pulled from **NuGet API**
124+
- Updated via scripts: `npm run update:integrations`
125+
- GitHub stats updated via: `npm run update:github-stats`
126+
- Combined update: `npm run update:all`
127+
128+
### Data Structure
129+
- Integration data stored in `src/frontend/src/data/aspire-integrations.json`
130+
- Contains package information, descriptions, download counts, versions
131+
132+
## Common Tasks
133+
134+
### Adding New Documentation
135+
1. Create `.mdx` file in appropriate `src/frontend/src/content/docs/` subdirectory
136+
2. Add frontmatter with title and description
137+
3. Write content following markdown conventions
138+
4. Test locally using Aspire orchestration
139+
140+
### Creating Components
141+
1. Create `.astro` file in `src/frontend/src/components/`
142+
2. Use TypeScript for props and logic
143+
3. Follow accessibility guidelines
144+
4. Test responsive behavior
145+
146+
### Updating Styles
147+
1. Modify files in `src/frontend/src/styles/`
148+
2. Use CSS custom properties for theme compatibility
149+
3. Test in both light and dark modes
150+
4. Ensure responsive design
151+
152+
## Testing
153+
154+
### Local Validation
155+
- Run `dotnet run` in AppHost directory
156+
- Verify changes in browser
157+
- Test responsive design
158+
- Check both light/dark themes
159+
160+
### Build Validation
161+
- Frontend: `npm run build` should complete successfully
162+
- AppHost: `dotnet build` should complete without errors
163+
- CI will validate both builds automatically
164+
165+
## Terminology
166+
167+
### Preferred Terms
168+
- Use **"Aspire"** (not ".NET Aspire")
169+
- **"Integration"** for NuGet packages
170+
- **"Component"** for Astro components
171+
- **"AppHost"** for the orchestration project
172+
173+
### Avoid
174+
- Don't use deprecated API patterns
175+
- Avoid hard-coded URLs (use relative paths)
176+
- Don't include sensitive information in code
177+
178+
## File Naming Conventions
179+
180+
### Documentation Files
181+
- Use **kebab-case** for file names: `getting-started.mdx`
182+
- Match directory structure to navigation
183+
- Use descriptive, clear names
184+
185+
### Component Files
186+
- Use **PascalCase** for component names: `IntegrationCard.astro`
187+
- Include component type in name when helpful
188+
- Group related components in subdirectories
189+
190+
### Asset Files
191+
- Use **descriptive names** with appropriate extensions
192+
- Optimize images before committing
193+
- Use appropriate formats (WebP for photos, SVG for graphics)
194+
195+
## Dependencies
196+
197+
### Key Frontend Dependencies
198+
- `astro` - Core framework
199+
- `@astrojs/starlight` - Documentation theme
200+
- `@catppuccin/starlight` - Color theme
201+
- `mermaid` - Diagram support
202+
- `asciinema-player` - Terminal recording playback
203+
204+
### Key .NET Dependencies
205+
- `Aspire.Hosting.AppHost` - Core Aspire hosting
206+
- `Aspire.Hosting.NodeJs` - Node.js integration
207+
- `CommunityToolkit.Aspire.Hosting.NodeJS.Extensions` - Enhanced Node.js support
208+
209+
## Accessibility
210+
211+
### Requirements
212+
- Maintain **WCAG 2.1 AA compliance**
213+
- Include **proper alt text** for images
214+
- Use **semantic HTML** elements
215+
- Ensure **keyboard navigation** works
216+
- Test with **screen readers**
217+
218+
### Implementation
219+
- Use Astro's built-in accessibility features
220+
- Include **focus management** in interactive components
221+
- Provide **skip links** where appropriate
222+
- Use **sufficient color contrast**
223+
224+
## Performance
225+
226+
### Optimization Guidelines
227+
- Use **static site generation** where possible
228+
- Optimize **images and videos**
229+
- Minimize **JavaScript bundle size**
230+
- Implement **lazy loading** for heavy content
231+
- Use **appropriate caching strategies**
232+
233+
This repository demonstrates Aspire's capabilities by using Aspire itself for development orchestration - it's a great example of "dogfooding" the technology we're documenting.

‎.github/workflows/apphost-build.yml‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
name: AppHost Build
2+
3+
on:
4+
workflow_call:
5+
6+
permissions:
7+
contents: read
8+
9+
jobs:
10+
build:
11+
name: AppHost Build
12+
runs-on: ubuntu-latest
13+
steps:
14+
- uses: actions/checkout@v4
15+
16+
- uses: actions/setup-dotnet@v4
17+
with:
18+
global-json-file: global.json
19+
20+
- name: Restore
21+
run: cd src/apphost/Aspire.Dev.AppHost && dotnet restore
22+
23+
- name: Build
24+
run: cd src/apphost/Aspire.Dev.AppHost && dotnet build --no-restore --configuration Release
25+
26+
- name: Verify output
27+
run: |
28+
APPHOST_DLL=$(ls -1 src/apphost/Aspire.Dev.AppHost/bin/Release/*/Aspire.Dev.AppHost.dll 2>/dev/null | head -n 1)
29+
if [ -z "$APPHOST_DLL" ]; then
30+
echo "AppHost build failed - output assembly not found"
31+
ls -R src/apphost/Aspire.Dev.AppHost/bin/Release || true
32+
exit 1
33+
fi
34+
echo "Found $APPHOST_DLL"
35+
36+
- name: Upload artifact
37+
if: ${{ always() }}
38+
uses: actions/upload-artifact@v4
39+
with:
40+
name: apphost-release
41+
path: src/apphost/Aspire.Dev.AppHost/bin/Release/*/
42+
if-no-files-found: warn
43+
retention-days: 7

0 commit comments

Comments
 (0)